> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cxp.crescendo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an organization

> Create a CXP organization to reference from imported conversations.

# Create an organization

Create an organization before referencing it in an
[imported conversation](https://docs.cxp.crescendo.ai/developers/import-conversation.md):

```http theme={null}
POST /api/v1/cxm/tenants/{tenantId}/organizations
```

Use a tenant API key with `cxm:organizations.write` or a broader scope. See the
[API overview](https://docs.cxp.crescendo.ai/developers/api-overview.md) for authentication and common limits.

## Send a request

```bash theme={null}
curl --request POST \
  --url "https://platform.crescendo.ai/api/v1/cxm/tenants/tenant_demo/organizations" \
  --header "Authorization: Bearer $CXP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "organization": {
      "organizationId": "external-org-123",
      "name": "Example Ltd"
    }
  }'
```

`name` is required, trimmed and nonblank, with a maximum of 255 characters.
`organizationId` is optional; omitting it generates an `org_<uuid>` ID.

A supplied ID must be nonblank and at most 255 characters. It cannot contain
whitespace, control characters, `/`, `\`, `%`, `?` or `#`, and cannot equal `.`
or `..`. The exact ID `org_<tenantId>` is reserved for tenant settings.

The endpoint accepts only `organizationId` and `name`. It does not accept tags,
website, custom fields, historical timestamps or contact associations.

## Save the created ID

A successful request returns `201 Created`:

```json theme={null}
{
  "organization": {
    "organizationId": "external-org-123",
    "result": "created"
  }
}
```

Duplicate names are allowed. A name is a display value, not a unique identity;
CXP does not match or update an organization by name through this endpoint.
For repeatable imports, preserve source IDs or save the returned ID mapping.

An existing ID returns `409 OrganizationIdConflict` with
`existingOrganizationId`. This does not establish that the existing record has
the same name or came from an earlier identical request. See
[common errors and retry behavior](https://docs.cxp.crescendo.ai/developers/api-overview.md#responses-and-errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.