The Organization object
Attributes | Description | Editable? |
id | Vitally's unique ID for the organization | No |
createdAt | Datetime the organization was created | No |
updatedAt | Datetime the organization was last updated | No |
externalId | Your unique ID for the organization | Only on create |
name | Name of the organization | Yes |
traits | Set of key-value pairs to attach to the organization | Yes |
organizationOwnerId | Vitally ID for the User that is the organization owner | No |
mrr | Monthly recurring revenue for the organization | Via traits |
firstPaidDate | The date and time the organization's revenue was first recorded in Vitally | In-app |
nextRenewalDate | Datetime the organization is next set to renew their subscription | Via traits |
churnedAt | Datetime the organization churned | Via traits |
trialEndDate | Datetime the organization trial is set to end | Via traits |
usersCount | The number of users at the organization | No |
accountsCount | Returns the number of Accounts tied to the Organization | No |
healthScore | Returns the account's current health score (0-10) | No |
csmId | Vitally ID for the team member that is the organization's CSM | No |
accountExecutiveId | Vitally ID for the team member that is the organization'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 |
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 |
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 Organizations GET
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations
EU Data Center:
https://rest.vitally-eu.io/resources/organizations
Paginated list of Organizations, by default ordered by updatedAt.
Params (see Pagination)
Example Request
GET https://{subdomain}.rest.vitally.io/resources/organizations?limit=10&from=cursor
Example Response
{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}
Get An Organization GET
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations/:id
EU Data Center:
https://rest.vitally-eu.io/resources/organizations/:id
Request Params
Property | Type | Description |
id |
| Accepts the Organization ID assigned by Vitally or the |
Example
GET https://{subdomain}.rest.vitally.io/resources/organizations/:id
GET https://{subdomain}.rest.vitally.io/resources/organizations/:externalId
Create An Organization POST
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations
EU Data Center:
https://rest.vitally-eu.io/resources/organizations
Request Body
Property | Type | Description |
externalId |
| Required The unique ID of this Organization in your system |
name |
| Required The name of the Organization |
traits |
| A JSON object containing the traits of this Organization. |
Creating new traits
Including a key in the traits object that does not yet exist in Vitally will automatically create that trait. The trait type cannot be set explicitly via the API — it is inferred from the value you send:
Value format | Trait type created |
Any text string, e.g. | String — also the fallback for long text, non-ISO dates like |
Raw integer or decimal with no quotes, e.g. | Number |
ISO 8601 UTC with time set to all zeroes, e.g. | Date |
ISO 8601 UTC with a non-zero time, e.g. | Datetime |
JSON array of strings, e.g. | Multi-select — must use array format; a plain string will not create a multi-select |
Unquoted boolean, e.g. | Boolean — quoting the value (e.g. |
| No type assigned — Vitally cannot infer type from a null value |
Note that some trait types cannot be created via the API: Text Area traits always default to String regardless of length, and File attachment traits are not supported. Once a trait is created, its additional settings (predefined options, permissions, display settings) can only be configured in the Vitally UI.
Example
POST https://{subdomain}.rest.vitally.io/resources/organizations
{
"externalId": "org-101",
"name": "Big Corp",
"traits": {
"paymentMethod": "subscription",
...
}
}
Update An Organization PUT
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations/:id
EU Data Center:
https://rest.vitally-eu.io/resources/organizations/:id
Request Params
Property | Type | Description |
id |
| Accepts the Organization ID assigned by Vitally or the |
Request Body
Property | Type | Description |
name |
| The name of the Organization |
traits |
| A JSON object containing the traits of this Organization. Note that traits specified here are merged with the organization's existing traits. Any trait not specified is not removed. To remove a trait from an organization, set the trait to |
Example
PUT https://{subdomain}.rest.vitally.io/resources/organizations/:id
{
"name": "New Name",
"traits": {
"existingTrait": "new value",
"newTrait": 100,
...
}
}
Delete An Organization DELETE
🚨 Deleting an Organization via the REST API permanently destroys the record in Vitally and all data that exclusively belongs to that Organization (meeting recordings, conversations, notes, tasks, traits, etc. will be deleted if they are only associated with that Organization)
US Data Center (default):
https://{subdomain}.rest.vitally.io/resources/organizations/:id
EU Data Center:
https://rest.vitally-eu.io/resources/organizations/:id
Request Params
Property | Type | Description |
id |
| Accepts both the Organization ID assigned by Vitally and the |