# 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."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chatcaptain.com/api/api-dokumentation/conversation-organizations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.