Conversation contacts

Searches contacts

get

Required Permission: chatbots.contacts.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

querystringRequired

The search term.

pagenumberRequired

The page on which to start the seach.

Example: 1

pageSizenumberRequired

The number of pages to return.

Example: 250

hiddenHitsstringOptional

Comma-separated list of IDs to be excluded from the search results.

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/contacts/search

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/contacts/search?query=text&page=1&pageSize=250 HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "results": {
    "facetCounts": [
      {}
    ],
    "found": 42,
    "hits": [
      {
        "contact": {
          "id": "59aBv7wzR9cxd1Pxyz",
          "name": "Max Mustermann",
          "created": "2025-10-05T10:00:00Z",
          "updated": "2025-10-05T10:05:00Z",
          "email": "[e-mail]",
          "address": {
            "street": "Example Street",
            "country": "Germany",
            "zipcode": "12345",
            "houseNumber": "1a",
            "location": "Berlin"
          },
          "phoneNumber": "[phone]",
          "variables": {
            "customer_id": "12345"
          },
          "organizationIds": [
            "uq8BxZaJd2wZR9cxd1P"
          ],
          "whatsappId": "49123456789",
          "telegramId": "123456789",
          "facebookId": "10158123456789012",
          "instagramId": "17841400123456789",
          "avatar": "https://example.com/avatar.png"
        },
        "highlights": [
          {}
        ],
        "textMatch": "John Doe [e-mail]"
      }
    ],
    "outOf": 1000,
    "page": 1,
    "searchTimeMs": 15
  },
  "error": "text"
}

Lists all contacts for a chatbot

get

Required Permission: chatbots.contacts.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

pageTokenstringOptional

The date after which to filter organizations. Only organizations created before this date will be fetched.

Example: 2025-09-29T07:08:00Z

limitnumberOptional

The amount of contacts to fetch

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/contacts

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/contacts HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "contacts": [
    {
      "id": "59aBv7wzR9cxd1Pxyz",
      "name": "Max Mustermann",
      "created": "2025-10-05T10:00:00Z",
      "updated": "2025-10-05T10:05:00Z",
      "email": "[e-mail]",
      "address": {
        "street": "Example Street",
        "country": "Germany",
        "zipcode": "12345",
        "houseNumber": "1a",
        "location": "Berlin"
      },
      "phoneNumber": "[phone]",
      "variables": {
        "customer_id": "12345"
      },
      "organizationIds": [
        "uq8BxZaJd2wZR9cxd1P"
      ],
      "whatsappId": "49123456789",
      "telegramId": "123456789",
      "facebookId": "10158123456789012",
      "instagramId": "17841400123456789",
      "avatar": "https://example.com/avatar.png"
    }
  ],
  "error": "text"
}

Creates a new contact

post

Required Permission: chatbots.contacts.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

application/json

namestringOptional

The name of the contact.

Example: Max Example

languagestringRequired

The language of the contact.

Example: EN

emailstringOptional

The email address of the contact.

Example: [e-mail]

phoneNumberstringOptional

The phone number of the contact.

Example: [phone]

whatsappIdstringOptional

The WhatsApp ID of the contact.

Example: 49123456789

webIdstringOptional

The web channel ID of the contact.

Example: web_abc123xyz

instagramIdstringOptional

The Instagram ID of the contact.

Example: 17841400123456789

facebookIdstringOptional

The Facebook ID of the contact.

Example: 10158123456789012

telegramIdstringOptional

The Telegram ID of the contact.

Example: 123456789

providerIdstringOptional

The ID of the contact with the external provider.

Example: provider_abc123

avatarstring · uriOptional

The URL to the avatar image of the contact.

Example: https://example.com/avatar.png

Responses

201Success

application/json

400

Invalid input data.

403

Insufficient permissions.

post

/v1/chatbots/{chatbotId}/contacts

HTTPcURLJavaScriptPython

POST /v1/chatbots/{chatbotId}/contacts HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 322

{
  "name": "Max Example",
  "language": "EN",
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "whatsappId": "49123456789",
  "webId": "web_abc123xyz",
  "instagramId": "17841400123456789",
  "facebookId": "10158123456789012",
  "telegramId": "123456789",
  "providerId": "provider_abc123",
  "avatar": "https://example.com/avatar.png"
}

{
  "contact": {
    "id": "59aBv7wzR9cxd1Pxyz",
    "name": "Max Mustermann",
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T10:05:00Z",
    "email": "[e-mail]",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "[phone]",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "whatsappId": "49123456789",
    "telegramId": "123456789",
    "facebookId": "10158123456789012",
    "instagramId": "17841400123456789",
    "avatar": "https://example.com/avatar.png"
  },
  "error": "text"
}

Retrieves a specific contact

get

Required Permission: chatbots.contacts.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to retrieve.

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/contacts/{contactId}

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/contacts/{contactId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "contact": {
    "id": "59aBv7wzR9cxd1Pxyz",
    "name": "Max Mustermann",
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T10:05:00Z",
    "email": "[e-mail]",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "[phone]",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "whatsappId": "49123456789",
    "telegramId": "123456789",
    "facebookId": "10158123456789012",
    "instagramId": "17841400123456789",
    "avatar": "https://example.com/avatar.png"
  },
  "error": "text"
}

Deletes a contact

delete

Required Permission: chatbots.contacts.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to delete.

Responses

200Success

application/json

deletedbooleanOptional

Indicates whether the contact was successfully deleted.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/contacts/{contactId}

HTTPcURLJavaScriptPython

DELETE /v1/chatbots/{chatbotId}/contacts/{contactId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "deleted": true,
  "error": "text"
}

Updates an existing contact

patch

Required Permission: chatbots.contacts.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to retrieve.

Body

application/json

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

patch

/v1/chatbots/{chatbotId}/contacts/{contactId}

HTTPcURLJavaScriptPython

PATCH /v1/chatbots/{chatbotId}/contacts/{contactId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 367

{
  "contact": {
    "name": "Maximilian Example",
    "email": "[e-mail]",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "[phone]",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "avatar": "https://example.com/avatar.png",
    "language": "EN"
  }
}

{
  "contact": {
    "id": "59aBv7wzR9cxd1Pxyz",
    "name": "Max Mustermann",
    "created": "2025-10-05T10:00:00Z",
    "updated": "2025-10-05T10:05:00Z",
    "email": "[e-mail]",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "phoneNumber": "[phone]",
    "variables": {
      "customer_id": "12345"
    },
    "organizationIds": [
      "uq8BxZaJd2wZR9cxd1P"
    ],
    "whatsappId": "49123456789",
    "telegramId": "123456789",
    "facebookId": "10158123456789012",
    "instagramId": "17841400123456789",
    "avatar": "https://example.com/avatar.png"
  },
  "error": "text"
}

Lists all organizations a contact belongs to

get

Required Permission: chatbots.contacts.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

contactIdstringRequired

The Id of the contact to retrieve.

Responses

200Success

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/contacts/{contactId}/organizations

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/contacts/{contactId}/organizations HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "organizations": [
    {
      "id": "39aBv7wzR9cxd1Pxyz",
      "name": "Example Company Ltd.",
      "created": "2025-10-05T12:00:00Z",
      "updated": "2025-10-05T12:05:00Z",
      "email": "[e-mail]",
      "website": "https://www.examplecompany.de",
      "size": 50,
      "industry": "Software Development",
      "address": {
        "street": "Example Street",
        "country": "Germany",
        "zipcode": "12345",
        "houseNumber": "1a",
        "location": "Berlin"
      },
      "variables": {
        "customer_number": "KD-12345"
      }
    }
  ],
  "error": "text"
}