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

Name	Type	Description
Content-Type*	string	Set to `application/json`
Authorization*	string	Set to `Basic [YOUR_API_TOKEN]`

Request Body

Name	Type	Description
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`

200 When your user is created/updated, you'll receive

{"message":"Success."}

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

Vitally's HTTPS Analytics API - Organization

Vitally's HTTPS Analytics API - Account

Vitally's HTTPS Analytics API - Track

Vitally's HTTPS Analytics API - Batch

Vitally's HTTPS Analytics API - Unlink

Vitally's HTTPS Analytics API - User

Create/update a user

Headers

Request Body

Example

Special traits