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

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

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

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

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"
        }
    ]
}

Create 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

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

Example Request

POST 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

Query Params (see Pagination)

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

Query Params (exactly one is required)

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

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

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

Request Body

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