Skip to main content
Vitally's HTTPS Analytics API - User

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

Laura Bedoya avatar
Written by Laura Bedoya
Updated over 3 months ago

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

Did this answer your question?