Authentication (v2)

The v2 API (contacts, contact lists and segments) is authenticated with the API token you obtain from Obtain API token.

Note

v1 and v2 authenticate differently. v2 accepts only the X-API-Key header. The Authorization: Basic <token> flavor accepted by v1 is not supported here.

Header

Send your token in the X-API-Key header on every request:

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

Errors

Status code	Meaning
401	Missing or invalid X-API-Key, or token not linked to a profile.
429	Rate limit exceeded (see below).

Rate limiting

v2 endpoints are rate limited per API key at 60 requests per minute. Every response includes headers describing your current budget:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window.
X-RateLimit-Remaining	Requests still available in the current window.
X-RateLimit-Reset	Seconds until the limit window resets.

When the limit is exceeded the API responds with 429 Too Many Requests and a Retry-After header indicating how many seconds to wait before retrying.

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

Tip

Build retry/backoff into your integration: when you receive a 429, wait the number of seconds in Retry-After before sending the next request.