API Documentation

Working with custom fields ¶

Creating custom fields ¶

When working with custom fields, you should first create a new custom field on the desired type of object (which you can specify with the customizable_type attribute). For more information about API requests for creating and managing custom field objects, check out API Documentation: Custom fields.

For this example, we will show how to create a custom field for a deal and populate the value of this custom field for a certain deal object.

First step is creating the custom field object:

POST https://api.productive.io/api/v2/custom_fields

The request body should contain information about customizable_type, data_type_id, and the name of the custom field.

{
  "data": {
    "type": "custom_fields",
    "attributes": {
      "name": "Review link",
      "data_type_id": 1,
      "customizable_type": "deals"
    }
  }
}

After you successfully create a new custom field object, the data part of the response body will contain the id of the created custom field.

"data": {
    "id": "307",
    "type": "custom_fields",
    "attributes": {
      "created_at": "2024-05-21T02:03:56.482+02:00",
      "updated_at": "2024-05-21T02:03:56.482+02:00",
      "name": "Review link",
      "data_type_id": 1,
      "required": false,
      "description": null,
      "archived_at": null,
      "aggregation_type_id": null,
      "formatting_type_id": null,
      "global": true,
      "show_in_add_edit_views": true,
      "sensitive": false,
      "position": 1,
      "customizable_type": "deals"
    }
  }

Filtering custom fields ¶

If you want to retrieve all custom fields, you can do so with this API request:

GET https://api.productive.io/api/v2/custom_fields

To add custom fields to objects, they must not be archived. To retrieve available custom fields, you can use this API request:

GET https://api.productive.io/api/v2/custom_fields?filter[archived]=false

And if you want to retrieve available custom fields for a specific customizable type, you can do so with this API request:

GET https://api.productive.io/api/v2/custom_fields?filter[archived]=false&filter[customizable_type]=deals

For more about filtering please check out API Documentation: Filtering

Adding custom fields to the object ¶

To add a custom field to a specific object, you should first retrieve this object and update its custom_fields attribute.

Remember, the custom_fields attribute on objects is a type of hash (dictionary). To prevent overwriting its values, always retrieve the entire object and add a new key (custom_field_id) to the custom_fields hash. If you remove the key, the custom field value will be lost.

Here is an example of the custom_fields attribute on objects such as people, deals, budgets etc.:

{
   "data": {
    "attributes": {
      ...
      "custom_fields": {
        "custom_field_id_1": "value1",
        "custom_field_id_2": 12,
        "custom_field_id_3": ["value3", "value4"],
      }
      ...
    }
  }
}

custom_field_id_1, custom_field_id_2, and custom_field_id_3 are the ids of the custom field objects.

If the data type is a number, the value should be numerical (12), for others the value should be a string (value1). If the data type is multiple select, the value should be an array of string values (["value3", "value4"]).

Keep in mind:

For person data type, this value is a person object id. For select and multiple select data types, it is the id of the custom field option objects.

Example

So the first step is to retrieve the deal object for which we want to update the custom field values.

GET https://api.productive.io/api/v2/deals/{id}

In the response body, we receive a custom_fields hash with already existing values.

{
  "data": {
    "attributes": {
      ...
        "custom_fields": {
            "63": [
                "70"
                ],
            "156": "code_321"
        }
      ...
    }
  }
}

If we want to add a new custom field value, we should update this custom_fields hash. Similarly, if we want to change the value or remove a value, then we only need to modify or remove that key-value pair from the hash.

For example to add the custom field “Review link” to a certain deal with the desired value "https://mylink.com" (assuming its id is 307), you can use the following API request:

PATCH https://api.productive.io/api/v2/deals/{id}

with request body:

{
    "data": {
        "id": "{id}",
        "type": "deals",
        "attributes": {
            "custom_fields": {
                "63": [
                    "70"
                ],
                "156": "code_321",
                "307": "https://mylink.com"
            }
        }
    }
}

Filtering objects by custom fields ¶

You can filter objects such as deals by their custom field values. The correct format for this would be:

GET https://api.productive.io/api/v2/deals?filter[custom_fields][custom_field_id][operation]=filter_value

For example, to filter all deals that have the Review Link custom field set as "https://mylink.com", you can make an API call like this:

GET https://api.productive.io/api/v2/deals?filter[custom_fields][307][eq]=https://mylink.com

For more information about filtering, please check out the API Documentation: Filtering