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	Can be set to `null` to remove the Account Owner, otherwise, edit in-app
mrr	Monthly recurring revenue for the account	Via traits
nextRenewalDate	Datetime the account is next set to renew their subscription	Via traits
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
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

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 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`

🚨 Deleting an Account via the REST API permanently destroys the record in Vitally and all data that exclusively belongs to that Account (meeting recordings, conversations, notes, tasks, traits, etc. will be deleted if they are only associated with that Account)

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

REST API: Users

REST API: Conversations

REST API: Notes

REST API: Tasks

REST API: Custom Objects

REST API: Accounts

The Account object

List Accounts GET

List Accounts For An Organization GET

Get An Account GET

Get An Account's Health Score Breakdown GET

Create An Account POST

Update An Account PUT

Delete An Account DELETE

List Accounts `GET`

List Accounts For An Organization `GET`

Get An Account `GET`

Create An Account `POST`

Update An Account `PUT`

Delete An Account `DELETE`