> 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-organizations.md).

# Conversation Organizations

## Lists all organizations for a chatbot

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations":{"get":{"operationId":"ConversationOrganizationController_listOrganizations[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/ListOrganizationsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all organizations for a chatbot","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListOrganizationsResponseDto":{"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."}}}}}}
```

## Creates a new organization

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations":{"post":{"operationId":"ConversationOrganizationController_createOrganization[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/CreateOrganizationRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Creates a new organization","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateOrganizationRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the organization."},"email":{"type":"string","description":"The email address of the organization."},"website":{"type":"string","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"}]},"phoneNumber":{"type":"string","description":"The phone number of the organization."}},"required":["name"]},"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."}}},"OrganizationResponseDto":{"type":"object","properties":{"organization":{"description":"The organization.","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"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"]}}}}
```

## Searches organizations

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations/search":{"get":{"operationId":"ConversationOrganizationController_searchOrganizations[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/SearchOrganizationResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Searches organizations","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"SearchOrganizationResponseDto":{"type":"object","properties":{"results":{"description":"The search results.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SearchOrganizationResultDto"}]},"error":{"type":"string","description":"Optional error message."}},"required":["results"]},"SearchOrganizationResultDto":{"type":"object","properties":{"facetCounts":{"description":"The facet counts for the search.","type":"array","items":{"$ref":"#/components/schemas/SearchResultFacetDto"}},"found":{"type":"number","description":"Total number of results found."},"hits":{"description":"The search result hits.","type":"array","items":{"$ref":"#/components/schemas/SearchResultHitOrganizationDto"}},"outOf":{"type":"number","description":"Total number of documents searched."},"page":{"type":"number","description":"The current page of search results."},"searchTimeMs":{"type":"number","description":"The search duration in milliseconds."}},"required":["facetCounts","found","hits","outOf","page","searchTimeMs"]},"SearchResultFacetDto":{"type":"object","properties":{"counts":{"description":"The facet value counts.","type":"array","items":{"$ref":"#/components/schemas/SearchResultFacet_CountDto"}},"fieldName":{"type":"string","description":"The name of the faceted field."},"stats":{"description":"Statistics for numeric facets.","allOf":[{"$ref":"#/components/schemas/SearchResultFacet_StatsDto"}]}},"required":["counts","fieldName"]},"SearchResultFacet_CountDto":{"type":"object","properties":{"count":{"type":"number","description":"The number of results for this facet value."},"highlighted":{"type":"string","description":"The highlighted facet value."},"value":{"type":"string","description":"The facet value."}},"required":["count","highlighted","value"]},"SearchResultFacet_StatsDto":{"type":"object","properties":{"max":{"type":"number","description":"The maximum value."},"avg":{"type":"number","description":"The average value."},"min":{"type":"number","description":"The minimum value."},"sum":{"type":"number","description":"The sum of all values."}}},"SearchResultHitOrganizationDto":{"type":"object","properties":{"organization":{"description":"The matching organization.","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"highlights":{"description":"List of highlighted match results.","type":"array","items":{"$ref":"#/components/schemas/HighlightResultDto"}},"textMatch":{"type":"string","description":"A combined string of all text matches."}},"required":["organization","highlights","textMatch"]},"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."}}},"HighlightResultDto":{"type":"object","properties":{"field":{"type":"string","description":"The field where the hit was found."},"matchedTokens":{"description":"The exact words that matched.","type":"array","items":{"type":"string"}},"snippet":{"type":"string","description":"A short excerpt of the text with highlights."}},"required":["field","matchedTokens","snippet"]}}}}
```

## Lists all contacts of an organization

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations/{organizationId}/contacts":{"get":{"operationId":"ConversationOrganizationController_listOrganizationContacts[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"organizationId","required":true,"in":"path","description":"The Id of the organization to add a contact to.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOrganizationContactsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all contacts of an organization","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.contacts.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListOrganizationContactsResponseDto":{"type":"object","properties":{"contacts":{"description":"The list of contacts in the organization.","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."}}}}}}
```

## Retrieves a specific organization

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations/{organizationId}":{"get":{"operationId":"ConversationOrganizationController_getOrganization[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"organizationId","required":true,"in":"path","description":"The Id of the organization to add a contact to.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific organization","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"OrganizationResponseDto":{"type":"object","properties":{"organization":{"description":"The organization.","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"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."}}}}}}
```

## Deletes an organization

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

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

## Updates an existing organization

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations/{organizationId}":{"patch":{"operationId":"ConversationOrganizationController_updateOrganization[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"organizationId","required":true,"in":"path","description":"The Id of the organization to add a contact to.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Updates an existing organization","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateOrganizationRequestDto":{"type":"object","properties":{"organization":{"description":"The organization data to update.","allOf":[{"$ref":"#/components/schemas/UpdateOrganizationDto"}]}},"required":["organization"]},"UpdateOrganizationDto":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the organization."},"email":{"type":"string","description":"The new email address of the organization."},"website":{"type":"string","description":"The new website URL of the organization."},"size":{"type":"number","description":"The new number of employees."},"industry":{"type":"string","description":"The new industry of the organization."},"address":{"description":"The new address of the organization.","allOf":[{"$ref":"#/components/schemas/AddressDto"}]},"variables":{"type":"object","description":"Custom variables to set on the organization.","additionalProperties":{"type":"string"}}},"required":["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."}}},"OrganizationResponseDto":{"type":"object","properties":{"organization":{"description":"The organization.","allOf":[{"$ref":"#/components/schemas/OrganizationDto"}]},"error":{"type":"string","description":"Optional error message."}}},"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"]}}}}
```

## Gets the count of contacts in an organization

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

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Conversation organizations","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/organizations/{organizationId}/contacts/count":{"get":{"operationId":"ConversationOrganizationController_getOrganizationContactsCount[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"organizationId","required":true,"in":"path","description":"The Id of the organization to add a contact to.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetOrganizationContactsCountResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Gets the count of contacts in an organization","tags":["Conversation organizations"],"description":"\n\n**Required Permission:** `chatbots.organizations.contacts.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"GetOrganizationContactsCountResponseDto":{"type":"object","properties":{"count":{"type":"number","description":"The number of contacts in the organization."},"error":{"type":"string","description":"Optional error message."}}}}}}
```