API Reference

Contacts API

Create, retrieve, update, and delete contacts in your workspace.

Contacts represent individuals your agents communicate with. Each contact has a phone number and optional profile information. Contacts can be enrolled in campaigns and associated with call history.

Available Endpoints

GET/v1/contacts— List all contacts

POST/v1/contacts— Create a contact

GET/v1/contacts/:id— Get a contact

PATCH/v1/contacts/:id— Update a contact

DELETE/v1/contacts/:id— Delete a contact

Phone format requirement — August 8, 2026

Creating a contact or changing its phone number now requires an international number beginning with + and the country code. National-format numbers are rejected with 400because the API cannot safely infer a person's country from a workspace-wide default. Existing legacy national numbers may still be returned by reads and may be echoed unchanged during profile-only updates.

List Contacts

GET

/v1/contacts

Retrieves a paginated list of contacts with optional search and filtering.

Query Parameters

Parameters

Name	Type	Description
`limit`	`integer`	Number of contacts to return (1-100, default: 20)
`offset`	`integer`	Number of contacts to skip (default: 0)
`search`	`string`	Search by phone, name, or email (partial match)
`tag`	`string`	Filter by tag

Example Request

curl

curl -X GET "https://www.nutalk.ai/v1/contacts?search=john&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200

Response

