API Overview
The public Rest API currently supports creating, updating, retrieving and listing Users, Accounts, Conversations, Tasks, Notes and NPS Responses.
It uses an API Key header for authentication.
List endpoints use cursor-based pagination, ordered by updatedAt (the default) or createdAt.
All REST API Activity Object requests include parent object details in the payload. For example, a request to GET a Task will also returns the associated Account information.
Authentication
The authentication is passed via the Authorization header on every request.
Keys can be created in the Vitally UI by navigating to your Settings (⚙️) by selecting your Account Logo on the top left and under Connectors select Integrations. Then select Vitally REST API (or via Quick Jump Mac: ⌘ + j Windows: Alt + j). Toggle the switch on the top right to enable the integration. The REST API settings screen supports multiple API keys — each key appears in its own block with an editable name, copyable secret token, copyable Basic Auth header, and individual options to regenerate or revoke that key only.
You can create additional keys at any time to use for different integrations or environments.
For security purposes they can be rolled (a new key will be generated) or deleted.
Request Headers
The Authorization header format is basic auth, using the API Key as the username.
Authorization: Basic c2VjcmV0X2tleTo=
Rate-Limiting
The default rate limiting is set at 1000 requests / min using a token bucket. Write requests (POST, PUT, PATCH, DELETE) may count as more than one request against that budget. Headers returned on every request will show the total limit, the budget remaining, and the number of seconds until one unit of budget refills.
Response Headers
RateLimit-Limit: 1000, 1000;window=60RateLimit-Remaining: 990RateLimit-Reset: 1
Error
Status Codes
400 - Bad Request- The body of the request needs to be reviewed401 - Unauthorized- There is an issue with the authorization used (Secret Token/Basic Auth Header)429 Too Many Requests- There are too many requests being made within the allotted timeframe (e.g. over the 1000 requests/min)
Pagination
All paginated endpoints use cursor based pagination.
In addition to an array of results, the response will return a next property which can be used to access the subsequent page. The next property will be null when the end is reached and there are no more pages.
Unless specified otherwise, all List endpoints paginate sorted by updatedAt descending.
Query Params
Param | Type | Description |
limit |
| (optional) The number of items to return. The max/default is 100 |
from |
| (optional) The cursor returned from a previous request |
sortBy |
| (optional) How to order the elements returned. The default is |
If your data may update at any time, include sortBy=createdAt on every request in the crawl, including every subsequent request that uses the from cursor. createdAt never changes after a record is created, which keeps each record's position stable across pages even if other fields update mid-crawl. If sortBy is omitted on a later page, that page falls back to the default updatedAt sort, and since the from cursor was generated under a different sort order, the results for that page can be duplicates, gaps, or otherwise inconsistent with the rest of the crawl.
To verify pagination is stable, run the same crawl twice with sortBy=createdAt applied to every request and confirm both runs return the same total record count. If the counts differ between runs, check whether sortBy is actually present on every paginated request rather than just the first.
Response Body
Param | Type | Description |
results |
| Any array of the items for that endpoint. |
next |
| The cursor to use for the following page, if any. |
Example response
With more results:
GET /endpoint?limit=100
{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}
At the end:
GET /endpoint?limit=100&from=c29tZWJhc2U2NA==
{
"results": [...],
"next": null
}
HTML Fields
Fields that are editable in Vitally as rich text (Notes, Tasks) share the same set of supported tags and attributes. Any tags or attributes not in the allow list will be stripped out when creating or updating.
Tags
<a>, <img>, <p>, <div>, <br>, <ul>, <ol>, <nl>, <li>, <b>, <u>, <i>, <strong>, <em>, <code>
Attributes
Tag | Attributes |
|
|
|
|