Learn how to store custom data on various resources.
In certain scenarios, you may want to store additional metadata on a specific Contractors Cloud resource such as a Project, Account, Contact, etc. The Contractors Cloud API allows you to set key-value pairs on various supported resources called Extended Properties. Extended properties make it easy to store application-specific data for a resource without having to utilize an external database.
Supported resources
Currently, only the following resources support the concept of extended properties:
We may add extended properties support for additional resources in the future or if we receive requests for it.
Managing properties
Endpoints to create, read, update or delete extended properties on any of the supported resources are available to you.
Create / Update Properties
The create and update endpoints will function the same. If you try to create a property that already exists, it will be updated instead. If you try to update a property that doesn't exist, it will be created instead.
Search properties
You can search resources based on the values of their extended properties using the concept of filters. Simply provide the property name and value(s) you would like to target. For example, the following request would return contacts where the property gender=male and the property favorite_coloris blueor green:
GET: api/v1/contacts?filter[extended_property][gender]=male&filter[extended_property][favorite_color]=blue,green
Limits
- The maximum size of a property's key is 44 characters, and properties with longer keys will either be silently dropped or produce a 422 validation error.
- The maximum size of a property's value is 255 characters, and properties with longer values will either be silently truncated or produce a 422 validation error.