Request Format

To create a Custom Attribute, you must send a JSON:API spec JSON object. The list of attributes and relationships can be found in BODY PARAMS section

The Resource

Custom Attributes can be created for a select number of resources. The current list of supported resources is available in the data.relationships. custom_attributable.data.type field documentation in BODY PARAMS section.

The `Custom Field`

Before creating a Custom Attribute for a resource, decide which Custom Field the attribute will be for. As described here, a Custom Attribute stores a value for a predefined field (CustomField) which can be considered a label or key.

If you haven't yet defined any Custom Fields, there are two ways to do so:

Use the Create Custom Field API endpoint.
In the UI - refer to this help guide.

📘
Custom Field resource type
Please bear in mind that Custom Fields are defined for a specific resource type (e.g. job).
resource_type of the Custom Field must match the type of the resource that you want to create a new Custom Attribute for.

Example

When CustomField.resource_type is job then it can only be used to create CustomAttributes for Jobs (custom_attributable.type == jobs)

After setting up your Custom Fields, you can create Custom Attributes for them. This requires knowing the id of the Custom Field, which you can obtain from the List Custom Fields endpoint.

The Value Type

Custom Attributes can support multiple data types.

📘
Important
The data type stored in the Custom Attribute must match the data type of the associated Custom Field (field_type).

To check the data type of a Custom Field for which you wish to create a Custom Attribute, you can:

Fetch the Custom Field using Fetch Custom Field or List Custom Fields and check the field_type attribute.
Open the Custom Field for editing in the UI (navigate to the Custom Fields page from the Pinpoint settings menu).

The list of supported Custom Field types can be found here.

When you know the data type, fill in the corresponding_value field when creating a new Custom Attribute. Leave the rest of the _value fields empty.

Example

If the field_type of the Custom Field you wish to create a Custom Attribute for is boolean, then place the value in the boolean_value attribute.

Uniqueness

There can only be one Custom Attribute for a specific Custom Field and a given resource.

If you need to replace an existing one, please Update Custom Attribute or Delete Custom Attribute and create a new one.

Summary

When creating a Custom Attribute make sure that:

Custom Field resource_type matches the type of the resource (custom_attributable) for which you are creating the Custom Attribute
You fill the_value attribute which corresponds to the field_type of the associated Custom Field and leave the rest of the attributes empty.