Overview

Generating an API Key

The API is currently available for paying Help Scout accounts (Basic or Standard plan). You can generate a key from your User Profile, on the API Keys tab:

Authentication

This is an HTTPS-only API. Authentication will be based on API Keys, which can be generated using the Help Scout UI in the User Profile. Each API Key will map to an existing Help Scout user. Results returned from various responses will be based upon the role of the user to which the API key is tied.

The API Key will be passed via HTTP Basic Authentication. The API Key will go in the username field and a dummy password, such as X, in the password field.

To try the API via curl on the command-line, the general form used would be:

For instance, if we had an API key of 60783dd23ef, you would execute:

Endpoints

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

Formats

Each endpoint will specify the response format in the URL. However, the API will only support JSON at this time. We may introduce or support other formats at a later date.

Response Envelopes

The Help Scout API will return one of three envelopes, depending upon the request issued.

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

Single Item Envelope

All date/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 date/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'"
}

Rate Limiting

Requests will be limited to 200 requests per minute. Response code 429 will be returned when the throttle limit has been reached. A "Retry-After" header will be returned indicating how many seconds to wait until retry.

Status Codes

Page last updated on November 16, 2012