The Account API allows you to define an Account in Vitally by POST-ing to:

This endpoint will create or update an account in Vitally based on the accountId parameter. If you provide a timestamp, we will store the history of the account's traits over time, allowing you to build rich metrics that track the account's history.

Request Headers

The request should contain the following headers:

  • Authorization
  • Content-type: application/json
Request Body

The body of the request should be a JSON object with the following fields:

  • accountId: The unique ID of this account in your system
    • Required: yes
    • Type: string or number
  • traits: A JSON object containing the traits of this account. All account messages should specify, at minimum, a "name" trait indicating the name of the account.
    • Required: yes
    • Type: object
  • timestamp: The time that the message was sent. If timestamp is not included, it will default to the time the API server receives your message.
    • Required: if messageId is not included
    • Type: ISO 8601 UTC date string, i.e. '2018-01-01T00:00:00Z'
  • messageId: A unique ID for this message, used to de-duplicate messages. We recommend sending `messageId, but if it is not included and timestamp is included, it will be set to a hash of the message.
    • Required: if timestamp is not included
    • Type: string or number

An example curl request describing Vitally would look like:

curl -X POST \
  -H "Authorization: Basic [your token]" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "123456",
  "traits": {
    "name": "Vitally",
    "avatar": "",
    "status": "trialing",
    "trialEndDate": "2018-06-01T00:00:00.000Z"
  "messageId": "7ac1c682-a54b-4d0d-9f56-d6d3618f4915",
  "timestamp": "2018-05-15T12:31:12.123Z"