📖
📖
📖
📖
Vitally Help Center
Vitally.ioBlogLogin
Search
⌃K
Links

Vitally's 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.
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
  • 429 Too Many Requests

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
number
(optional) The number of items to return. The max/default is 100
from
string
(optional) The cursor returned from a previous request
sortBy
"createdAt" | "updatedAt"
(optional) How to order the elements returned. The default is "updatedAt".
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
Param
Type
Description
results
array
Any array of the items for that endpoint.
next
string | null
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
<a>
href, name, target
<img>
src, alt, width, height
Previous
Analytics best practices
Next
Organizations
Last modified 8mo ago