Updating custom fields via the API

The update Ortto endpoint of the custom-field entity is used to update single-select and multi-select field options, as well as starting or stopping tracking field changes in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

request resource and method,
valid parameters, headers, and request body values, as well as
the response payload.

HTTP method and request resources

Custom contact field endpoint


 PUT https://api.ap3api.com/v1/person/custom-field/update

Custom organization field endpoint


 PUT https://api.ap3api.com/v1/organizations/custom-field/update

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object with the valid elements listed in the table below.

The following JSON objects are examples of requests to update your custom field in your Ortto account’s CDP.

Request body standard structure


 {
  "field_id": "str:cm:my-field",
  "replace_values": [],
  "add_values": [],
  "remove_values": [],
  "track_changes": false
}

Example request body


 {
  "field_id": "str:cm:brand",
  "replace_values": ["Nike", "Adidas"],
  "track_changes": false
}

NOTE: You can only change the values for Single-select or Multi-select fields.

Multi-select fields are not eligible for change tracking.

Payload elements

The following table lists all elements supported in this payload.

Element	Description
`field_id`	The field ID for the custom field. Learn more about Ortto’s person fields.
`replace_values`	Removes all existing options and replaces them with the provided set of values. E.g. existing was A,B,C but we replaced with X,Y,Z.
`add_values`	Appends the provided values to the existing options. E.g. existing was A,B,C and we simply want to add D.
`remove_values`	Removes the provided values from existing options. E.g. existing was A,B,C,D but we want to remove D.
`track_changes`	Turns ON or OFF field change tracking. Learn more about tracking field changes.

NOTE: You only need to provide one of the following elements per payload: add_values, remove_values, or replace_values.

If more than one element is provided, only one will be processed. We'll use the following order:

replace_values: If present, replace the values and ignore the subsequent elements.
add_values: If replace_values is not provided, process add_values and ignore remove_values (if present).
remove_values: If replace_values and add_values are not provided, process remove_values only.

Response payload

The following JSON object is an example of people’s data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example replace_values response payload from Ortto’s CDP

json
 {
    "field_id": "sst:cm:brand",
    "values": [
        "Nike",
        "Adidas"
    ],
    "track_changes": false
}

Example add_values response payload from Ortto’s CDP

json
 {
    "field_id": "sst:cm:brand",
    "values": [
        "Nike",        
        "Adidas",        
        "Puma"
    ],
    "track_changes": false
}