The Talkable API is built on HTTP. Our API is RESTful, returns JSON and responds with standard HTTP response codes to indicate errors.

Base URL

All API URLs referenced in this documentation start with the following base part:


You authenticate to the Talkable API by providing your API Key in the request. You can manage your API key in the Account Settings.


Keep your API key secret!

You should not embed the API key within a web page and make Talkable API calls within JavaScript running within a browser. Once someone has your API key, they could create their own API calls.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

Example Request

curl '' \
  -u i9uil7nQgDjucCiTJu:

curl uses the -u flag to pass basic auth credentials. (Adding a colon after your API key prevents curl from asking for a password.)

If you need to authenticate via bearer auth (e.g., for a cross-origin request),
use -H "Authorization: Bearer i9uil7nQgDjucCiTJu"
instead of -u i9uil7nQgDjucCiTJu:.

Response Format

The API returns JSON-encoded objects (content-type: application/json).

Responses vary according to the method used, but every successful response envelope includes these common parts:

{"ok": true, "result": ...}

Date Format

Talkable returns JSON for all API calls. JSON does not have a built-in date type, dates are passed as strings encoded according to ISO 8601. This format is supported by most programming languages out of the box:



The following represents a common JSON error response resulting from a failed Talkable API call:

{"ok": false, "error_message": "Message describing the error"}

Most error messages that Talkable API will return are not meant to be shown to the user. We expect your service to gracefully handle errors and only show meaningful information to the user.

Talkable returns standard HTTP response codes.



200, 201

Everything worked as expected


Bad Request - Often missing a required parameter


Unauthorized - No valid API key provided


Not Found - The requested item doesn’t exist


Unprocessable Entity - The requested create, update, or delete cannot be performed due to validation errors.
See the response body for more details.

500, 502, 503, 504

Server Errors - Something is wrong on Talkable’s end