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:

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


 POST https://api.ap3api.com/v1/person/custom-field/get

Custom organization field endpoint


 POST https://api.ap3api.com/v1/organizations/custom-field/get

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

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

json
 {
    "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

json
 {
    "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

json
 {
    "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`.