Contacts API

The Contacts API allows you to programmatically manage and access user contact information collected by your Nexvio.ai chatbots.

Get Contacts

Retrieve a list of contacts collected by your chatbots.

GET https://api.nexvio.ai/v1/contacts

Headers

Name	Required	Description
`Authorization`	Yes	Your API key in the format: `Bearer YOUR_API_KEY`

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of contacts to return. Default: 100, Max: 500
`offset`	integer	No	Number of contacts to skip. Used for pagination. Default: 0
`chatbotId`	string	No	Filter contacts by chatbot ID
`search`	string	No	Search term to filter contacts by name or email
`sortBy`	string	No	Field to sort by: `createdAt`, `name`, `email`. Default: `createdAt`
`sortOrder`	string	No	Sort order: `asc` or `desc`. Default: `desc`

Response

{
  "status": "success",
  "data": {
    "contacts": [
      {
        "id": "contact_123abc",
        "chatbotId": "chatbot_456def",
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+15551234567",
        "metadata": {
          "company": "Acme Inc",
          "role": "Manager"
        },
        "createdAt": "2023-07-15T14:22:31Z",
        "updatedAt": "2023-07-15T14:22:31Z"
      },
      // More contacts...
    ],
    "total": 142,
    "limit": 100,
    "offset": 0
  }
}

Get Contact by ID

Retrieve a specific contact by ID.

GET https://api.nexvio.ai/v1/contacts/{contactId}

Headers

Name	Required	Description
`Authorization`	Yes	Your API key in the format: `Bearer YOUR_API_KEY`

Path Parameters

Parameter	Type	Required	Description
`contactId`	string	Yes	The ID of the contact to retrieve

Response

{
  "status": "success",
  "data": {
    "contact": {
      "id": "contact_123abc",
      "chatbotId": "chatbot_456def",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+15551234567",
      "metadata": {
        "company": "Acme Inc",
        "role": "Manager"
      },
      "conversations": [
        {
          "id": "conv_789ghi",
          "startedAt": "2023-07-15T14:20:00Z",
          "lastMessageAt": "2023-07-15T14:22:31Z"
        }
      ],
      "createdAt": "2023-07-15T14:22:31Z",
      "updatedAt": "2023-07-15T14:22:31Z"
    }
  }
}

Create Contact

Create a new contact manually.

POST https://api.nexvio.ai/v1/contacts

Headers

Name	Required	Description
`Authorization`	Yes	Your API key in the format: `Bearer YOUR_API_KEY`
`Content-Type`	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`chatbotId`	string	Yes	ID of the chatbot this contact is associated with
`name`	string	No	Contact’s full name
`email`	string	No	Contact’s email address
`phone`	string	No	Contact’s phone number (E.164 format recommended)
`metadata`	object	No	Additional custom fields for this contact

{
  "chatbotId": "chatbot_456def",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15559876543",
  "metadata": {
    "company": "XYZ Corp",
    "role": "Director",
    "source": "Website"
  }
}

Response

{
  "status": "success",
  "data": {
    "contact": {
      "id": "contact_321cba",
      "chatbotId": "chatbot_456def",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+15559876543",
      "metadata": {
        "company": "XYZ Corp",
        "role": "Director",
        "source": "Website"
      },
      "createdAt": "2023-07-16T09:45:12Z",
      "updatedAt": "2023-07-16T09:45:12Z"
    }
  }
}

Update Contact

Update an existing contact’s information.

PATCH https://api.nexvio.ai/v1/contacts/{contactId}

Headers

Name	Required	Description
`Authorization`	Yes	Your API key in the format: `Bearer YOUR_API_KEY`
`Content-Type`	Yes	Must be `application/json`

Path Parameters

Parameter	Type	Required	Description
`contactId`	string	Yes	The ID of the contact to update

Request Body

All fields are optional. Only include the fields you want to update.

{
  "name": "Jane Wilson-Smith",
  "email": "jane.wilson@example.com",
  "metadata": {
    "company": "XYZ Corp",
    "role": "VP of Operations",
    "lastContact": "2023-07-16"
  }
}

Response

{
  "status": "success",
  "data": {
    "contact": {
      "id": "contact_321cba",
      "chatbotId": "chatbot_456def",
      "name": "Jane Wilson-Smith",
      "email": "jane.wilson@example.com",
      "phone": "+15559876543",
      "metadata": {
        "company": "XYZ Corp",
        "role": "VP of Operations",
        "source": "Website",
        "lastContact": "2023-07-16"
      },
      "createdAt": "2023-07-16T09:45:12Z",
      "updatedAt": "2023-07-16T10:30:45Z"
    }
  }
}

Delete Contact

Delete a contact.

DELETE https://api.nexvio.ai/v1/contacts/{contactId}

Headers

Name	Required	Description
`Authorization`	Yes	Your API key in the format: `Bearer YOUR_API_KEY`

Path Parameters

Parameter	Type	Required	Description
`contactId`	string	Yes	The ID of the contact to delete

Response

{
  "status": "success",
  "data": {
    "deleted": true,
    "id": "contact_321cba"
  }
}

Get Contact Conversations

Retrieve all conversations for a specific contact.

GET https://api.nexvio.ai/v1/contacts/{contactId}/conversations

Headers

Name	Required	Description
`Authorization`	Yes	Your API key in the format: `Bearer YOUR_API_KEY`

Path Parameters

Parameter	Type	Required	Description
`contactId`	string	Yes	The ID of the contact

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of conversations to return. Default: 50, Max: 100
`offset`	integer	No	Number of conversations to skip. Used for pagination. Default: 0

Response

{
  "status": "success",
  "data": {
    "conversations": [
      {
        "id": "conv_789ghi",
        "chatbotId": "chatbot_456def",
        "contactId": "contact_123abc",
        "startedAt": "2023-07-15T14:20:00Z",
        "lastMessageAt": "2023-07-15T14:22:31Z",
        "messageCount": 6,
        "summary": "Customer asked about pricing plans and features for enterprise"
      },
      // More conversations...
    ],
    "total": 3,
    "limit": 50,
    "offset": 0
  }
}

Error Responses

Authentication Error

{
  "status": "error",
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Not Found Error

{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "Contact not found"
  }
}

Validation Error

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "Invalid request data",
    "details": {
      "email": "Must be a valid email address"
    }
  }
}

Rate Limits

The Contacts API is subject to rate limiting of 100 requests per minute per API key. If you exceed this limit, you’ll receive a 429 Too Many Requests response.