Contacts

Create, update, search, and manage contacts

Create or Update Contact

post

Create a new contact or update an existing one. If a contact with the same phone number exists, it will be updated.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Body

application/json

phonestringRequired

Phone number with country code (required)

Example: [phone]

firstNamestringOptional

First name

Example: John

lastNamestringOptional

Last name

Example: Doe

emailstring · emailOptional

Email address

Example: [email protected]

tagsstring[]Optional

Tags to assign

Example: ["vip","hot_lead"]

fieldsobjectOptional

Fields to create/update

Example: {"company":"Meta","city":"Bogura"}

Responses

200

Contact updated (isNew: false)

application/json

Other propertiesanyOptional

201

Contact created (isNew: true)

application/json

post/api/contacts

HTTPcURLJavaScriptPython

POST /api/contacts HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "phone": "[phone]",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "tags": [
    "vip",
    "hot_lead"
  ],
  "fields": {
    "company": "Meta",
    "city": "Bogura"
  }
}

{
  "contact": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "[phone]",
    "email": "[email protected]",
    "tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "vip",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "fields": {
      "city": "Jerusalem",
      "company": "Acme Inc"
    },
    "source": "API",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  "isNew": false
}

Delete Contact

delete

Permanently delete a contact by ID.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

contact_idstring · uuidRequired

Contact ID

Responses

200

Contact deleted

application/json

Other propertiesanyOptional

delete/api/contacts/{contact_id}

HTTPcURLJavaScriptPython

DELETE /api/contacts/{contact_id} HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Contact deleted

{
  "deleted": true
}

Update Contact Fields

patch

Update one or more fields for a specific contact.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

contact_idstring · uuidRequired

Contact ID

Body

application/json

fieldsobjectRequired

Fields to update

Example: {"NickName":"Johnny","city":"Jerusalem"}

Responses

200

Contact updated successfully

application/json

Other propertiesanyOptional

patch/api/contacts/{contact_id}/fields

HTTPcURLJavaScriptPython

PATCH /api/contacts/{contact_id}/fields HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "fields": {
    "NickName": "Johnny",
    "city": "Jerusalem"
  }
}

200

Contact updated successfully

{
  "contact": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "[phone]",
    "email": "[email protected]",
    "tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "vip",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "fields": {
      "city": "Jerusalem",
      "company": "Acme Inc"
    },
    "source": "API",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Clear Contact Field

delete

Clear a specific field value for a contact.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

contact_idstring · uuidRequired

Contact ID

field_keystringRequired

Field key to clear (e.g., 'email' or 'city')

Responses

200

Field cleared successfully

application/json

Other propertiesanyOptional

delete/api/contacts/{contact_id}/fields/{field_key}

HTTPcURLJavaScriptPython

DELETE /api/contacts/{contact_id}/fields/{field_key} HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Field cleared successfully

{
  "contact": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "[phone]",
    "email": "[email protected]",
    "tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "vip",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "fields": {
      "city": "Jerusalem",
      "company": "Acme Inc"
    },
    "source": "API",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  "cleared": true
}

Add Tags to Contact

post

Add one or more tags to an existing contact without replacing existing tags.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

contact_idstring · uuidRequired

Contact ID

Body

application/json

tagsstring[]Required

Tags to add

Example: ["vip","hot_lead"]

Responses

200

Tags added successfully

application/json

Other propertiesanyOptional

post/api/contacts/{contact_id}/tags

HTTPcURLJavaScriptPython

POST /api/contacts/{contact_id}/tags HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "tags": [
    "vip",
    "hot_lead"
  ]
}

200

Tags added successfully

{
  "contact": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "[phone]",
    "email": "[email protected]",
    "tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "vip",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "fields": {
      "city": "Jerusalem",
      "company": "Acme Inc"
    },
    "source": "API",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Remove Tag from Contact

delete

Remove a specific tag from a contact. You can use the tag ID or tag name.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

contact_idstring · uuidRequired

Contact ID

tag_id_or_namestringRequired

Tag ID or tag name to remove

Responses

200

Tag removed successfully

application/json

Other propertiesanyOptional

delete/api/contacts/{contact_id}/tags/{tag_id_or_name}

HTTPcURLJavaScriptPython

DELETE /api/contacts/{contact_id}/tags/{tag_id_or_name} HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Tag removed successfully

{
  "contact": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "[phone]",
    "email": "[email protected]",
    "tags": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "vip",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "fields": {
      "city": "Jerusalem",
      "company": "Acme Inc"
    },
    "source": "API",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  "removed": true
}

Search Contacts

get

Search contacts by phone number or name. At least one search parameter is required.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Query parameters

limitintegerOptional

Number of results to return (default: 50)

namestringOptional

Name to search (first or last)

offsetintegerOptional

Offset for pagination (default: 0)

phonestringOptional

Phone number to search

Responses

200

Search results

application/json

Other propertiesanyOptional

get/api/contacts/search

HTTPcURLJavaScriptPython

GET /api/contacts/search HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Search results

{
  "contacts": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "[phone]",
      "email": "[email protected]",
      "tags": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "vip",
          "created_at": "2025-01-01T00:00:00Z",
          "updated_at": "2025-01-01T00:00:00Z"
        }
      ],
      "fields": {
        "city": "Jerusalem",
        "company": "Acme Inc"
      },
      "source": "API",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}