Retrieve a list of custom fields (get)

The get Ortto endpoint of the custom-field entity is used to retrieve a list of the custom contact (person) or organization fields in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

HTTP method and request resources

Custom contact field endpoint
POST https://api.ap3api.com/v1/person/custom-field/get
Custom organization field endpoint
POST https://api.ap3api.com/v1/organizations/custom-field/get

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

This endpoint does not take a request body.

Response payload

The response payload consists of a JSON object with the elements listed in the table below.

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

Example get custom person fields response payload from Ortto’s CDP
{
    "fields": [
        {
            "field": {
                "id": "int:cm:rating",
                "name": "Rating",
                "display_type": "integer",
                "liquid_name": "people.custom.rating"
            },
            "tracked_value": false
        }
    ]
}
Example get custom organization fields response payload from Ortto’s CDP
{
    "fields": [
        {
            "id": "str:oc:industry",
            "name": "Industry",
            "display_type": "text",
            "liquid_name": "organization.custom.industry"
        }
    ]
}

This endpoint will also return single/multi-select field values:

Example get custom person fields response payload with single-select field values
{
    "fields": [
        {
            "field": {
                "id": "str:cm:plan-tier",
                "name": "Plan tier",
                "display_type": "single_select",
                "liquid_name": "people.custom.plan-tier",
                "dic_items": [
                    "Bronze",
                    "Silver",
                    "Gold"
                ]
            },
            "tracked_value": true
        }
    ]
}

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element Type Description

fields

array of objects

The fields array consists of an array of objects, where each object contains data for the custom person or organization fields in your CDP.

* Person is an array of objects containing field instances and tracked_value.

* Organization is an array of field objects.

field

string

Identifies a custom person (contact) field object.

id

string

The identifier for the field name in Ortto’s custom field ID format.

name

string

The name specified for the field when it was created.

display_type

string

The name of the field type. See a list of field types under Request body in Create a custom field (create).

liquid_name

string

The Liquid language tag for the field.

dic_items

array

A list of the field’s values.

tracked_value

boolean

If true, updates to the person (contact) field are tracked and created as a custom activity. Otherwise, false.