Links

Organizations

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

https://rest.vitally.io/resources/organizations
Paginated list of Organizations, by default ordered by updatedAt.
Params (see Pagination)
Example Request
GET https://rest.vitally.io/resources/organizations?limit=10&from=cursor
Example Response
{
"results": [...],
"next": "c29tZWJhc2U2NA=="
}

Get An Organization GET

https://rest.vitally.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://rest.vitally.io/resources/organizations/:id
GET https://rest.vitally.io/resources/organizations/:externalId

Create An Organization POST

https://rest.vitally.io/resources/organizations
Request Body
Property
Type
Description
externalId
string
Required The unique ID of this Organization in your system
name
string
The name of the Organization
traits
object
A JSON object containing the traits of this Organization.
Example
POST https://rest.vitally.io/resources/organizations
{
"externalId": "org-101",
"name": "Big Corp",
"traits": {
"paymentMethod": "subscription",
...
}
}

Update An Organization PUT

https://rest.vitally.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://rest.vitally.io/resources/organizations/:id
{
"name": "New Name",
"traits": {
"existingTrait": "new value",
"newTrait": 100,
...
}
}

Delete An Organization DELETE

https://rest.vitally.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