REST API: Accounts

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 Account object

Attributes	Description	Editable?
id	Vitally's unique ID for the account	No
createdAt	Datetime the account was created	No
updatedAt	Datetime the account was last updated	No
externalId	Your unique ID for the account	Only on create
name	Name of the account	Yes
traits	Set of key-value pairs to attach to the account	Yes
organizationId	Vitally ID for the organization this account belongs to (if applicable)	Yes
accountOwnerId	Vitally ID for the User that is the account owner	No
churnedAt	Datetime the account churned	Via traits
firstSeenTimestamp	Datetime the account was first active in your product	No
lastSeenTimestamp	Datetime the account was last active in your product	No
lastInboundMessageTimestamp	Datetime a user at the account last sent your team a message	No
lastOutboundMessageTimestamp	Datetime someone on your team last sent the account a message	No
mrr	Monthly recurring revenue for the account	Via traits
nextRenewalDate	Datetime the account is next set to renew their subscription	Via traits
trialEndDate	Datetime the account's trial is set to end	Via traits
usersCount	The number of users at the account	No
npsDetractorCount	The number of users at the account with a last NPS score <= 6	No
npsPassiveCount	The number of users at the account with a last NPS score of 7 or 8	No
npsPromoterCount	The number of users at the account with a last NPS score of 9 or 10	No
npsScore	The NPS score for the account across all its users (-100 to 100)	No
healthScore	The account's current health score (0-10)	No
csmId	Vitally ID for the team member that is the account's CSM	No
accountExecutiveId	Vitally ID for the team member that is the account's account executive	No
keyRoles	Array of objects, with each object representing a teammate assigned to a key role for the account. Each object has a vitallyUser field that references the Admin assigned to the key role and a keyRole field that details with key role the Admin is assigned to.	In-app
segments	Array of segments (id,name)	In-app

List Accounts GET

US Data Center (default):

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

EU Data Center:

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

Paginated list of Accounts, by default ordered by updatedAt.

Params

Property	Type	Description
status	string	Accepts one of active, churned, or activeOrChurned. Defaults to active

See Pagination

Additionally, this API accepts an optional status query parameter with the following values:

• active - default. Get tracked, non-churned accounts

• churned - get tracked, churned accounts

• activeOrChurned - get all tracked accounts

Example Request

GET https://{subdomain}.rest.vitally.io/resources/accounts?limit=10&from=cursor&status=active

Example Response

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

List Accounts For An Organization GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/accounts

EU Data Center:

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

Paginated list of Accounts for the given Organization, by default ordered by updatedAt.

Params (see Pagination)

Example Request

GET https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/accounts?limit=10&from=cursor

Example Response

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

Get An Account GET

US Data Center (default):

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

EU Data Center:

https://rest.vitally-eu.io/resources/accounts/:id

Request Params

Property	Type	Description
id	string	Accepts both the Account ID assigned by Vitally and the externalId if provided when creating the Account

Example

GET https://{subdomain}.rest.vitally.io/resources/accounts/id
GET https://{subdomain}.rest.vitally.io/resources/accounts/externalId

Get An Account's Health Score Breakdown GET

US Data Center (default)

https://{subdomain}.rest.vitally.io/resources/accounts/id/healthScores

EU Data Center:

https://rest.vitally-eu.io/resources/accounts/id/healthScores

Request Params

Property	Type	Description
id	string	Accepts both the Account ID assigned by Vitally and the externalId if provided when creating the Account

Example

GET https://{subdomain}.rest.vitally.io/resources/accounts/id/healthScores

Create An Account POST

US Data Center (default):

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

EU Data Center:

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

Request Body

Property	Type	Description
externalId	string	Required The unique ID of this Account in your system
name	string	Required The name of the Account
organizationId	string	The Vitally assigned ID of the Organization to relate this account to
traits	object	A JSON object containing the traits of this Account.

Example

POST https://{subdomain}.rest.vitally.io/resources/accounts
{
  "externalId": "account-101",
  "name": "Big Corp",
  "traits": {
    "paymentMethod": "subscription",
    ...
  }
}

Update An Account PUT

US Data Center (default):

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

EU Data Center:

https://rest.vitally-eu.io/resources/accounts/:id

Request Params

Property	Type	Description
id	string	Accepts both the Account ID assigned by Vitally and the externalId if provided when creating the Account

Request Body

name	string	The name of the Account
traits	object	A JSON object containing the traits of this Account. Note that traits specified here are merged with the Account's existing traits. Any trait not specified is not removed. To remove a trait value from an account, set the trait to null in the traits object.
organizationId	string	The Vitally assigned ID of the Organization to relate this Account to. To remove an Organization relationship from an Account, set this property to null

Example

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

Delete An Account DELETE

US Data Center (default):

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

EU Data Center:

https://rest.vitally-eu.io/resources/accounts/:id

Request Params

Property	Type	Description
id	string	Accepts both the Account ID assigned by Vitally and the externalId if provided when creating the Account