Replace {subdomain} in the endpoint below with your Vitally subdomain.
You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io
Relationship between a Custom Object and a Custom Object Instance
A Custom Object is a record type in Vitally tied to an Account or Organization that you define, like Deals or Opportunities.
A Custom Object Instance (COI) is one actual record of that type. If Deals is your Custom Object, then "Q1 Renewal – Acme Co" is a Custom Object Instance. It's a single, specific Custom Object record.
Create / Update a Custom Object Instance
This endpoint will create or update a Custom Object Instance in Vitally based on the externalId parameter.
Headers
Name | Type | Description |
Content-Type* | string | Set to |
Authorization* | string | Set to |
Request Body
Name | Type | Description |
externalId* | string | Required The unique ID of this custom object instance record in your system |
customObjectId* | string | Required The ID of the Custom Object this instance belongs to (e.g., Deal or Opportunity)
The Custom Object ID can be found by referencing the ID in the URL when viewing the Custom Object settings in-app under Settings > Custom Objects > select your Custom Object. |
name | string | Name of the Custom Object Instance |
accountId | string | Required if
This should match the |
organizationId | string | Required if |
traits* | object | Required, but can be passed as an empty object
A JSON object containing the traits of this Custom Object Instance. |
timestamp | string | Required if |
messageId | string | Required if |
200 When your Custom Object Instance is created/updated, you'll receive
{"message":"Success."}
Example
An example curl request creating a Custom Object Instance would look like:
curl -X POST https://{subdomain}.api.vitally.io/analytics/v1/customobjectinstance \
-H "Authorization: Basic [your token]" \
-H "Content-Type: application/json" \
-d '{
"externalId": "coi-789xyz",
"customObjectId": "2a3a47e7-459e-440e-b9d3-9fc1b11f233e",
"name": "Q1 Pulse Check",
"accountId": "8643da72-4eb4-44e0-a29e-9afc06748349",
"traits": {
"vitally.custom.pulse": "Green",
"vitally.custom.riskLevel": "Low"
},
"timestamp": "2026-04-06T00:54:13.058Z"
}'