Skip to main content
The CRM API returns JSON. The exact body shape depends on the status code and the endpoint.

​
Content type

​
Writes return a location header and no body

Creating a guest, creating a segment, and updating either of them return 200 OK with an empty body and a location header holding the path of the resource:
On a creation, the last path segment is the identifier to store on your side. On an update, the header points back at the resource you changed. Nothing in the response says what was stored. An attribute carrying a value the API rejects, such as a gender outside M, F, and X, is dropped and the status code stays 200. Read the guest back with Get a guest when the write matters.

​
Long operations return a task

Merging guests and computing a merge confidence run in the background. They return 200 OK with an empty body and a location header pointing at a task:
Read that path with Read a task until status reaches completed or failed. A completed task carries its result: the confidence score for a computation, and for a merge an object whose rid ends with the identifier of the merged profile.
A failed task carries an error instead. The identifiers you already hold keep working after a merge and redirect to the merged profile, as described in Best practices.

​
Error format

Errors return a JSON body with three fields:
​
string
A machine-readable code, such as system.invalidParams or system.accessDenied.
​
string
A human-readable summary.
​
object
Details specific to this occurrence, such as the invalid property and the reason. Absent on some errors, 401 among them.

​
Response codes

​
200 OK

The request was processed. The body depends on the endpoint: a guest, a segment, a count, a document list, an operation result, or nothing at all on the endpoints that answer with a location header.

​
204 No Content

The request succeeded and there is nothing to return: deleting a segment.

​
400 Bad Request

The request failed validation, with the code system.invalidParams (URL parameters) or system.invalidQuery (request body). The data object says which property is invalid. Fix the request before retrying.

​
401 Unauthorized

The bearer token is missing, invalid, or does not give access to the entity. The code is system.accessDenied, and the three cases share one response so an entity you cannot reach is indistinguishable from one that does not exist. See Authentication.

​
404 Not Found

The guest, segment, or task identifier does not match an existing resource. The code is system.notFound.

​
408 Request Timeout

The service did not answer in time, with the code system.timeout. Retry later with backoff.

​
500 Internal Server Error

The code is system.internalError. On this API, a 500 often points at the request rather than the server: an attribute sent in the wrong shape, such as an email as a plain string instead of an object, fails this way. Check the body against Requests before anything else. Treat a 500 as transient only on reads, where a retry with exponential backoff is safe. If it persists, contact us.