REST API
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
.
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 Operations 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 which is where you can obtain either the Secret Token or the Basic Auth Header for use in requests.
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 sliding window. Headers returned on every request will show the total limit, the requests remaining for the current window, and the number of seconds until the earliest request leaves the window.
Response Headers
RateLimit-Limit: 1000, 1000;window=60
RateLimit-Remaining: 999
RateLimit-Reset: 59
Error
Status Code
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
If you are frequently sending data to Vitally and your data may update at any time, setting sortBy
to "createdAt"
will ensure you return a full list every time.
Response Body
Example response
With more results:
At the end:
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
Last updated