Contacts — NexaDesk Docs

Manage your contact database programmatically. Contacts represent visitors who have interacted with your chatbot or been added manually.

List Contacts

Retrieve a paginated list of contacts with optional filtering.

GET /api/v1/external/contacts

Parameter	Type	Description
`search`	string	Search by first name, last name, email, phone, or company (case-insensitive partial match)
`tag`	string	Filter by tag (exact match)
`sort`	string	Sort field and direction. Allowed fields: `created_at`, `last_activity`, `name`, `email`
`limit`	number	Results per page (default 50, max 100)
`cursor`	string	Pagination cursor from previous response

bash

curl "https://chats.nexadesk.ai/api/v1/external/contacts?search=jane&sort=last_activity:desc&limit=20" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

json

{
  "success": true,
  "data": [
    {
      "id": "a50e8400-e29b-41d4-a716-446655440001",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "phone": "+1-555-0123",
      "company_name": "Acme Corp",
      "avatar_url": null,
      "tags": ["customer", "vip"],
      "profile_notes": "Enterprise client, interested in multi-channel setup",
      "interest_summary": "AI chatbot for customer support",
      "last_activity": "2026-03-18T09:15:00.000Z",
      "created_at": "2026-02-01T12:00:00.000Z",
      "conversation_count": 5,
      "last_conversation_at": "2026-03-18T09:15:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total_count": 1,
    "limit": 20
  }
}

Create Contact

Create a new contact. If a contact with the same email already exists, a 409 Conflict is returned.

POST /api/v1/external/contacts

Field	Type	Required	Description
`first_name`	string	Yes	First name (max 100 characters)
`last_name`	string	No	Last name (max 100 characters)
`email`	string	No	Email address (must be valid format, used for deduplication)
`phone`	string	No	Phone number (max 50 characters)
`company_name`	string	No	Company name (max 200 characters)
`tags`	string[]	No	Array of tag strings
`profile_notes`	string	No	Notes about the contact (max 5000 characters)
`metadata`	object	No	Arbitrary JSON metadata

bash

curl -X POST "https://chats.nexadesk.ai/api/v1/external/contacts" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1-555-0456",
    "company_name": "TechCorp",
    "tags": ["prospect", "website"],
    "profile_notes": "Found us through Google Ads",
    "metadata": { "utm_source": "google", "utm_campaign": "spring-2026" }
  }'

json

{
  "success": true,
  "data": {
    "id": "b60f9500-f39c-52e5-b827-557766550001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1-555-0456",
    "company_name": "TechCorp",
    "tags": ["prospect", "website"],
    "profile_notes": "Found us through Google Ads",
    "created_at": "2026-03-20T14:30:00.000Z"
  }
}

json

{
  "success": false,
  "error": "Contact with this email already exists",
  "data": { "id": "existing-contact-uuid" }
}

Update Contact

Update one or more fields on an existing contact.

PATCH /api/v1/external/contacts?id={contact_id}

All fields are optional. Only provided fields are updated.

Field	Type	Description
`first_name`	string	Updated first name
`last_name`	string	Updated last name
`email`	string	Updated email
`phone`	string	Updated phone
`company_name`	string	Updated company
`tags`	string[]	Replace tags array
`profile_notes`	string	Updated notes

bash

curl -X PATCH "https://chats.nexadesk.ai/api/v1/external/contacts?id=a50e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["customer", "vip", "enterprise"],
    "profile_notes": "Upgraded to enterprise plan in March 2026"
  }'

Delete Contact

Permanently delete a contact and disassociate their conversations.

DELETE /api/v1/external/contacts?id={contact_id}

bash

curl -X DELETE "https://chats.nexadesk.ai/api/v1/external/contacts?id=a50e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer fc_live_xxxxxxxxxxxx"

json

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "a50e8400-e29b-41d4-a716-446655440001"
  }
}