The Custom Object object

Property	Description
id	Vitally's unique ID for the Custom Object
createdAt	Datetime the Custom Object was created
updatedAt	Datetime the Custom Object was last updated
name	Name of the Custom Object
label	The label of the Custom Object
syncActive	Synchronization of custom objects is active
writeMode	Permissions that allow or disallow team members to create these custom objects in Vitally. `writable`: Admins & Leaders only `writableByAll`: Admins, Leaders, and Team Members `readonly`: No one
customFields	An array of key-value JSON object of Custom Fields. See below for more details.

Custom Object Custom Fields

In Vitally, if you are an admin, you can add additional custom fields to your Custom Objects via the Traits management section. When you create a custom field, we will provide you with a key for that custom field:

Using this key, you can set values for the Custom Object Instance traits

The Custom Object Instance object

Property	Description	Editable
id	Vitally's unique ID for the Custom Object Instance	No
createdAt	Datetime the Custom Object Instance was created	No
updatedAt	Datetime the Custom Object Instance was last updated	No
name	Name of the Custom Object Instance	Yes
externalId	Your unique ID for the Custom Object Instance	Yes
customObjectId	The ID of the Vitally Custom Object the Custom Object Instance belongs to	Only on create
createdByVitallyUserId	The ID of the internal Vitally User who created the Custom Object Instance	Only on create
ownedByVitallyUserId	The ID of the internal Vitally User who created the Custom Object Instance	Only on create
customerId	The ID of the Vitally Customer the Custom Object Instance is for	Yes
customer	A key-value JSON object of the Vitally Customer	No
customers	An array of key-value JSON objects of the Vitally Customer's associated to the object instance	No
organizationId	The ID of the Vitally Organization the Custom Object Instance is for	Yes
organization	A key-value JSON object of the Vitally Organization	No
organizations	An array of key-value JSON objects of the Vitally Organizations associated to the object instance	No
traits	A key-value JSON object of Custom Object Instance traits. See below for more details.	Yes
archivedAt	Datetime the Custom Object Instance was deleted	Set when tasks are deleted in-app or via DELETE endpoint
descriptionBody	An array of key-value JSON objects containing information about each line in the custom object instance's description	Yes (send HTML as `description` in the request body; Vitally stores and returns the converted rich-text value as `descriptionBody`)
timestamp	Datetime the Custom Object Instance was created (defaults to current time, can be set to a different time on creation)	Only on create

Custom Object Instance traits

You can set values for the Custom Object Instance traits using the Custom Object custom field key, when POSTing or PUTing to the API:

Example Request

POST https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances
{
    "name": "My custom object instance",
    "organizationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "traits": {
        "vitally.custom.organization": "my custom organization"
    }
}

Example Response

{
    "name": "My custom object instance",
    "organizationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "organization": { ... },
    ...
    "traits": {
        "vitally.custom.organization": "my custom organization"
    }
}

Note that when updating traits, if a trait is not specified, it will not be deleted from the Custom Object Instance (i.e. the value for the trait will remain unchanged). To actually delete a trait, simply specify the trait with a null value.

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

Custom Objects

List Custom Objects `GET`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects

Paginated list of Custom Objects, by default ordered by updatedAt.

Params (see Pagination)

Example Request

GET https://{subdomain}.rest.vitally.io/resources/customObjects?limit=10&from=cursor

Example Response

{
  "results": [...],
  "next": "eyJzb3J0VmFsd...=="
}

Get A Custom Object `GET`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:id

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:id

Request Params

Property	Type	Description
id	`string`	The Custom Object ID assigned by Vitally

Example Request

GET https://{subdomain}.rest.vitally.io/resources/customObjects/custom-object-id

Create A Custom Object `POST`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects

Request Body

Create a new Custom Object in Vitally, like a Pulse Check or Risk object. Include the name, label, and writeMode at minimum, and any custom fields you want to associate with this Custom Object.

Property	Type	Description
name	`string`	Required The name of the Custom Object.
label	`string`	Required The label of the Custom Object.
writeMode	`string`	Required Permissions that allow or disallow team members to create these custom objects in Vitally. `writable`: Admins & Leaders only `writableByAll`: Admins, Leaders, and Team Members `readonly`: No one
customFields	`array`	(Optional) An array of key-value JSON object of Custom Fields.
customFields.label	`string`	The label of the Custom Field
customFields.type	`string`	The type of the Custom Field
customFields.model	`string`	Model to which the Custom Field belongs

Example Request

POST https://{subdomain}.rest.vitally.io/resources/customObjects
{
  "name": "custom-object-1",
  "label": "custom-object-label-1",
  "writeMode": "readonly",
  "customFields": [
    {
      "label": "custom-field-label-1",
      "type": "string",
      "model": "CustomObject"
    },
    {
      "label": "custom-field-label-2",
      "type": "string",
      "model": "CustomObject"
    }
  ]
}

