Crescendo Lab API (2.1.0)

Overview

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

Authentication

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 keyvalue
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.

Errors

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.

statuserror.codewhen
401AUTH_NOT_AUTHENTICATEDthe key is missing, unknown, disabled or expired
403PERMISSION_DENIEDthe key's organization is not enabled for the product in the path
404NOT_FOUNDno endpoint matches the path
429RATE_LIMITEDthe rate limit is exceeded; see rate limits
502 / 503 / 504SERVICE_UNAVAILABLEthe service behind the gateway did not answer

Each endpoint documents the further codes it returns.

I get a 401

The body's error.code is AUTH_NOT_AUTHENTICATED. Confirm the key is sent in the x-api-key header and is not revoked. Then check the region: a key belongs to one region, so a Taiwan key used against the Japan host fails exactly like a bad key.

Rate limits

Requests are limited per second. Every operation belongs to one of two classes:

classlimit
Messaging150 requests per second
Others200 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.

productoperationendpoint
MAACSend personalized messages (send_message)POST /maac/openapi/v2/message/send/
IntegrationSend 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.

I get a 429

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.

MCP (Model Context Protocol)

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

regionURL
Taiwan / Thailandhttps://mcp.user360.cresclab.com/mcp
Japanhttps://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.

Install

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.

Example prompts

Once connected, ask in plain language; the assistant picks the tools.

  • "Find the contacts whose email ends in @acme.com and 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).

Privacy

Tool calls carry your organization's data between the assistant and User360. How Crescendo Lab handles it is described in the Privacy Policy.

Servers
Asia server
https://api.user360.cresclab.com
JP server
https://api.user360.jp.cresclab.com