Getting started with Dialog takes just a few minutes.

Interact with the API via its HTTP endpoint or using an official wrapper for ruby or node. Please take note that official wrappers for these languages are coming: Clojure, Go, Java, PHP, Python, and .NET.

The Dialog API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

Sandbox account

All code examples in this documentation use the test API token, which makes requests to a sandbox account (for testing purposes only).

Authenticate by including your secret API key in the request. Your API key carry many privileges, so be sure to keep it secret! Do not share your secret API key in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API can be performed via the request's URL token parameter or by including an AUTHORIZATION Token your-api-token header with your API token.

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

In order to send data to our HTTP API, a content-type header must be set to 'application/json'.

Dialog uses conventional HTTP response codes to indicate the 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 failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with Dialog's servers.

Status Description
200 - Ok The request has succeeded.
201 - Created The request has been fulfilled and has resulted in one or more new resources being created.
400 - Bad Request
401 - Unauthorized The request has not been applied because it lacks valid authentication credentials for the target resource.
403 - Forbidden The server understood the request but refuses to authorize it.
404 - Record Not Found
404 - Routing Error Nothing exists at this endpoint.
413 - Payload Too Large Request payload is larger than expected.
422 - Record Invalid The request was unacceptable, all required parameters are present, but some parameters are invalid.
422 - Record Not Unique The request was unacceptable due to a non-unique attribute.
422 - Parameter Missing The request was unacceptable due to missing a required parameter.
429 - Too Many Requests
500 - Internal Server Error Something went wrong on Dialog's end. These are rare.

API calls are rate limited to 1000 per minute. Once you go over the rate limit you will receive an error. If you’re running into this error often and think you’ll need a higher rate limit, drop us a line at

Header Name
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per period.
X-RateLimit-Remaining The number of requests remaining in the current rate limit period.
X-RateLimit-Reset The time at which the current rate limit window resets in Unix time format.

When we make backwards-incompatible changes to our API, we release new dated versions. The latest version is v1.