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 | In-app |
segments | Array of segments ( | 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/accountsEU Data Center:
https://rest.vitally-eu.io/resources/accounts
Paginated list of Accounts, by default ordered by updatedAt.
Params
Property | Type | Description |
status |
| Accepts one of |
See Pagination
Additionally, this API accepts an optional status query parameter with the following values:
active- default. Get tracked, non-churned accountschurned- get tracked, churned accountsactiveOrChurned- 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/accountsEU Data Center:
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 |
| Accepts both the Account ID assigned by Vitally and the |
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 |
| Accepts both the Account ID assigned by Vitally and the |
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 |
| Required The unique ID of this Account in your system |
name |
| Required The name of the Account |
organizationId | string | The Vitally assigned ID of the Organization to relate this account to |
traits |
| 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/:idEU Data Center:
https://rest.vitally-eu.io/resources/accounts/:id
Request Params
Property | Type | Description |
id |
| Accepts both the Account ID assigned by Vitally and the |
Request Body
name |
| The name of the Account |
traits |
| 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 |
organizationId |
| The Vitally assigned ID of the Organization to relate this Account to. To remove an Organization relationship from an Account, set this property to |
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 |
| Accepts both the Account ID assigned by Vitally and the |