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

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`

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=user@domain.com

GET 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	`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": "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	`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

REST API: Organizations

REST API: Accounts

REST API: Notes

REST API: Tasks

REST API: Custom Objects

The User object

List Users GET

List Users For An Account GET

List Users For An Organization GET

Get A User GET

Search Users GET

Create A User POST

Update A User PUT

Delete A User DELETE

List Users `GET`

List Users For An Account `GET`

List Users For An Organization `GET`

Get A User `GET`

Search Users `GET`

Create A User `POST`

Update A User `PUT`

Delete A User `DELETE`