Overview

Generating an API Key

The API is available for paying Help Scout accounts. A key can be generated from your User Profile, on the API Keys tab:

Generate an API Key

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.

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

Rate Limiting

Requests are limited to 5,000 per hour. 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.

Status Codes

Code Description
200 Request succeeded
201 The request to POST or PUT a record was successful. A Location HTTP header is returned
204 The request to DELETE a record was successful
400 The request was not formatted correctly
401 Invalid API Key
402 API key suspended
403 Access denied
404 Selected resource was not found (ie. User asked for non-existent item or URL)
405 Invalid method type (GET when you should POST, etc)
409 Resource being created already exists (i.e. a customer with the same email address)
429 Too Many Requests (i.e. throttle limit reached)
500 Application error or server error
503 Service Temporarily Unavailable