Introduction
Supercharge your GTM tooling in under five minutes
CustomerOS API Reference
The CustomerOS API is organized around REST. All requests are synchronous unless otherwise stated. You should continue to poll the existing endpoint to get data where it is not provided immediately.
Access to each API is currently provided on a per request basis - reach out to the team in order to get enabled for each set of endpoints.
Authentication
All API endpoints are authenticated using a custom header with your API key:
Versioning
When backwards-incompatible changes are made to the API, we release a new version.
You can tell which version is referenced by looking at the version path (/v1/) path in the URL.
Errorrs Errors
CustomerOS uses conventional HTTP response codes to indicate success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate failure given the information provided and codes in the 5xx range indicate an issue with CustomerOS.
If an error should be handled programmatically (i.e. an action that you have requested is not possible to be completed) the response will include an error code with a brief description of the error being faced.
Error Code Summary
| Code | Name | Description |
|---|---|---|
200 | OK | Everything worked as expected. |
400 | Bad Request | The request was unacceptable, often due to missing a required paramater. |
401 | Unauthorized | No valid API key provided. |
402 | Request Failed | The parameters were valid but the request failed. |
403 | Forbidden | The API key doesn’t have permissions to perform the request. |
404 | Not Found | The requested resource does not exist. |
409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
429 | Too Many Requests | Too many requests hit the API too quickly. We recommend exponential backoff of your requests. |
500, 502, 503, 504 | Server Errors | Something went wrong on CustomerOS’s servers. |