Example Response

{
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "createdAt": "2024-05-22T15:28:11.123Z",
    "updatedAt": "2024-05-22T15:28:11.123Z",
    "name": "custom-object-1",
    "label": "custom-object-label-1",
    "syncActive": true,
    "writeMode": "readonly",
    "customFields": [
        {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "label": "custom-field-label-1",
            "path": "vitally.custom.customFieldLabel1",
            "type": "string",
            "createdAt": "2024-05-22T15:28:11.123Z"
        },
        {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "label": "custom-field-label-2",
            "path": "vitally.custom.customFieldLabel2",
            "type": "string",
            "createdAt": "2024-05-22T15:28:11.123Z"
        }
    ]
}

Update A Custom Object `PUT`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:id

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:id

Query Params

Property	Type	Description
id	`string`	(Required) The Custom Object ID assigned by Vitally.

Request Body

The Custom Object Instance can be associated with a customer, an organization, or to both, but at least one of them should be sent

Property	Type	Description
name	`string`	The name of the Custom Object.
label	`string`	The label of the Custom Object.
writeMode	`string`	Permissions that allow or disallow team members to create these custom objects.
customFields	`array`	(Optional) An array of key-value JSON object of Custom Fields.
customFields.label	`string`	The label of the Custom Field.
customFields.type	`string`	The type of the Custom Field.
customFields.model	`string`	Model to which the Custom Field belongs

Example Request

PUT https://{subdomain}.rest.vitally.io/resources/customObjects/:id
{
  "name": "custom-object-1-updated",
  "label": "custom-object-label-1",
  "writeMode": "readonly",
  "customFields": [
    {
      "label": "custom-field-label-3",
      "type": "string",
      "model": "CustomObject"
    }
  ]
}

Example Response

{
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "createdAt": "2024-05-22T15:28:11.123Z",
    "updatedAt": "2024-05-22T15:33:15.131Z",
    "name": "custom-object-1-updated",
    "label": "custom-object-label-1",
    "syncActive": true,
    "writeMode": "readonly",
    "customFields": [
        {
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "label": "custom-field-label-3",
            "path": "vitally.custom.customFieldLabel3",
            "type": "string",
            "createdAt": "2024-05-22T15:33:15.131Z"
        }
    ]
}

Custom Object Instances

List Custom Object Instances `GET`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances

Paginated list of Custom Object Instances, by default ordered by updatedAt.

Request Params

Property	Type	Description
customObjectId	`string`	The Custom Object ID assigned by Vitally

Query Params (see Pagination)

Param	Type	Description
limit	`number`	(optional) The number of items to return. The max/default is 100
from	`string`	(optional) The cursor returned from a previous request
archived	`boolean`	(optional) Show only deleted items if `true`, or only active items if `false`

Example Requests

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances?limit=10&from=cursor

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances?archived=true

Example Response

{
  "results": [...],
  "next": "eyJzb3J0VmFsd...=="
}

Search Custom Object Instances `GET`

Find the first matching Custom Object Instance by id, externalId, customerId, organizationId, customFieldId or customFieldValue

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances/search

Request Params

Property	Type	Description
customObjectId	`string`	The Custom Object ID assigned by Vitally

Query Params (exactly one is required*)

Param	Type	Description
id	`string`	The Custom Object Instance ID assigned by Vitally
externalId	`string`	The unique ID of this Custom Object Instance in your system
customerId	`string`	The Customer ID assigned by Vitally
organizationId	`string`	The Organization ID assigned by Vitally
customFieldId	`string`	*The Custom Field (Trait) ID assigned by Vitally This is a UUID returned by the GET A Custom Object endpoint Must include customFieldValue when searching by customFieldId
customFieldValue	`string`	*The Custom Field (Trait) value Must include customFieldId when searching by customFieldValue

Example Request

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search?id=custom-object-instance-id

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search?externalId=custom-object-instance-external-id

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search?customerId=customer-id

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search?organizationId=organization-id

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search?customFieldId=custom-field-id

GET https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/search?customFieldValue=my-custom-field-value

Example Response

{
  "results": [...]
}

Create A Custom Object Instance `POST`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances

Request Params

Property	Type	Description
customObjectId	`string`	The Custom Object ID assigned by Vitally

Request Body

The Custom Object Instance can be associated with a customer, an organization, or to both, but at least one of them should be sent