{
  "success": true,
  "data": [
    {
      "id": "contact_abc123",
      "phone_number": "+14155551234",
      "first_name": "John",
      "last_name": "Doe",
      "display_name": "John Doe",
      "email": "john@example.com",
      "company": "Acme Corp",
      "notes": "Interested in enterprise plan",
      "tags": ["lead", "enterprise"],
      "source": "api",
      "first_contact_at": "2024-01-15T10:30:00Z",
      "last_contact_at": "2024-01-25T14:45:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-25T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 2500,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Create Contact

POST

/v1/contacts

Creates a new contact with the specified phone number and profile information.

Request Body

Parameters

Name	Type	Description
`phone_number` Required	`string`	Phone number in E.164 format (e.g., +14155551234)
`first_name`	`string`	Contact's first name (max 100 characters)
`last_name`	`string`	Contact's last name (max 100 characters)
`display_name`	`string`	Display name (max 200 characters)
`email`	`string`	Email address
`company`	`string`	Company name (max 200 characters)
`notes`	`string`	Internal notes (max 2000 characters)
`tags`	`array`	Array of tag strings for categorization

Example Request

curl

curl -X POST "https://www.nutalk.ai/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+14155551234",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "company": "Tech Startup",
  "tags": [
    "prospect",
    "inbound"
  ]
}'

Response

201

Response

{
  "success": true,
  "data": {
    "id": "contact_def456",
    "phone_number": "+14155551234",
    "first_name": "Jane",
    "last_name": "Smith",
    "display_name": null,
    "email": "jane@example.com",
    "company": "Tech Startup",
    "notes": null,
    "tags": ["prospect", "inbound"],
    "source": "api",
    "created_at": "2024-01-25T16:00:00Z",
    "updated_at": "2024-01-25T16:00:00Z"
  }
}

Duplicate Phone Numbers

Each phone number must be unique within your workspace. Attempting to create a contact with an existing phone number returns a 409 Conflict error.

Get Contact

GET

/v1/contacts/:id

Retrieves detailed information about a specific contact.

Path Parameters

Parameters

Name	Type	Description
`id` Required	`uuid`	The contact's unique identifier

Example Request

curl

curl -X GET "https://www.nutalk.ai/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200

Response

{
  "success": true,
  "data": {
    "id": "contact_abc123",
    "phone_number": "+14155551234",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "email": "john@example.com",
    "company": "Acme Corp",
    "notes": "Interested in enterprise plan",
    "tags": ["lead", "enterprise"],
    "source": "import",
    "first_contact_at": "2024-01-15T10:30:00Z",
    "last_contact_at": "2024-01-25T14:45:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-25T14:45:00Z",
    "crm_ids": {
      "hubspot": "12345",
      "kommo": "67890"
    }
  }
}

Update Contact

PATCH

/v1/contacts/:id

Updates an existing contact's profile information.

Path Parameters

Parameters

Name	Type	Description
`id` Required	`uuid`	The contact's unique identifier

Request Body

Parameters

Name	Type	Description
`phone_number`	`string`	New phone number in E.164 format
`confirm_phone_change`	`boolean`	Set to true only when intentionally repairing a legacy contact whose displayed and normalized phone identities conflict
`first_name`	`string`	New first name
`last_name`	`string`	New last name
`display_name`	`string`	New display name
`email`	`string`	New email address
`company`	`string`	New company name
`notes`	`string`	New notes
`tags`	`array`	New tags (replaces existing tags)

Example Request

curl

curl -X PATCH "https://www.nutalk.ai/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "New Company Name",
  "tags": [
    "customer",
    "enterprise"
  ]
}'

Response

200

Response

{
  "success": true,
  "data": {
    "id": "contact_abc123",
    "phone_number": "+14155551234",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "email": "john@example.com",
    "company": "New Company Name",
    "notes": "Interested in enterprise plan",
    "tags": ["customer", "enterprise"],
    "source": "import",
    "first_contact_at": "2024-01-15T10:30:00Z",
    "last_contact_at": "2024-01-25T14:45:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-25T17:00:00Z"
  }
}

Delete Contact

DELETE

/v1/contacts/:id

Permanently deletes a contact from your workspace.

Path Parameters

Parameters

Name	Type	Description
`id` Required	`uuid`	The contact's unique identifier

Example Request

curl

curl -X DELETE "https://www.nutalk.ai/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200

Response

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Permanent Deletion

This action is irreversible. The contact and all associated enrollment data will be permanently removed. Call history will be preserved but no longer linked to this contact.

Contact Sources

The source field indicates how the contact was added to your workspace:

Source	Description
api	Created via API
import	Imported from CSV file
manual	Added manually in dashboard
inbound	Created from inbound call/message
webhook	Created from webhook integration

PreviousCalls API NextContact Lists API

API Reference

Contacts API

Create, retrieve, update, and delete contacts in your workspace.

Contacts represent individuals your agents communicate with. Each contact has a phone number and optional profile information. Contacts can be enrolled in campaigns and associated with call history.

Available Endpoints

GET/v1/contacts— List all contacts

POST/v1/contacts— Create a contact

GET/v1/contacts/:id— Get a contact

PATCH/v1/contacts/:id— Update a contact

DELETE/v1/contacts/:id— Delete a contact

Phone format requirement — August 8, 2026

List Contacts

GET

/v1/contacts

Retrieves a paginated list of contacts with optional search and filtering.

Query Parameters

Parameters

Name	Type	Description
`limit`	`integer`	Number of contacts to return (1-100, default: 20)
`offset`	`integer`	Number of contacts to skip (default: 0)
`search`	`string`	Search by phone, name, or email (partial match)
`tag`	`string`	Filter by tag

Example Request

curl

curl -X GET "https://www.nutalk.ai/v1/contacts?search=john&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200

Response

{
  "success": true,
  "data": [
    {
      "id": "contact_abc123",
      "phone_number": "+14155551234",
      "first_name": "John",
      "last_name": "Doe",
      "display_name": "John Doe",
      "email": "john@example.com",
      "company": "Acme Corp",
      "notes": "Interested in enterprise plan",
      "tags": ["lead", "enterprise"],
      "source": "api",
      "first_contact_at": "2024-01-15T10:30:00Z",
      "last_contact_at": "2024-01-25T14:45:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-25T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 2500,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Create Contact

POST

/v1/contacts

Creates a new contact with the specified phone number and profile information.

Request Body

Parameters

Name	Type	Description
`phone_number` Required	`string`	Phone number in E.164 format (e.g., +14155551234)
`first_name`	`string`	Contact's first name (max 100 characters)
`last_name`	`string`	Contact's last name (max 100 characters)
`display_name`	`string`	Display name (max 200 characters)
`email`	`string`	Email address
`company`	`string`	Company name (max 200 characters)
`notes`	`string`	Internal notes (max 2000 characters)
`tags`	`array`	Array of tag strings for categorization

Example Request

curl

curl -X POST "https://www.nutalk.ai/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+14155551234",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@example.com",
  "company": "Tech Startup",
  "tags": [
    "prospect",
    "inbound"
  ]
}'

Response

201

Response

{
  "success": true,
  "data": {
    "id": "contact_def456",
    "phone_number": "+14155551234",
    "first_name": "Jane",
    "last_name": "Smith",
    "display_name": null,
    "email": "jane@example.com",
    "company": "Tech Startup",
    "notes": null,
    "tags": ["prospect", "inbound"],
    "source": "api",
    "created_at": "2024-01-25T16:00:00Z",
    "updated_at": "2024-01-25T16:00:00Z"
  }
}

Duplicate Phone Numbers

Each phone number must be unique within your workspace. Attempting to create a contact with an existing phone number returns a 409 Conflict error.

Get Contact

GET

/v1/contacts/:id

Retrieves detailed information about a specific contact.

Path Parameters

Parameters

Name	Type	Description
`id` Required	`uuid`	The contact's unique identifier

Example Request

curl

curl -X GET "https://www.nutalk.ai/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200

Response

{
  "success": true,
  "data": {
    "id": "contact_abc123",
    "phone_number": "+14155551234",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "email": "john@example.com",
    "company": "Acme Corp",
    "notes": "Interested in enterprise plan",
    "tags": ["lead", "enterprise"],
    "source": "import",
    "first_contact_at": "2024-01-15T10:30:00Z",
    "last_contact_at": "2024-01-25T14:45:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-25T14:45:00Z",
    "crm_ids": {
      "hubspot": "12345",
      "kommo": "67890"
    }
  }
}

Update Contact

PATCH

/v1/contacts/:id

Updates an existing contact's profile information.

Path Parameters

Parameters

Name	Type	Description
`id` Required	`uuid`	The contact's unique identifier

Request Body

Parameters

Name	Type	Description
`phone_number`	`string`	New phone number in E.164 format
`confirm_phone_change`	`boolean`	Set to true only when intentionally repairing a legacy contact whose displayed and normalized phone identities conflict
`first_name`	`string`	New first name
`last_name`	`string`	New last name
`display_name`	`string`	New display name
`email`	`string`	New email address
`company`	`string`	New company name
`notes`	`string`	New notes
`tags`	`array`	New tags (replaces existing tags)

Example Request

curl

curl -X PATCH "https://www.nutalk.ai/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "New Company Name",
  "tags": [
    "customer",
    "enterprise"
  ]
}'

Response

200

Response

{
  "success": true,
  "data": {
    "id": "contact_abc123",
    "phone_number": "+14155551234",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "email": "john@example.com",
    "company": "New Company Name",
    "notes": "Interested in enterprise plan",
    "tags": ["customer", "enterprise"],
    "source": "import",
    "first_contact_at": "2024-01-15T10:30:00Z",
    "last_contact_at": "2024-01-25T14:45:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-25T17:00:00Z"
  }
}

Delete Contact

DELETE

/v1/contacts/:id

Permanently deletes a contact from your workspace.

Path Parameters

Parameters

Name	Type	Description
`id` Required	`uuid`	The contact's unique identifier

Example Request

curl

curl -X DELETE "https://www.nutalk.ai/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200

Response

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Permanent Deletion

This action is irreversible. The contact and all associated enrollment data will be permanently removed. Call history will be preserved but no longer linked to this contact.

Contact Sources

The source field indicates how the contact was added to your workspace:

Source	Description
api	Created via API
import	Imported from CSV file
manual	Added manually in dashboard
inbound	Created from inbound call/message
webhook	Created from webhook integration

PreviousCalls API NextContact Lists API