Your API Key
Each User has a Docs API key, which is separate from any Mailbox API keys. To generate, view, or regenerate the API key, click the "person" icon on the top right of your account, next to the search, then click Your Profile.
Next, click the Authentication link in the menu on the left and select API Keys tab
Note: If you don't see an API key in your profile, that's because you haven't been granted the "Docs: Create new, edit settings & Collections" permission by the Account Owner or an Administrator.
This is an HTTPS-only API. Authentication is based on API keys. Each API key is associated with a Help Scout user. Results returned from various responses are based upon the role of the user to which the API key is tied.
The API key is passed via HTTP Basic Authentication and goes in the username field. A dummy password, such as X, goes in the password field.
To try the API via curl on the command-line, the general form used would be:
For instance, if your API key is 60783dd23ef, you would execute:
All API requests are made to https://docsapi.helpscout.net/ and all requests are served over HTTPS. The current version is v1.
The API will only support JSON at this time.
Correlation ID Response Header
All responses from the API contain a Correlation-Id header. This header contains a value (a UUID) which is used by Help Scout to trace interactions between our various APIs. In the case of an error and you're contacting the Help Scout team then include one or more of these IDs and developers will be able to assist quicker.
For instance if you wanted to print all headers on a curl request to access the Correlation-Id you would do the following:
You would see console output like the following:
Each account is allowed to make a limited number of requests per 10 minute period. This limit is based on the number of Docs Sites the account has:
|Number of Sites||Rate Limit|
|1||2000 requests every 10 mins|
|2||3000 requests every 10 mins|
|3 or more||4000 requests every 10 mins|
Headers are returned with every API response to detail the current rate limiting status:
|X-RateLimit-Limit||The maximum number of requests the account is permitted to make per 10 minute period|
|X-RateLimit-Remaining||The number of requests remaining in the current rate limit window|
|X-RateLimit-Reset||The number of seconds until the current rate limit window expires|
Response code 429 is returned when the limit has been reached.
Note: Usage of the Help Scout Docs administration interface generates requests to Docs API. These requests also count towards the rate limit.
The API returns one of three envelopes depending upon the request issued:
- Single Item Envelope
- Collections Envelope
- Error Envelope
Single Item Envelope
All dates/times are returned in ISO8601 format and in UTC timezone.
All dates/times are returned in ISO8601 format and in UTC timezone. Collections return a maximum of 50 records per page.