> ## 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 one organization with an optional preserved ID. Requires cxm:organizations.write. Duplicate names are allowed; this endpoint does not match or update by name. Preserve IDs or save the returned source-to-CXP mapping for repeated imports. Requires the matching tenant API-key write scope or broader scope. Maximum JSON request body: 1 MiB, subject to a lower configured gateway limit. Unknown fields are rejected. Each accepted request executes; no idempotency or replay guarantee. A timeout may occur after commit. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /api/v1/cxm/tenants/{tenantId}/organizations openapi: 3.1.0 info: title: Crescendo CXP API version: 1.0.0 description: >- Use the Customer Experience Platform API from trusted server-side applications to create Contacts and Organizations, import historical Conversations, create live Conversations, read projected detail and stored history, update operational fields, assign work, and add internal notes. Writes execute independently; repeating a write may repeat its effects. servers: - url: https://platform.crescendo.ai description: Production security: [] tags: - name: Conversations description: Create, import, continue, and manage customer conversations. - name: Contacts description: Create contacts for backend integrations and historical imports. - name: Organizations description: Create organizations for historical conversation references. paths: /api/v1/cxm/tenants/{tenantId}/organizations: post: tags: - Organizations summary: Create an organization description: >- Create one organization with an optional preserved ID. Requires cxm:organizations.write. Duplicate names are allowed; this endpoint does not match or update by name. Preserve IDs or save the returned source-to-CXP mapping for repeated imports. Requires the matching tenant API-key write scope or broader scope. Maximum JSON request body: 1 MiB, subject to a lower configured gateway limit. Unknown fields are rejected. Each accepted request executes; no idempotency or replay guarantee. A timeout may occur after commit. operationId: createOrganization parameters: - name: tenantId in: path required: true description: Tenant authorized for the API key and every referenced resource. schema: type: string minLength: 1 maxLength: 255 example: tenant_demo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrganizationRequest' example: organization: organizationId: external-org-123 name: Example Ltd responses: '201': description: Organization created. content: application/json: schema: $ref: '#/components/schemas/CreateOrganizationResponse' example: organization: organizationId: external-org-123 result: created '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/PermissionDenied' '409': description: A supplied ID or identity conflicts with existing tenant data. content: application/json: schema: $ref: '#/components/schemas/Error' examples: id: value: code: OrganizationIdConflict message: Organization ID already exists existingOrganizationId: external-org-123 '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' security: - BearerApiKey: [] components: schemas: CreateOrganizationRequest: type: object additionalProperties: false required: - organization properties: organization: $ref: '#/components/schemas/CreateOrganizationInput' CreateOrganizationResponse: type: object additionalProperties: false required: - organization properties: organization: type: object additionalProperties: false required: - organizationId - result properties: organizationId: type: string minLength: 1 maxLength: 255 result: type: string const: created Error: type: object additionalProperties: false required: - code - message properties: code: type: string enum: - BadRequest - InvalidCustomField - Unauthenticated - PermissionDenied - EmailChannelNotFound - AssigneeNotFound - NotFound - EmailChannelDisabled - ContactIdentityConflict - OrganizationAmbiguous - AssigneeAmbiguous - Conflict - PayloadTooLarge - RateLimitExceeded - BadGateway - ServiceUnavailable - GatewayTimeout - ContactIdConflict - OrganizationIdConflict - ConversationIdConflict - ContactNotFound - OrganizationNotFound - ContactReadOnly - TeamNotFound - TeamAmbiguous message: type: string existingContactId: type: string minLength: 1 maxLength: 255 description: >- One blocking record ID in a corresponding create/import conflict response. It does not establish that an earlier request had the same payload. existingOrganizationId: type: string minLength: 1 maxLength: 255 description: >- One blocking record ID in a corresponding create/import conflict response. It does not establish that an earlier request had the same payload. existingConversationId: type: string minLength: 1 maxLength: 255 description: >- One blocking record ID in a corresponding create/import conflict response. It does not establish that an earlier request had the same payload. CreateOrganizationInput: type: object additionalProperties: false required: - name properties: organizationId: type: string minLength: 1 maxLength: 255 description: >- Optional preserved organization ID. Omission generates org_. The exact org_ ID is reserved for tenant settings. No whitespace, control characters, /, backslash, %, ? or #, or the exact values `.` or `..`. pattern: ^(?!\.{1,2}$)[^\s\u0000-\u001F\u007F-\u009F/\\%?#]+$ name: type: string minLength: 1 maxLength: 255 description: >- Required trimmed nonblank display name. Duplicate names are allowed; no matching or update by name. responses: BadRequest: description: The body, a field, an unknown property, or a custom field is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: BadRequest message: message.text is required Unauthenticated: description: The API key is missing, invalid, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: Unauthenticated message: Authentication required PermissionDenied: description: The API key does not authorize the tenant or required scope. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: PermissionDenied message: API key does not allow this operation PayloadTooLarge: description: >- The request exceeds the endpoint body limit or a lower configured gateway limit. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: PayloadTooLarge message: CXM API request body must not exceed 1048576 bytes RateLimitExceeded: description: The tenant/API-key/route limit was exceeded. headers: Retry-After: description: Seconds to wait before another request. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/Error' example: code: RateLimitExceeded message: CXM API rate limit exceeded BadGateway: description: >- The gateway could not complete downstream transport. The durable mutation outcome may be unknown. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: BadGateway message: CXM API downstream request failed ServiceUnavailable: description: A required service or durable/configuration dependency is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: ServiceUnavailable message: CXM API is temporarily unavailable GatewayTimeout: description: >- The gateway timed out. The durable mutation outcome may be unknown, and retrying can duplicate effects. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: GatewayTimeout message: CXM API downstream request timed out securitySchemes: BearerApiKey: type: http scheme: bearer description: >- Tenant API key with the operation's scope: `cxm:conversations.read`, `cxm:conversations.write`, `cxm:contacts.write`, or `cxm:organizations.write`. Corresponding resource wildcards and broader `cxm:read`, `cxm:write`, or `cxm:*` scopes apply. Keep it in a trusted backend; do not expose it in browser code. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.