The User object
Attribute | Description | Editable? |
id | Vitally's unique ID for the User | No |
createdAt | Datetime the User was created | No |
updatedAt | Datetime the User was last updated | No |
externalId | Your unique ID for the User | Only on create |
name | Name of the User | Yes |
The email of the User | Yes | |
avatar | A URL for the User's avatar | Yes |
traits | Set of key-value pairs to attach to the User | Yes |
firstKnown | Datetime the User was first active in your product | No |
lastSeenTimestamp | Datetime the User was last active in your product | No |
lastInboundMessageTimestamp | Datetime of the last inbound message from this User | No |
lastOutboundMessageTimestamp | Datetime of the last outbound message to this User | No |
npsLastScore | Score (0-10) of the last NPS response submitted by the User | No |
npsLastFeedback | The text feedback of the last NPS response submitted by the User | No |
npsLastRespondedAt | Datetime of last submitted NPS Responses | No |
unsubscribedFromConversations | Boolean set to true if the User has chosen to unsubscribe | Yes |
unsubscribedFromConversationsAt | Datetime the User has chosen to unsubscribe | No |
deactivatedAt | Datetime of when User was deactivated | No |
isPermanentlyBounced | Prevents sending communications to the user. Automatically set to `true` when a permanent email bounce is detected. | Yes |
segments | Array of segments ( | In-app |
accounts | Array of the Account object(s) the User is associated with | No |
organizations | Array of the Organization object(s) the User is associated with | No |
Unlinking a User from an Account or Organization is not supported via the REST API. Only new Account and Organization associations can be established here. To unlink a User from an Account programmatically, use the Analytics API unlink endpoint (POST /analytics/v1/unlink). You can also remove associations manually in-app — see Removing Hierarchy Associations.
Replace {subdomain} in the endpoints below with your Vitally subdomain.
You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io
List Users GET
Paginated list of Users, by default ordered by updatedAt. This endpoint returns only Users with a tracked Account or Organization association. A User with no tracked Account or Organization, known as an orphan User, is not returned, and neither is a User whose only Accounts or Organizations are ignored. This applies from the moment the User has no tracked association, not only once the User has been ignored, so this endpoint cannot be used to build a list of orphan Users. The GET /users/search and GET /users/:id endpoints do return these Users. To get a list of the orphan Users in your instance, contact Vitally support and we can run that export for you.
Params (see Pagination)
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/users
EU Data Center:
https://rest.vitally-eu.io/resources/users
Example Request
GET https://{subdomain}.rest.vitally.io/resources/users?limit=10&from=cursor
Example Response
{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}
List Users For An Account GET
Paginated list of Users for a given Account, by default ordered by updatedAt. Accepts the accountId assigned by Vitally. Find this ID by using the GET An Account or GET A User endpoint and reference the Account's id field.
Params (see Pagination)
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/users
EU Data Center:
https://rest.vitally-eu.io/resources/accounts/:accountId/users
Example Request
GET https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/users?limit=10&from=cursor
Example Response
{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}
List Users For An Organization GET
Paginated list of Users for a given Organization, by default ordered by updatedAt. Accepts the organizationId assigned by Vitally. Find this ID by using the GET An Organization or GET A User endpoint and reference the Organization's id field.
Params (see Pagination)
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/usersEU Data Center:
https://rest.vitally-eu.io/resources/organizations/:organizationId/users
Example Request
GET https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/users?limit=10&from=cursor
Example Response
{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}
Get A User GET
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/users/:id
EU Data Center:
https://rest.vitally-eu.io/resources/users/:id
Request Params
Property | Type | Description |
id |
| Accepts both the User ID assigned by Vitally and the |
Example
GET https://{subdomain}.rest.vitally.io/resources/users/:id GET https://{subdomain}.rest.vitally.io/resources/users/:externalId
Search Users GET
Find a User by email or externalId
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/users/search
EU Data Center:
https://rest.vitally-eu.io/resources/users/search
Query Params (exactly one is required)
Param | Type | Description |
externalId |
| The unique ID of this User in your system |
| The email of the User | |
emailSubdomain |
| The email subdomain of the User |
Example Request
GET https://{subdomain}.rest.vitally.io/resources/users/search?externalId=user-idGET https://{subdomain}.rest.vitally.io/resources/users/search?email=user@domain.comGET https://{subdomain}.rest.vitally.io/resources/users/search?emailSubdomain=domain.com
Example Response
{
"results": [...]
}
NOTE: If the email address contains a special character (e.g. +), then this will need to be encoded within the URL endpoint.
Create A User POST
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/users
EU Data Center:
https://rest.vitally-eu.io/resources/users
Request Body
Property | Type | Description |
externalId |
| Required The unique ID of this User in your system |
accountIds |
| Required* An array of Account IDs assigned by Vitally. *Only one of accountsIds or organizationIds is required |
organizationIds |
| Required* An array of Organization IDs assigned by Vitally. *Only one of accountsIds or organizationIds is required |
name |
| The name of the User |
| The email of the User | |
avatar |
| The URL of the User's avatar |
unsubscribedFromConversations |
| Boolean set to true if the User has chosen to unsubscribe |
isPermanentlyBounced |
| Automatically set to `true` when a permanent email bounce is detected. |
traits |
| A JSON object containing the traits of this user. |
joinDate |
| Datetime the User was first active in your product |
Creating new traits
Including a key in the traits object that does not yet exist in Vitally will automatically create that trait. The trait type cannot be set explicitly via the API — it is inferred from the value you send:
Value format | Trait type created |
Any text string, e.g. | String — also the fallback for long text, non-ISO dates like |
Raw integer or decimal with no quotes, e.g. | Number |
ISO 8601 UTC with time set to all zeroes, e.g. | Date |
ISO 8601 UTC with a non-zero time, e.g. | Datetime |
JSON array of strings, e.g. | Multi-select — must use array format; a plain string will not create a multi-select |
Unquoted boolean, e.g. | Boolean — quoting the value (e.g. |
| No type assigned — Vitally cannot infer type from a null value |
Note that some trait types cannot be created via the API: Text Area traits always default to String regardless of length, and File attachment traits are not supported. Once a trait is created, its additional settings (predefined options, permissions, display settings) can only be configured in the Vitally UI.
Example
POST https://{subdomain}.rest.vitally.io/resources/users
{
"externalId": "user-101", // (required)
"accountIds": ["xxxx-xxxxx-xxxxxxxx-xxxxxxxx"],
"organizationIds": ["xxxx-xxxxx-xxxxxxxx-xxxxxxxx"],
"name": "Jane McUser",
"email": "jane@domain.com",
"avatar": "https://domain.com/avatar/user-101",
"unsubscribedFromConversations": true,
"traits": {
"favoriteColor": "green",
...
}
}
Update A User PUT
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/users/:id
EU Data Center:
https://rest.vitally-eu.io/resources/users/:id
Request Params
Property | Type | Description |
id |
| Accepts both the User ID assigned by Vitally and the |
Request Body
Property | Type | Description |
accountIds |
| An array of Account IDs assigned by Vitally |
organizationIds |
| An array of Organization IDs assigned by Vitally |
name |
| The name of the User |
| The email of the User | |
avatar |
| The URL of the User's avatar |
unsubscribedFromConversations |
| Boolean set to true if the User has chosen to unsubscribe |
isPermanentlyBounced |
| Automatically set to `true` when a permanent email bounce is detected. |
traits |
| A JSON object containing the traits of this user. |
joinDate |
| Datetime the User was first active in your product |
Example
PUT https://{subdomain}.rest.vitally.io/resources/users/:id
{
"name": "Corrected Name",
"unsubscribedFromConversations": true,
"traits": {
"existingTrait": "new value",
"newTrait": 100,
...
}
}
Delete A User DELETE
Delete a User, or schedule a User for deletion
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/users/:id
EU Data Center:
https://rest.vitally-eu.io/resources/users/:id
Request Params
Property | Type | Description |
id |
| Accepts both the User ID assigned by Vitally and the |
Query Params
Param | Type | Description |
deleteOn |
| (optional) The timestamp when to delete the User |
Example
DELETE https://{subdomain}.rest.vitally.io/resources/users/:idDELETE https://{subdomain}.rest.vitally.io/resources/users/:id?deleteOn=2021-09-01