API overview

The Engage API lets you interact with data and resources through REST. The API accepts requests in JSON format, returns responses in JSON, and uses standard HTTP for authentication, methods, and response codes.

Authentication

Authentication is via HTTP Basic Authentication using your API key as username and API secret as password. You can view and manage these keys on the settings page of your account dashboard. On some endpoints, you can use just your API key (as username) and leave the secret empty. This makes it possible to call such endpoints from client-side applications. Endpoints that support this are marked with “works with username authentication”.

API Root

https://api.engage.so/v1

Requests have to be HTTPS or it won’t work.

Versioning

The current API version is v1.

Errors

Errors are returned with standard HTTP status codes. Error responses will come with an additional body in the format:

{"error": "More details about error"}

Pagination

The API uses cursor-based pagination. Responses for list requests will come with a next_cursor and/or previous_cursor parameter. If you need to get the next page of the dataset, make a request with the next_cursor parameter. To get the previous page of the dataset, make a request with the previous_cursor dataset.

{
  "data": [...],
  "next_cursor": "60583d4a60ad2a26042a9499"
}

api.engage.so/v1/users?next_cursor=60583d4a60ad2a26042a9499

You can only use one of next_cursor and previous_cursor in a request.

An earlier version of the API lets you use the id field of the resource object to request the previous or next page of the dataset by making a request with the parameters: after_id and before_id set to the id. This pagination style has now been deprecated and is not recommended.

{
  "data": [{
    "id": "60583d4a60ad2a26042a9499"
    ...
  }],
  "has_more": true
}

api.engage.so/v1/users?after_id=60583d4a60ad2a26042a9499

Resources

• Users

• Lists

• Batch requests

More resources coming soon.