Overview

The Pronto REST API allows developers to integrate programmatically with Pronto to manage users, chats, messages, and more.

The Pronto REST API is a work in progress. We are continually adding new endpoints and functionality. If there's something you need that the API doesn't provide, please let us know so that we can better prioritize our API work.

Root URL

https://api.pronto.io/api/

Authentication

To use the API you must first create an API Token from within the Pronto app (API Token management is currently supported on Web and iOS). To do so, click on the gear icon next to your organization name to enter your user settings, then select the "API Tokens" option.

When creating a token you will need to make sure you select the scopes appropriate for the task you want to perform with the token.

Once you have an API token, include it in your request's HTTP header using Bearer Authentication:

Authorization: Bearer <token>

Note: You must be an admin and the integrations feature must be enabled for your organization in order for the "API Tokens" option to appear. Contact Pronto support to have integrations enabled or for help troubleshooting API tokens.

Conventions

Endpoints with response data will include a data property that will contain the object or objects specified in the documentation for that endpoint. Depending on the endpoint the data property may be an object or an array of objects.

{
  "data": ...,
}

For example, the GET /users/me endpoint will return a single user object:

{
  "data": {
    "id": 30,
    "first_name": "Paul",
    "last_name": "Atreides",
    "profile_pic_url": "https://files.chat.trypronto.com/files/users/30/profilepic?pronto_time=1547585053",
    "role": "user",
    "active": true,
    "created_at": "2017-07-14T18:36:07Z",
    "updated_at": "2021-10-26T19:57:47Z"
  }
}

The GET /organization/users endpoint will return an array of user objects:

{
  "data": [
    {
      "id": 45889,
      "first_name": "Gurney",
      "last_name": "Halleck",
      ...
    },
    {
      "id": 45888,
      "first_name": "Lady",
      "last_name": "Jessica",
      ...
    },
    ...
  ]
}

Errors

Errors are broadly characterized by the HTTP status code (e.g. 404 for resources that don't exist or are not accessible, 403 when unauthorized, 422 when validation fails). Errors may also include a JSON response object that contains a message property giving more details about the error.

Example:

404 Not Found
{
  "message": "User is not authorized to perform that action"
}

An error with a 400 HTTP status code will also include a separate code property that can be used to programmatically distinguish certain important error cases. Individual endpoints will specify the possible values for code.

Example:

400 Bad Request
{
  "code": "INVALID_FILE_KEY",
  "message": "Invalid or expired attachment_file_key"
}

Please see Error Responses for more details.

Pagination

When an endpoint returns a collection of multiple resources the response will be paginated. The Pronto API uses cursor-based pagination to make it easy to fetch the next and previous pages.

When calling and endpoint that returns a collection of multiple resources, you will receive the standard data object that is an array of objects, plus two other pagination-related objects: links and meta.

The next and previous properties in the links object will instruct you which URL to call to get the next or previous pages of the request. previous will be null when you are on the first page, and next will be null when you are on the last page. Both next and previous will be null when there is no more than 1 page of results.

The per_page property in the meta object will tell you how many results are being return per page.

Note: The first and last properties of the links object not used with cursor-based pagination

{
  "data": [...],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https://api.pronto.io/api/organization/users?cursor=eyJpZCI6NDU3MzksIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  },
  "meta": {
    "path": "https://api.pronto.io/api/organization/users",
    "per_page": 20
  }
}

## Rate Limiting

Requests are rate limited per organization, with separate budgets for different cost tiers of endpoints. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers, and requests over the limit are rejected with a `429` status and a `Retry-After` header. See [Rate Limiting](/rate-limiting) for the tiers and how to handle them.

Error Responses