Analytics API - User

Create/update your Users in Vitally using the /user API endpoint

Replace {subdomain} in the endpoint below with your Vitally subdomain.

You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io

Create/update a user

POST https://{subdomain}.api.vitally.io/analytics/v1/user

This endpoint will create or update a user in Vitally based on the userId parameter.

Headers

NameTypeDescription

Content-Type*

string

Set to application/json

Authorization*

string

Set to Basic [YOUR_API_TOKEN]

Request Body

NameTypeDescription

userId*

string

The unique ID of this user in your system

accountId

string

Required if organizationId is not included.

This should match the accountId you send in your account request

traits*

object

Required, but can be passed as an empty object "traits": {}

A JSON object containing the traits of this user. Some traits, called "reserved" traits, have special meaning to Vitally. A list of "reserved" traits can be found below.

timestamp

string

Required if messageId is not included. An ISO 8601 UTC date string - i.e. '2018-01-01T00:00:00Z' - for the time the message was sent. If timestamp is not included, it will default to the time the API server receives your message.

messageId

string

Required if timestamp is not included. 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.

organizationId

string

Required if accountId is not included.

If you have organizations enabled, you may associate the user with an organization by setting organizationId

{"message":"Success."}

Expand the POST box above for full specs

Example

An example curl request describing a Vitally user would look like:

curl -X POST https://{subdomain}.api.vitally.io/analytics/v1/user \
  -H "Authorization: Basic [your token]" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "32",
  "accountId": "123456",
  "traits": {
    "name": "Lionel Messi",
    "position": "Forward",
    "email": "messi@barcelona.sp"
  },
  "messageId": "7ac1c682-a54b-4d0d-9f56-d6d3618f4915",
  "timestamp": "2018-05-15T12:31:12.123Z"
}'

Special traits

Vitally has special logic to handle the following User traits:

  • name: defines the user's name in Vitally

  • avatar: defines the user's avatar in Vitally

  • email: defines the user's email in Vitally

  • createdAt: defines the user's 'join date' in Vitally

Last updated