Skip to main content
Extended properties let you attach your own key/value metadata to a resource without waiting on a schema change. Each property is a simple string key paired with a string value, stored alongside the resource and returned wherever that resource is returned. A handful of resource types support them today: User, Account, Contact, Project, and Appointment.

​
Supported resources

Extended properties use the same endpoint pattern on every supported resource — only the plural path segment changes.
Requesting extended properties for a resource type that doesn’t support them returns a 422 response.

​
Managing properties

The examples below use a contact, but the same requests work against any resource in the table above by swapping the path segment and id.

​
Creating or updating a property

Send a key and a value to add a property:
Posting a key that already exists updates its value instead of creating a duplicate. The response status reflects which happened: 201 Created for a new key, 200 OK when an existing key’s value was replaced. Updating a property directly by key (PUT .../extended-properties/{key}) behaves the same way — it creates the key if it doesn’t exist yet. A key can be at most 44 characters and is required. A value is optional (it may be null) but can be at most 255 characters. Either limit being exceeded returns a 422 validation error.

​
Listing a resource’s properties

Returns a paginated list of the resource’s key/value pairs.

​
Reading a single property

Returns 404 if the resource has no property with that key.

​
Removing a property

Returns 204 No Content, whether or not the key existed.

​
Searching by property

List endpoints that support extended properties accept a filter[extended_property][<key>]=<value> parameter to find records with a matching property. The example below finds every contact with a roof_color of forest-green:
The key in the brackets (roof_color above) is the property’s key, and the value matches exactly. As with other exact-match filters, comma-separate multiple values to match any of them, for example filter[extended_property][roof_color]=forest-green,charcoal. The same syntax works on users and contacts.
See Filtering and sorting for the general filter and sort syntax shared across every list endpoint.