API Documentation

The API is organized around REST. The API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code). JSON will be returned in all responses from the API, including errors.

You should note that there is a 'test' server instance of the API available. You should use the test server for all implementation and testing-related needs. The base URL and your client_id and api_key will likely be different in test vs. production.

The requests in the sidebar actually work. We'll perform the requests using your client ID and your API key,

Date Format

yyyyMMddHHmmssZ

UTF-8 Encoding

Authentication

You authenticate to the API by providing one of your API keys in the request. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via HTTP Basic Auth. Provide your client Id as the basic auth username and your API key as the basic auth password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Note: Different calls may have a different mechanism for authentication based on the usage pattern of the call.

Errors

The API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with the API servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully, we return a 400 error code.

All errors return JSON with a type (see 'type' in response) and message describing the particular problem to the developer.

Attributes

type

The type of error returned (ParamValueException, etc) Generally you should not expect to see errors from the API unless you're requesting invalid data or incorrectly requesting information. API errors cover any other type of problem (e.g. a temporary problem with the API servers) and should turn up only very infrequently. Based on the type of error you may see additional information to utilize (param_value_error also provides a 'paramTypeName' and a 'message' so you can see why the parameter is causing an issue)

Catching errors

The API bindings can raise exceptions for many reasons, such as invalid parameters, authentication errors, and network unavailability. We recommend always trying to gracefully handle exceptions from our API.