Create a custom field (create)

The create Ortto endpoint of the custom-field entity is used to create one or more custom contact (person) or organization fields in Ortto’s customer data platform (CDP).

Most field types are supported when creating a custom field, and follow the same rules/limits seen when creating a field the Ortto app. The field type not supported is aggregate.

NOTE: Up to 100 custom fields can be added to an Ortto account/instance.

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/create

Custom organization field endpoint


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

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 create custom fields in your Ortto account’s CDP.

NOTE:

Only single_select and multi_select field types require the values key.
Duplicate name values are not allowed.

Example create text field request body


 {
  "type": "text",
  "name": "apiCreateTextField"
  "track_changes": false
}

Example create single-select field request body


 {
    "type":"single_select",
    "name":"apiCreateSingleSelectField",
    "values": ["option1", "option 2"]
}

Valid request body elements

Element	Type	Description
`type`	`string`	Specify the type of field to create. See the table below for a list of all possible field types.
`name`	`string`	The name of the field.
`values`	array of strings	Provide the options available when using a single-select or multi-select field.
`track_changes`	`bool`	Turn On or Off field change tracking. Learn more about field update tracking.

Available field types:

Field type	Input	Description
Text	`text`	Any combination of letters and numbers whose length is 500 characters or fewer, irrespective of the language used.
Long text	`large_text`	A text field type whose length is 500 characters or more, irrespective of the language used.
Number	`integer`	A whole (integer) number.
Decimal number	`decimal`	A decimal (floating point) number.
Currency	`currency`	A decimal number displayed as currency. The currency symbol used to represent this field’s values in person and organization record data is based on the Default currency settings (accessible through the General settings page).
Multi currency	`price`	A decimal number displayed as international currency. The currency symbol used to represent this field’s values in person and organization record data is based on the ISO currency code supplied with the field data. See also List of currencies.
Date	`date`	A specific day, month and year.
Time and date	`time`	A specific time and date.
Boolean	`bool`	A `true` (on) or `false` (off) value.
Phone number	`phone`	A local or international phone number.
Single select	`single_select`	A list of values you define from which a single item can be selected. When choosing this field type, use `values` to specify each value from which multiple items can be selected.
Multi select	`multi_select`	A list of values you define from which multiple items can be selected. When choosing this field type, use `values` to specify each value from which multiple items can be selected.
Link	`link`	The URL of a webpage or file.
Object	`object`	A JSON object containing custom data.

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 people’s data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example create text field response payload from Ortto’s CDP

json
 {
    "name": "apiCreateTextField",
    "field_id": "str:cm:apicreatetextfield",
    "display_type": "text",
    "track_changes": false
}

Example create single select field response payload from Ortto’s CDP

json
 {
    "name": "apiCreateSingleSelectField",
    "field_id": "str:cm:apicreatesingleselectfield",
    "display_type": "single_select"
    "values": [
        "option1",
        "option 2"
    ],
    "track_changes": false
}

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
`name`	`string`	The `name` for the custom field specified in the request body.
`field_id`	`string`	The person field ID for the custom field. Learn more about Ortto’s person fields.
`display_type`	`string`	The name for the field `type` specified in the request body.
`values`	array of strings	The names of the values specified in the request body.
`track_changes`	`bool`	Whether field updates are being tracked or not.