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.

Formats

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

Request size

Maximum allowed request size is 100kB by default. There are two exception - 10MB for Create attachment endpoint and 256kB for Create conversation endpoint. The API will return response code 413 when the request size was exceeded.

Rate Limiting

Basic 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. Applicable to all requests

Burst write rate limiting

Write requests (POST, PUT, DELETE) have an additional limit of 12 requests every 5 seconds per account. Read requests (GET) are not subject to this limit

Response headers

Example headers

X-RateLimit-Interval-burst: 5
X-RateLimit-Interval-minute: 60
X-RateLimit-Limit-burst: 12
X-RateLimit-Limit-minute: 200
X-RateLimit-Remaining-burst: 12
X-RateLimit-Remaining-minute: 199

Maximum URL Length

The maximum length for a URL is 4000 bytes.

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'"
}