Fundamentals
Requests and responses
Envelope, error shape, trace_id, and the two response contracts — which endpoint uses which.
Two contracts, two contexts
Blesyum has two response shapes, and confusing them is the most common mistake.
Core and module panel endpoints
Envelope: {data, trace_id}
{ "data": { "id": "0193…", "name": "Acme Ltd." }, "trace_id": "01JC7…" }Error:
{ "error": {
"code": "CORE-REQ-0002",
"message": "Validation failed.",
"hint": "validation",
"trace_id": "01JC7…",
"details": [{ "field": "email", "message": "Not a valid email address." }]
} }Public API endpoints (/public/v1/...)
These use an Intercom-compatible shape so existing client libraries work:
{ "type": "list",
"data": [ { "type": "contact", "id": "0193…" } ],
"pages": { "type": "pages", "per_page": 50, "next": { "starting_after": "eyJ…" } } }Error:
{ "type": "error.list",
"errors": [{ "code": "parameter_invalid", "message": "per_page can be at most 150." }] }A module has both panel endpoints and public API endpoints, and their shapes differ. If public appears in the path, expect the second shape.
trace_id — send this when you ask for support
Every response carries a trace_id. If you include it when reporting a problem, we can find the exact request in our logs. Store it on your side too: the difference between "sometimes I get a 500" and "I got a 500 on this trace_id" is the difference between hours of investigation and a five-second lookup.
The error code is a CONTRACT
code is stable and shaped DOMAIN-AREA-NNNN:
CORE-AUTH-0001 core · auth · 401
CORE-REQ-0002 core · request · 422 (validation)
CRM-LIC-0001 CRM · licence · 403
ERP-FATURA-0007 ERP · invoicing · module-specificBranch on code, not on message. message is translated to the reader's language and improves over time; code does not change.
Full list: Error codes.
Content type and encoding
- Request body:
application/json, UTF-8 - Response:
application/json; charset=utf-8 - Dates: RFC 3339, UTC (
2026-08-21T09:14:00Z) - Money: integer minor units plus a separate
currencyfield — we do not use floating point (to avoid the 0.1 + 0.2 problem)
Body size
The default ceiling for JSON endpoints is 1 MiB. Upload endpoints have their own, wider ceilings; exceeding it gives 413 and CORE-REQ-0006.
Time
Server time is canonical. No endpoint makes a duration or access decision based on a date sent by the client; trial, licence and session decisions are all made server-side. If your own UI shows "days remaining", take the reference from GET /api/v1/time — a device clock is an opinion, not evidence.