⚡️ Other integrations

Users

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 account

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

No

deactivatedAt

Datetime of when User was deactivated

No

segments

Array of segments (id,name)

In-app

List Users GET

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

Paginated list of Users, by default ordered by updatedAt.

Params (see Pagination)

Example Request

GET https://rest.vitally.io/resources/users?limit=10&from=cursor

Example Response

{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}

List Users For An Account GET

https://rest.vitally.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://rest.vitally.io/resources/accounts/:accountId/users?limit=10&from=cursor

Example Response

{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}

Get A User GET

https://rest.vitally.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://rest.vitally.io/resources/users/:id
GET https://rest.vitally.io/resources/users/:externalId

Search Users GET

Find a User by email or externalId.

https://rest.vitally.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

Example Request

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

or

GET https://rest.vitally.io/resources/users/[email protected]

Example Response

{
"results": [...]
}

Create A User POST

https://rest.vitally.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

name

string

The name of the User

email

string

The email of the User

avatar

string

The URL of the User's avatar

traits

object

A JSON object containing the traits of this user.

Example

POST https://rest.vitally.io/resources/users
{
"externalId": "user-101", // (required)
"accountIds": ["xxxx-xxxxx-xxxxxxxx-xxxxxxxx"],
"name": "Jane McUser",
"email": "[email protected]",
"avatar": "https://domain.com/avatar/user-101",
"traits": {
"favoriteColor": "green",
...
}
}

Update A User PUT

https://rest.vitally.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

name

string

The name of the User

email

string

The email of the User

avatar

string

The URL of the User's avatar

traits

object

A JSON object containing the traits of this user.

Example

PUT https://rest.vitally.io/resources/users/:id
{
"name": "Corrected Name",
"traits": {
"existingTrait": "new value",
"newTrait": 100,
...
}
}

Delete A User DELETE

https://rest.vitally.io/resources/users/:id

Delete a User, or schedule a User for delete.

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://rest.vitally.io/resources/users/:id
DELETE https://rest.vitally.io/resources/users/:id?deleteOn=2021-09-01