Skip to main content

REST API: Accounts

Written by Laura Bedoya
Updated over a week ago

The Account object

Attributes

Description

Editable?

id

Vitally's unique ID for the account

id is not editable via REST API

createdAt

Datetime the account was created

createAt is not editable via REST API

updatedAt

Datetime the account was last updated

updateAt is not editable via REST API

externalId

Your unique ID for the account

externalId is not editable via REST API

name

Name of the account

name is not editable via REST API

traits

Set of key-value pairs to attach to the account

traits are editable via REST API

organizationId

Vitally ID for the organization this account belongs to (if applicable)

organizationId is editable via REST API

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

mrr is editable via traits

nextRenewalDate

Datetime the account is next set to renew their subscription

nextRenewalDate is editable via traits

churnedAt

Datetime the account churned

churnedAt is editable via traits

firstSeenTimestamp

Datetime the account was first active in your product

firstSeenTimestamp is not editable via REST API

lastSeenTimestamp

Datetime the account was last active in your product

lastSeenTimestamp is not editable via REST API

lastInboundMessageTimestamp

Datetime a user at the account last sent your team a message

lastInboundMessageTimestamp is not editable via REST API

lastOutboundMessageTimestamp

Datetime someone on your team last sent the account a message

lastOutboundMessageTimestamp is not editable via REST API

trialEndDate

Datetime the account's trial is set to end

Via traits

usersCount

The number of users at the account

usersCount is not editable via REST API

npsDetractorCount

The number of users at the account with a last NPS score <= 6

npsDetractorCount is not editable via REST API

npsPassiveCount

The number of users at the account with a last NPS score of 7 or 8

npsPassiveCount is not editable via REST API

npsPromoterCount

The number of users at the account with a last NPS score of 9 or 10

npsPromoterCount is not editable via REST API

npsScore

The NPS score for the account across all its users (-100 to 100)

npsScore is not editable via REST API

healthScore

The account's current health score (0-10)

healthscore is not editable via REST API

csmId

Vitally ID for the team member that is the account's CSM

csmId is not editable via REST API

accountExecutiveId

Vitally ID for the team member that is the account's account executive

accountExecutiveId is not editable via REST API

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.

keyRoles is editable In-app

segments

Array of segments (id,name)

segments is editable 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

externalId is Required. It's the unique ID of this Account in your system

name

string

name is Required. It's the name of the Account

organizationId

string

organizationID is the Vitally assigned ID of the Organization to relate this account to

traits

object

traits is 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

id 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 Organization External ID or 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

Related Articles
REST API: Organizations
REST API: Users
REST API: Notes
REST API: Projects
REST API: Project Templates
Did this answer your question?