Skip to main content

​
CXP API overview

Use the CXP API to connect trusted websites, portals, and backend automations to your customer experience workflows. The first available endpoint creates or continues a conversation from a structured form submission.

​
Prerequisites

Before you send a request, obtain these values from your Crescendo contact:
  • Your tenant ID
  • A tenant API key with the cxm:conversations.write scope (or a broader CXP write scope)
  • The production API base URL
Keep API keys in a server-side secret store. Never put an API key in browser, mobile app, or public form code. Send requests over HTTPS.

​
Authenticate

Send the API key as a bearer token:
The tenant in the URL and every ID, email channel, agent, or team referenced by the request must belong to the API key’s authorized tenant. Write endpoints do not accept a bearer token in the query string.

​
Request conventions

  • Use Content-Type: application/json.
  • Keep the complete JSON body at or below 1 MiB.
  • Unknown request properties are rejected.
  • Optional blank strings are treated as absent where the endpoint permits them.
  • Email addresses are trimmed and normalized to lowercase; phone numbers are normalized to E.164 format.
You may send X-Request-Id or X-Correlation-Id to help Crescendo support trace a request. These headers are tracing identifiers only. They do not make a request idempotent or suppress duplicate work.
Every accepted POST executes. Repeating a request can create another conversation or append another customer message. If a timeout or transport error makes the outcome unclear, verify the result before retrying when possible.

​
Responses and errors

Success responses contain the result of the requested operation. They can also contain a warnings array when the primary operation succeeded but a documented best-effort follow-up did not. Treat warnings according to the endpoint guide; they are not error responses. Errors use a stable JSON envelope:
For 429 RateLimitExceeded, wait for the number of seconds in the Retry-After response header. A 502 or 504 can have an ambiguous mutation outcome; retrying can duplicate the effect.

​
Next step

Follow Create a conversation for request mappings, routing behavior, and copyable examples. Open API reference in the developer navigation for the generated operation and machine-readable contract.