REST API: Organizations

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 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
churnedAt	Datetime the organization churned	Via traits
mrr	Monthly recurring revenue for the organization	Via traits
nextRenewalDate	Datetime the organization is next set to renew their subscription	Via traits
trialEndDate	Datetime the organization trial is set to end	Via traits
usersCount	The number of users at the organization	No
csmId	Vitally ID for the team member that is the organization's CSM	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
accountExecutiveId	Vitally ID for the team member that is the organization's account executive	No
segments	Array of segments (id,name)	In-app
accountsCount	Returns the number of Accounts tied to the Organization	No
healthScore	Returns the account's current health score (0-10)	No

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	string	Accepts the Organization ID assigned by Vitally or the externalId if provided when creating the Organization

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	string	Required The unique ID of this Organization in your system
name	string	Required The name of the Organization
traits	object	A JSON object containing the traits of this Organization.

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	string	Accepts the Organization ID assigned by Vitally or the externalId if provided when creating the Organization

Request Body

Property	Type	Description
name	string	The name of the Organization
traits	object	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 null in the traits object.

Example

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

Delete An Organization DELETE

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	string	Accepts both the Organization ID assigned by Vitally and the externalId if provided when creating the Organization