Overview

Authentication

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:

curl -u API_KEY:DUMMY_PASSWORD API_URL

For instance, if your API key is 60783dd23ef, you would execute:

curl -u 60783dd23ef:X https://api.helpscout.net/v1/mailboxes.json

Endpoints

All API requests are made to https://api.helpscout.net/and all requests are served over HTTPS. The current version is v1.

Formats

Each endpoint specifies the response format in the URL. However, the API will only support JSON at this time.

Rate Limiting

Requests are limited to 200 requests per minute per account. All API keys associated with the same account count against the minute rate limit. Response code 429 is returned when the throttle limit has been reached. A "Retry-After" header is returned indicating how many seconds to wait until retry.

Response Envelopes

The API returns one of three envelopes depending upon the request issued:

  1. Single Item Envelope
  2. Collections Envelope
  3. Error Envelope

Single Item Envelope

All dates/times are returned in ISO8601 format and in UTC timezone.

Status: 200 OK
{
	"item": {
		"id": 1234,
		...
		"createdAt": "2012-07-17T13:41:01Z"
	}
}

Collections Envelope

All dates/times are returned in ISO8601 format and in UTC timezone. Collections return a maximum of 50 records per page.

Status: 200 OK
{
	"page": 1,
	"pages": 24,
	"count": 1154,
	"items": [
		{
			"id": 1234,
			...
			"createdAt": "2012-07-17T13:41:01Z"
		},
		{
			"id": 5678,
			...
			"createdAt": "2012-07-15T08:12:15Z"
		},
		...
	]
}

Error Envelope

Status: 403 Forbidden
{
	"status": 403,
	"message": "The specified resource was not found: '/v1/fake'"
}