​
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. You can find API endpoint documentation in the dropdown on the top left of the nav panel to the left.
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: 
"X-CUSTOMER-OS-API-KEY": "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

CodeNameDescription
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, often due to missing a required paramater.
401UnauthorizedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesn’t have permissions to perform the request.
404Not FoundThe requested resource does not exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429Too Many RequestsToo many requests hit the API too quickly. We recommend exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething went wrong on CustomerOS’s servers.