Crescendo Lab API (2.1.0)
If you would like to integrate with the Crescendo Lab API, please contact our support: help@cresclab.com
Crescendo Lab API is used to query unified contact profile, engagement history, and subscribe webhook events from Crescendo Lab. Do not use http when connecting with API, please use https to avoid insecure data transmission.
- If you are using Crescendo Lab product in the Taiwan or Thailand region, please use
https://api.user360.cresclab.com - If you are using Crescendo Lab product in the Japan region, please use
https://api.user360.jp.cresclab.com
Send your API key in the x-api-key HTTP header to call any endpoint in this document. The legacy apikey header is still accepted.
| header key | value |
|---|---|
| x-api-key | {API key} |
Creating a key — sign in to Admin Center and go to Applications → OpenAPI. The full key is shown once, at creation time: copy it then. Afterwards the list shows only a masked value and the key cannot be recovered.
Managing keys — the same page renames a key, disables it (requests carrying it are rejected until it is enabled again) or revokes it (deleted permanently, cannot be restored).
If that page asks you to contact your CSM instead of listing keys, the organization is not enabled for OpenAPI v2 yet.
A request rejected before it reaches an endpoint — a missing key, a rate limit, an unknown path — gets the same error body the endpoints return:
{
"error": {
"code": "AUTH_NOT_AUTHENTICATED",
"message": "No API key found in request"
},
"request_id": "0f7b7a5b-b319-4720-ae77-046107b2982b#4"
}
Branch on error.code; error.message is for people and may change. request_id equals the Cl-Request-Id response header — include it when you contact support.
| status | error.code | when |
|---|---|---|
| 401 | AUTH_NOT_AUTHENTICATED | the key is missing, unknown, disabled or expired |
| 403 | PERMISSION_DENIED | the key's organization is not enabled for the product in the path |
| 404 | NOT_FOUND | no endpoint matches the path |
| 429 | RATE_LIMITED | the rate limit is exceeded; see rate limits |
| 502 / 503 / 504 | SERVICE_UNAVAILABLE | the service behind the gateway did not answer |
Each endpoint documents the further codes it returns.
Requests are limited per second. Every operation belongs to one of two classes:
| class | limit |
|---|---|
| Messaging | 150 requests per second |
| Others | 200 requests per second |
Limits are counted per organization (API account): every API key of the organization draws on the same quota. Each product — MAAC, CAAC, CDH and Integration — is counted separately, with the same limits in every product, and the two classes are counted separately too.
Messaging operations are the ones below. Every other operation in this document falls under Others.
| product | operation | endpoint |
|---|---|---|
| MAAC | Send personalized messages (send_message) | POST /maac/openapi/v2/message/send/ |
| Integration | Send a message from an Insider journey (harmony_insider_message_send) | POST /integration/insider/openapi/v2/message/send/ |
Requests made through the MCP server use the same API key and count against the same quota.
A request over the limit is rejected with 429 Too Many Requests and is not processed. The body uses the standard error format:
{
"error": {"code": "RATE_LIMITED", "message": "API rate limit exceeded"},
"request_id": "<request id>"
}
The limits are per second, so wait at least one second before retrying, and back off exponentially if the retry is rejected again.
Every endpoint in this document is also exposed as an MCP tool so that AI assistants (Claude Code, claude.ai, Claude Desktop) can call the Crescendo Lab API directly. The MCP server is a thin protocol translator — it forwards each tool call to the same API surface documented here, so available operations and request shapes match this doc exactly, and tool calls count against the same rate limits as direct API calls.
Endpoint
| region | URL |
|---|---|
| Taiwan / Thailand | https://mcp.user360.cresclab.com/mcp |
| Japan | https://mcp.user360.jp.cresclab.com/mcp |
Authentication is a browser sign-in: the client opens a Crescendo Lab sign-in page, and approving it issues the key the MCP server uses. An API key from your API key page does not work against the MCP server.
Claude Code
claude mcp add --transport http crescendo-lab \ https://mcp.user360.cresclab.com/mcp
then run /mcp inside Claude Code and choose Authenticate to sign in.
claude.ai — and Claude Desktop and Cowork, which are the same app and take the same connector. All three install a connector rather than a config file and sign you in themselves, so there is no key to paste or store. Add it in Settings → Connectors → Add custom connector with this URL:
https://mcp.user360.cresclab.com/mcp
and leave Advanced settings empty — Claude identifies itself to this server on its own. Connectors added earlier with the OAuth client ID mcp-wrapper-public in that dialog keep working and need no change.
Connecting opens a Crescendo Lab sign-in page on mcp.user360.cresclab.com: work email, password, then the organization Claude will act in, then Approve. What you approve is an ordinary API key, issued in that organization and named claude.ai-<your email>. It appears in Admin Center on the same API key page as the keys you create yourself, grants the same access one of those grants, and is revocable there at any time; revoking it disconnects the connector. Connecting again issues another key rather than reusing the first, so delete the ones you have stopped using.
Two things end the flow on that page rather than in Claude: an organization without OpenAPI v2 enabled is declined with the reason on screen, and an account Admin Center does not recognise offers no organization to choose. Both need an administrator, not a retry.
Single sign-on is not available on this page yet. If your domain is configured for SSO only, the page will say it has no way to sign you in.
Once connected, ask in plain language; the assistant picks the tools.
- "Find the contacts whose email ends in
@acme.comand show their names and tags." — searches contacts (cdh_search_contacts). - "Of the broadcasts we sent last month, which one drew the most link clicks?" — lists broadcasts (
list_broadcasts) and reads each one's performance report (get_broadcast). - "Tag every contact who ordered in the last 30 days with
recent-buyer." — finds the contacts and attaches the tag in bulk (cdh_bulk_attach_tags).
Tool calls carry your organization's data between the assistant and User360. How Crescendo Lab handles it is described in the Privacy Policy.