REST API: Users

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

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
email	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
deactivatedAt	Datetime of when User was deactivated	No
segments	Array of segments (id,name)	In-app
accountIds	Array of Account IDs assigned by Vitally	Yes
organizationIds	Array of Organization IDs assigned by Vitally	Yes

List Users GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/users

EU Data Center:

https://rest.vitally-eu.io/resources/users

Paginated list of Users, by default ordered by updatedAt.

Params (see Pagination)

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

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

Paginated list of NPS Responses for a given Account, by default ordered by updatedAt.

Params (see Pagination)

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

US Data Center (default):

hhttps://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/users

EU Data Center:

https://rest.vitally-eu.io/resources/organizations/:organizationId/users

Paginated list of NPS Responses for a given Organization, by default ordered by updatedAt.

Params (see Pagination)

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	string	Accepts both the User ID assigned by Vitally and the externalId if provided when creating the User

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	number	The unique ID of this User in your system
email	string	The email of the User
emailSubdomain	string	The email subdomain of the User

Example Request

GET https://{subdomain}.rest.vitally.io/resources/users/search?externalId=user-id

GET https://{subdomain}.rest.vitally.io/resources/users/search?email=[e-mail]

GET https://{subdomain}.rest.vitally.io/resources/users/search?emailSubdomain=domain.com

Example Response

{
  "results": [...]
}

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	string	Required The unique ID of this User in your system
accountIds	array<string>	Required* An array of Account IDs assigned by Vitally. *Only one of accountsIds or organizationIds is required
organizationIds	array<string>	Required* An array of Organization IDs assigned by Vitally. *Only one of accountsIds or organizationIds is required
name	string	The name of the User
email	string	The email of the User
avatar	string	The URL of the User's avatar
unsubscribedFromConversations	boolean	Boolean set to true if the User has chosen to unsubscribe
traits	object	A JSON object containing the traits of this user.
joinDate	string	Datetime the User was first active in your product

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": "[e-mail]",
  "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	string	Accepts both the User ID assigned by Vitally and the externalId if provided when creating the User

Request Body

Property	Type	Description
accountIds	array<string>	An array of Account IDs assigned by Vitally
organizationIds	array<string>	An array of Organization IDs assigned by Vitally
name	string	The name of the User
email	string	The email of the User
avatar	string	The URL of the User's avatar
unsubscribedFromConversations	boolean	Boolean set to true if the User has chosen to unsubscribe
traits	object	A JSON object containing the traits of this user.
joinDate	string	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	string	Accepts both the User ID assigned by Vitally and the externalId if provided when creating the User

Query Params

Param	Type	Description
deleteOn	string	(optional) The timestamp when to delete the User

Example

DELETE https://{subdomain}.rest.vitally.io/resources/users/:id

DELETE https://{subdomain}.rest.vitally.io/resources/users/:id?deleteOn=2021-09-01