Property	Type	Description
name	`string`	Required The name of the Custom Object Instance
customerId	`string`	The ID of the Vitally Customer to associate the Custom Object Instance with
organizationId	`string`	The ID of the Vitally Organization to associate the Custom Object Instance with
externalId	`string`	The unique ID of the Custom Object Instance in your system
createdByVitallyUserId	`string`	The ID of the internal Vitally User who created the Custom Object Instance
ownedByVitallyUserId	`string`	The ID of the internal Vitally User who owns the Custom Object Instance
traits	`key/value object`	A key-value JSON object of the Custom Object Instance traits
timestamp	`string`	Datetime the Custom Object Instance was created (defaults to current time)
description	`string`	HTML content for the instance's description. Vitally converts the HTML to the stored rich-text format, which is returned as `descriptionBody` in responses.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances
{
  "name": "custom-object-instance-1",
  "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "custom-object-external-id",
  "description": "<p>Implementation notes for this record.</p>",
  "traits": {
    "vitally.custom.organization": "my custom organization"
  }
}

Example Response

{
    "name": "My custom object instance",
    "customObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "externalId": "custom-object-external-id",
    "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "customer": { ... },
    "traits": {
        "vitally.custom.organization": "my custom organization"
    },
    ...
}

Update A Custom Object Instance `PUT`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/:instanceId

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances/:instanceId

Request Params

Property	Type	Description
instanceId	`string`	The Custom Object Instance ID assigned by Vitally
customObjectId	string	The Custom Object ID assigned by Vitally

Request Body

Property	Type	Description
name	`string`	The name of the Custom Object Instance
externalId	`string`	The unique ID of the Custom Object Instance in your system
traits	`key/value object`	A key-value JSON object of the Custom Object Instance traits
ownedByVitallyUserId	`string`	The ID of the internal Vitally User who owns the Custom Object Instance
description	`string`	Updated HTML content for the instance's description. Send `null` to clear the description. Omit the field entirely to leave the existing description unchanged.

Delete A Custom Object Instance `DELETE`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/:instanceId

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances/:instanceId

Request Params

Property	Type	Description
instanceId	`string`	The Custom Object Instance ID assigned by Vitally
customObjectId	string	The Custom Object ID assigned by Vitally

Custom Object Instance Parent Links

Account and Organization parent associations on a Custom Object Instance can be managed independently of the instance itself using dedicated link and unlink endpoints.

Link an Account `POST`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/:instanceId/customers/:customerKey

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances/:instanceId/customers/:customerKey

Request Params

Property	Type	Description
instanceId	`string`	Vitally Custom Object Instance UUID, or the instance's `externalId` when it matches the integration implied by `source`
customObjectId	`string`	The Custom Object ID assigned by Vitally
customerKey	`string`	Vitally Account ID, Account `externalId`, or Account `segmentId`

Query Params

Param	Type	Description
source	`string`	(Optional) Integration name for resolving `instanceId` as `externalId`. If omitted, the Public API integration for the token is used

Response

HTTP	Body	Meaning
201	`{ "created": true }`	A new Account link was created
200	`{ "created": false }`	The Account was already linked

Errors: 404 if the Custom Object, instance, or Account is not found. 400 if the Custom Object's integration does not allow another Account parent.

Unlink an Account `DELETE`

Request Params and Query Params match the POST above. Returns 204 on success. 404 if the Account is not linked to this instance.

Link an Organization `POST`

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/customObjects/:customObjectId/instances/:instanceId/organizations/:organizationKey

EU Data Center:

https://rest.vitally-eu.io/resources/customObjects/:customObjectId/instances/:instanceId/organizations/:organizationKey

Request Params

Property	Type	Description
customObjectId	`string`	Vitally Custom Object ID
instanceId	`string`	Vitally instance ID or `externalId` (with `source`)
organizationKey	`string`	Vitally Organization ID or Organization `externalId`

Query Params and source behavior match the Account link endpoints. Returns 201/200 on success. 403 if Organizations are disabled for this Vitally customer.

Unlink an Organization `DELETE`

Request Params and Query Params match the Organization POST above. Returns 204 on success. 404 if the Organization is not linked to this instance; 403 if Organizations are disabled.

REST API: Organizations

REST API: Users

REST API: Projects

REST API: Custom Traits

REST API: Project Templates

REST API: Custom Objects

The Custom Object object

Custom Object Custom Fields

The Custom Object Instance object

Custom Object Instance traits

Custom Objects

List Custom Objects GET

Get A Custom Object GET

Create A Custom Object POST

Update A Custom Object PUT

Custom Object Instances

List Custom Object Instances GET

Search Custom Object Instances GET

Create A Custom Object Instance POST

Update A Custom Object Instance PUT

Delete A Custom Object Instance DELETE

Custom Object Instance Parent Links

Link an Account POST

Unlink an Account DELETE

Link an Organization POST

Unlink an Organization DELETE

List Custom Objects `GET`

Get A Custom Object `GET`

Create A Custom Object `POST`

Update A Custom Object `PUT`

List Custom Object Instances `GET`

Search Custom Object Instances `GET`

Create A Custom Object Instance `POST`

Update A Custom Object Instance `PUT`

Delete A Custom Object Instance `DELETE`

Link an Account `POST`

Unlink an Account `DELETE`

Link an Organization `POST`

Unlink an Organization `DELETE`