API

Introduction to Contacts API

The Contacts API allows you to manage contacts within your organization. All requests require authentication using your API key.

Authentication

All requests require the following headers:

  • x-api-key: Your API key
  • x-organization-id: Your organization ID

Base URL

https://api.agentvoice.com/api

List All Contacts

GET /contacts

Description: Retrieves all contacts for your organization.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]

Response:

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "company": "Example Corp",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z",
    "last_task_run": null,
    "total_tasks_run": 0,
    "organization_id": "uuid",
    "crm_id": "CRM123",
    "crm_source": "salesforce"
  },
  // More contacts...
]

Get a Specific Contact

GET /contacts/:id

Description: Retrieves a specific contact by ID.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]

Parameters:

  • id: The UUID of the contact

Response:

{
  "id": "uuid",
  "user_id": "uuid",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "company": "Example Corp",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "last_task_run": null,
  "total_tasks_run": 0,
  "organization_id": "uuid",
  "crm_id": "CRM123",
  "crm_source": "salesforce"
}

Get a Contact by CRM ID

GET /contacts/crm/lookup

Description: Retrieves a contact by CRM ID and source.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]

Query Parameters:

  • crm_id: The ID of the contact in the CRM system
  • crm_source: The source CRM system (e.g., “salesforce”, “hubspot”)

Example:

GET /contacts/crm/lookup?crm_id=CRM123&crm_source=salesforce

Response:

{
  "id": "uuid",
  "user_id": "uuid",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "company": "Example Corp",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "last_task_run": null,
  "total_tasks_run": 0,
  "organization_id": "uuid",
  "crm_id": "CRM123",
  "crm_source": "salesforce"
}

Create a Contact

POST /contacts

Description: Creates a new contact. The contact will be associated with the authenticated user.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]
  • Content-Type: application/json

Request Body:

{
  "first_name": "Jane",      // Required unless crm_id and crm_source are provided
  "last_name": "Smith",      // Optional
  "email": "jane@example.com", // Optional
  "phone": "+1987654321",    // Optional
  "company": "New Corp",     // Optional
  "crm_id": "CRM456",        // Optional - ID in external CRM system
  "crm_source": "hubspot"    // Optional - Source CRM system (required if crm_id is provided)
}

Response:

{
  "id": "uuid",
  "user_id": "uuid",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "phone": "+1987654321",
  "company": "New Corp",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "last_task_run": null,
  "total_tasks_run": 0,
  "organization_id": "uuid",
  "crm_id": "CRM456",
  "crm_source": "hubspot"
}

Update a Contact

PATCH /contacts/:id

Description: Updates specific fields of a contact. Only include the fields you want to update.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]
  • Content-Type: application/json

Parameters:

  • id: The UUID of the contact

Request Body:

{
  "first_name": "Janet",     // Optional
  "last_name": "Smith",      // Optional
  "email": "janet@example.com", // Optional
  "phone": "+1987654321",    // Optional
  "company": "Updated Corp", // Optional
  "crm_id": "CRM789",        // Optional
  "crm_source": "zoho"       // Optional (required if crm_id is provided)
}

Response:

{
  "id": "uuid",
  "user_id": "uuid",
  "first_name": "Janet",
  "last_name": "Smith",
  "email": "janet@example.com",
  "phone": "+1987654321",
  "company": "Updated Corp",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-02T00:00:00Z",
  "last_task_run": null,
  "total_tasks_run": 0,
  "organization_id": "uuid",
  "crm_id": "CRM789",
  "crm_source": "zoho"
}

Delete a Contact

DELETE /contacts/:id

Description: Permanently deletes a contact.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]

Parameters:

  • id: The UUID of the contact

Response:

{
  "message": "Contact deleted successfully"
}

CRM Webhook Overview

The CRM Webhook API allows external CRM systems to synchronize contacts with AgentVoice.

Authentication

All webhook requests require the following headers:

  • x-api-key: Your API key
  • x-organization-id: Your organization ID

CRM Webhook Endpoint

POST /api/webhook/crm

Description: Receives contact data from external CRM systems and creates or updates contacts accordingly.

Request Headers:

  • x-api-key: [Your API Key]
  • x-organization-id: [Your Organization ID]
  • Content-Type: application/json

Request Body:

{
  "source": "salesforce",  // Required - CRM system identifier
  "data": {                // Required - Contact data
    "crm_id": "CRM123",    // Required - Unique ID in the CRM system
    "first_name": "John",  // Optional (default: "Unknown" if not provided)
    "last_name": "Doe",    // Optional
    "email": "john@example.com", // Optional
    "phone": "+1234567890",      // Optional
    "company": "Example Corp"    // Optional
  }
}

Field Mapping Notes:

The webhook supports various field naming conventions from different CRM systems:

  • first_name / firstName / name
  • last_name / lastName
  • email / emailAddress
  • phone / phoneNumber
  • company / companyName / organization

Response (Contact Created):

{
  "message": "Contact created successfully",
  "contact": {
    "id": "uuid",
    "user_id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "company": "Example Corp",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z",
    "organization_id": "uuid",
    "crm_id": "CRM123",
    "crm_source": "salesforce"
  }
}

Response (Contact Updated):

{
  "message": "Contact updated successfully",
  "contact": {
    "id": "uuid",
    "user_id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "company": "Example Corp",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-02T00:00:00Z",
    "organization_id": "uuid",
    "crm_id": "CRM123",
    "crm_source": "salesforce"
  }
}

API Error Responses

The API returns standard HTTP status codes:

  • 400 Bad Request: Missing required fields
  • 401 Unauthorized: Invalid API key or organization ID
  • 404 Not Found: Contact not found
  • 409 Conflict: A contact with this CRM ID already exists (unique constraint violation)
  • 500 Internal Server Error: Server-side error

Example error response:

{
  "error": "Invalid payload: source, data, and data.crm_id are required"
}

On this page