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

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

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
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
timestamp	`string`	Datetime the Custom Object Instance was created (defaults to current time)

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
ownedByVitallyUserId	`string`	The ID of the internal Vitally User who owns the Custom Object Instance

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

REST API: Notes

REST API: Projects

REST API: Tasks

REST API: Custom Traits

REST API: Project Templates

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

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`