REST API: Custom Objects

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 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
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
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
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

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.

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

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
customFieldValue	string	The Custom Field (Trait) value

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

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",
  "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

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