REST API: Custom Objects
Last updated
Last updated
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
Property | Description |
---|---|
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
You can set values for the Custom Object Instance traits using the Custom Object custom field key, when POST
ing or PUT
ing to the API:
Example Request
Example Response
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.
GET
US Data Center (default):
EU Data Center:
Paginated list of Custom Objects, by default ordered by updatedAt
.
Params (see Pagination)
Example Request
Example Response
GET
US Data Center (default):
EU Data Center:
Request Params
Example Request
POST
US Data Center (default):
EU Data Center:
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
Example Response
PUT
US Data Center (default):
EU Data Center:
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
Example Response
GET
US Data Center (default):
EU Data Center:
Paginated list of Custom Object Instances, by default ordered by updatedAt
.
Request Params
Query Params (see Pagination)
Example Requests
Example Response
GET
Find the first matching Custom Object Instance by id
, externalId
, customerId
, organizationId
, customFieldId
or customFieldValue
US Data Center (default):
EU Data Center:
Request Params
Query Params (exactly one is required)
Example Request
Example Response
POST
US Data Center (default):
EU Data Center:
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
Example Response
PUT
US Data Center (default):
EU Data Center:
Request Params
Request Body
US Data Center (default):
EU Data Center:
Request Params
Property | Description | Editable |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Param | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | Description |
---|---|---|
Property | Type | 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.
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
id
string
The Custom Object ID assigned by Vitally
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
id
string
(Required) The Custom Object ID assigned by Vitally.
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
customObjectId
string
The Custom Object ID assigned by Vitally
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
customObjectId
string
The Custom Object ID assigned by Vitally
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
customObjectId
string
The Custom Object ID assigned by Vitally
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)
instanceId
string
The Custom Object Instance ID assigned by Vitally
customObjectId
string
The Custom Object ID assigned by Vitally
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
instanceId
string
The Custom Object Instance ID assigned by Vitally
customObjectId
string
The Custom Object ID assigned by Vitally