Authentication

The Inboxroad Contacts API is authenticated using the API token you obtain from Obtain API token.

Authentication header

The Contacts API only accepts authentication through the X-API-Key header.

Send your API token with every request:

curl -X GET 'https://webapi.inboxroad.com/api/v2/contacts-lists/' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Error responses

Status code	Description
401	Missing or invalid `X-API-Key`, or the token is not linked to a customer profile.
422	A path parameter, query parameter or body field failed validation.
429	Rate limit exceeded. See Rate limiting.

Each endpoint documents the full set of codes it can return.

Validation errors

A 422 body maps each rejected field to a list of messages. The key is the field name, so page, blueprint_id and a body field all report the same way:

{
  "range": ["Input should be 'today', 'yesterday', 'three_days', 'last_week', 'two_weeks' or 'last_month'"],
  "page": ["Input should be a valid integer, unable to parse string as an integer"]
}

Errors that are not field-specific are grouped under non_field_errors.

Rate limiting

All v2 endpoints are rate limited per API key.

Each API key is limited to:

60 requests per minute

Every response includes headers that show your current rate limit usage:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed in the current window.
X-RateLimit-Remaining	Remaining requests available in the current window.
X-RateLimit-Reset	Number of seconds until the rate limit window resets.

If the limit is exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{
  "errors": ["Too many requests."]
}

The Retry-After header indicates how many seconds you should wait before retrying the request.