Conversation organizations

Lists all organizations for a chatbot

get

Required Permission: chatbots.organizations.list

Resource: chatbots/:chatbotId

Authorizations

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: 2024-09-29T07:08:00Z

limitnumberOptional

The amount of contacts to fetch

Responses

200Success

application/json

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/organizations

GET /v1/chatbots/{chatbotId}/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": "contact@examplecompany.de",
      "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"
}

Creates a new organization

post

Required Permission: chatbots.organizations.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

namestringRequired

The name of the organization.

Example: Neue Firma GmbH

emailstringOptional

The email address of the organization.

Example: info@neue-firma.de

websitestringOptional

The website URL of the organization.

Example: https://neue-firma.de

sizenumberOptional

The number of employees in the organization.

Example: 10

industrystringOptional

The industry of the organization.

Example: E-Commerce

phoneNumberstringOptional

The phone number of the organization.

Example: +4915198765432

Responses

201Success

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

post

/v1/chatbots/{chatbotId}/organizations

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

{
  "name": "Neue Firma GmbH",
  "email": "info@neue-firma.de",
  "website": "https://neue-firma.de",
  "size": 10,
  "industry": "E-Commerce",
  "address": {
    "street": "Example Street",
    "country": "Germany",
    "zipcode": "12345",
    "houseNumber": "1a",
    "location": "Berlin"
  },
  "phoneNumber": "+4915198765432"
}

{
  "organization": {
    "id": "39aBv7wzR9cxd1Pxyz",
    "name": "Example Company Ltd.",
    "created": "2025-10-05T12:00:00Z",
    "updated": "2025-10-05T12:05:00Z",
    "email": "contact@examplecompany.de",
    "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"
}

Searches organizations

get

Required Permission: chatbots.organizations.list

Resource: chatbots/:chatbotId

Authorizations

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

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/organizations/search

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

{
  "results": {
    "facetCounts": [
      {
        "counts": [
          {
            "count": 42,
            "highlighted": "<em>whatsapp</em>",
            "value": "whatsapp"
          }
        ],
        "fieldName": "channelType",
        "stats": {
          "max": 100,
          "avg": 45.5,
          "min": 1,
          "sum": 1820
        }
      }
    ],
    "found": 42,
    "hits": [
      {
        "organization": {
          "id": "39aBv7wzR9cxd1Pxyz",
          "name": "Example Company Ltd.",
          "created": "2025-10-05T12:00:00Z",
          "updated": "2025-10-05T12:05:00Z",
          "email": "contact@examplecompany.de",
          "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"
          }
        },
        "highlights": [
          {
            "field": "content.text",
            "matchedTokens": [
              "text"
            ],
            "snippet": "text"
          }
        ],
        "textMatch": "Musterfirma GmbH Software"
      }
    ],
    "outOf": 500,
    "page": 1,
    "searchTimeMs": 12
  },
  "error": "text"
}

Lists all contacts of an organization

get

Required Permission: chatbots.organizations.contacts.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

organizationIdstringRequired

The Id of the organization to add a contact to.

Responses

200Success

application/json

403

Insufficient permissions.

get

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

GET /v1/chatbots/{chatbotId}/organizations/{organizationId}/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": "max.mustermann@example.com",
      "address": {
        "street": "Example Street",
        "country": "Germany",
        "zipcode": "12345",
        "houseNumber": "1a",
        "location": "Berlin"
      },
      "phoneNumber": "+4917612345678",
      "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 organization

get

Required Permission: chatbots.organizations.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

organizationIdstringRequired

The Id of the organization to add a contact to.

Responses

200Success

application/json

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/organizations/{organizationId}

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

{
  "organization": {
    "id": "39aBv7wzR9cxd1Pxyz",
    "name": "Example Company Ltd.",
    "created": "2025-10-05T12:00:00Z",
    "updated": "2025-10-05T12:05:00Z",
    "email": "contact@examplecompany.de",
    "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"
}

Deletes an organization

delete

Required Permission: chatbots.organizations.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

organizationIdstringRequired

The Id of the organization to add a contact to.

Responses

200Success

application/json

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/organizations/{organizationId}

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

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

Updates an existing organization

patch

Required Permission: chatbots.organizations.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

organizationIdstringRequired

The Id of the organization to add a contact to.

Body

Responses

200Success

application/json

400

Invalid input data.

403

Insufficient permissions.

patch

/v1/chatbots/{chatbotId}/organizations/{organizationId}

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

{
  "organization": {
    "name": "Updated Firma GmbH",
    "email": "updated@firma.de",
    "website": "https://updated-firma.de",
    "size": 100,
    "industry": "Technology",
    "address": {
      "street": "Example Street",
      "country": "Germany",
      "zipcode": "12345",
      "houseNumber": "1a",
      "location": "Berlin"
    },
    "variables": {
      "customer_number": "KD-67890"
    }
  }
}

{
  "organization": {
    "id": "39aBv7wzR9cxd1Pxyz",
    "name": "Example Company Ltd.",
    "created": "2025-10-05T12:00:00Z",
    "updated": "2025-10-05T12:05:00Z",
    "email": "contact@examplecompany.de",
    "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"
}

Gets the count of contacts in an organization

get

Required Permission: chatbots.organizations.contacts.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

organizationIdstringRequired

The Id of the organization to add a contact to.

Responses

200Success

application/json

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/organizations/{organizationId}/contacts/count

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

{
  "count": 42,
  "error": "text"
}

PreviousConversation contacts NextConversation variables

Last updated 6 days ago