> For the complete documentation index, see [llms.txt](https://docs.epic-ai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.epic-ai.com/api-dokumentation/conversation-contacts.md).

# Conversation Contacts

## Searches contacts

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/search":{"get":{"operationId":"ConversationContactController_searchContacts[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"query","required":true,"in":"query","description":"The search term.","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","description":"The page on which to start the seach.","schema":{"type":"number"}},{"name":"pageSize","required":true,"in":"query","description":"The number of pages to return.","schema":{"type":"number"}},{"name":"hiddenHits","required":false,"in":"query","description":"Comma-separated list of IDs to be excluded from the search results.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchContactsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Searches contacts","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"SearchContactsResponseDto":{"type":"object","properties":{"results":{"description":"The search results.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SearchContactResultDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["results"]},"SearchContactResultDto":{"type":"object","properties":{"facetCounts":{"description":"The facet counts for the search.","type":"array","items":{"type":"object"}},"found":{"type":"number","description":"Total number of results found."},"hits":{"description":"The search result hits.","type":"array","items":{"$ref":"#/components/schemas/SearchResultHitContactDto"}},"outOf":{"type":"number","description":"Total number of documents searched."},"page":{"type":"number","description":"The current page of search results."},"searchTimeMs":{"type":"number","description":"The duration of the search in milliseconds."}},"required":["facetCounts","found","hits","outOf","page","searchTimeMs"]},"SearchResultHitContactDto":{"type":"object","properties":{"contact":{"description":"The matching contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"highlights":{"description":"List of highlighted match results.","type":"array","items":{"type":"object"}},"textMatch":{"type":"string","description":"A combined string of all text matches."}},"required":["contact","highlights","textMatch"]},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Lists all contacts for a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts":{"get":{"operationId":"ConversationContactController_listContacts[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"pageToken","required":false,"in":"query","description":"The date after which to filter organizations. Only organizations created before this date will be fetched.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"The amount of contacts to fetch","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListContactsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all contacts for a chatbot","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListContactsResponseDto":{"type":"object","properties":{"contacts":{"description":"The list of contacts.","type":"array","items":{"$ref":"#/components/schemas/ContactDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["contacts"]},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Creates a new contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts":{"post":{"operationId":"ConversationContactController_createContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Creates a new contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateContactRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the contact."},"language":{"type":"string","description":"The language of the contact."},"email":{"type":"string","description":"The email address of the contact."},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"webId":{"type":"string","description":"The web channel ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"providerId":{"type":"string","description":"The ID of the contact with the external provider."},"avatar":{"type":"string","format":"uri","description":"The URL to the avatar image of the contact."}},"required":["language"]},"ContactResponseDto":{"type":"object","properties":{"contact":{"description":"The contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Retrieves a specific contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}":{"get":{"operationId":"ConversationContactController_getContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ContactResponseDto":{"type":"object","properties":{"contact":{"description":"The contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```

## Deletes a contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.delete\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}":{"delete":{"operationId":"ConversationContactController_deleteContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteContactResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes a contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteContactResponseDto":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Indicates whether the contact was successfully deleted."},"error":{"type":"string","description":"Optional error message."}}}}}}
```

## Updates an existing contact

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.edit\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}":{"patch":{"operationId":"ConversationContactController_updateContact[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to retrieve.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Updates an existing contact","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateContactRequestDto":{"type":"object","properties":{"contact":{"description":"The contact data to update.","allOf":[{"$ref":"#/components/schemas/UpdateContactDto"}]}},"required":["contact"]},"UpdateContactDto":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the contact."},"email":{"type":"string","description":"The new email address of the contact."},"address":{"description":"The new address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The new phone number of the contact."},"variables":{"type":"object","description":"Custom variables to set on the contact.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs to associate with the contact.","type":"array","items":{"type":"string"}},"avatar":{"type":"string","format":"uri","description":"The URL to the contact's avatar image."},"language":{"type":"string","description":"The language code of the contact."}},"required":["variables","organizationIds"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}},"ContactResponseDto":{"type":"object","properties":{"contact":{"description":"The contact.","allOf":[{"$ref":"#/components/schemas/ContactDto"}]},"error":{"type":"string","description":"Optional error message."}}},"ContactDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the contact."},"name":{"type":"string","description":"The display name of the contact."},"created":{"type":"string","description":"Timestamp when the contact was created."},"updated":{"type":"string","description":"Timestamp when the contact was last updated."},"email":{"type":"string","description":"The email address of the contact."},"address":{"description":"The address of the contact.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":"string","description":"The phone number of the contact."},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}},"organizationIds":{"description":"List of organization IDs this contact belongs to.","type":"array","items":{"type":"string"}},"whatsappId":{"type":"string","description":"The WhatsApp ID of the contact."},"telegramId":{"type":"string","description":"The Telegram ID of the contact."},"facebookId":{"type":"string","description":"The Facebook ID of the contact."},"instagramId":{"type":"string","description":"The Instagram ID of the contact."},"avatar":{"type":"string","description":"The URL to the contact's avatar image."}},"required":["id","name","created","updated","variables","organizationIds"]}}}}
```

## Lists all organizations a contact belongs to

> \
> \
> \*\*Required Permission:\*\* \`chatbots.contacts.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation contacts","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/contacts/{contactId}/organizations":{"get":{"operationId":"ConversationContactController_listContactOrganizations[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"contactId","required":true,"in":"path","description":"The Id of the contact to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListContactOrganizationsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all organizations a contact belongs to","tags":["Conversation contacts"],"description":"\n\n**Required Permission:** `chatbots.contacts.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListContactOrganizationsResponseDto":{"type":"object","properties":{"organizations":{"description":"The list of organizations.","type":"array","items":{"$ref":"#/components/schemas/OrganizationDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["organizations"]},"OrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the organization."},"name":{"type":"string","description":"The name of the organization."},"created":{"type":"string","description":"Timestamp when the organization was created."},"updated":{"type":"string","description":"Timestamp when the organization was last updated."},"email":{"type":"string","format":"email","description":"The email address of the organization."},"website":{"type":"string","format":"uri","description":"The website URL of the organization."},"size":{"type":"number","description":"The number of employees in the organization."},"industry":{"type":"string","description":"The industry of the organization."},"address":{"description":"The address of the organization.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"variables":{"type":"object","description":"Custom variables as key-value pairs.","additionalProperties":{"type":"string"}}},"required":["id","name","created","updated","variables"]},"AddressDto":{"type":"object","properties":{"street":{"type":"string","description":"The street name."},"country":{"type":"string","description":"The country name."},"zipcode":{"type":"string","description":"The postal/zip code."},"houseNumber":{"type":"string","description":"The house number."},"location":{"type":"string","description":"The city or location name."}}}}}}
```