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.

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

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/create
Custom organization field endpoint
POST https://api.ap3api.com/v1/organizations/custom-field/create

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.

  • 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"
}
Example create single-select field request body
{
    "type":"single_select",
    "name":"apiCreateSingleSelectField",
    "values": ["option1", "option 2"]
}
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 setup page).

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

For organization fields only.

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
{
    "name": "apiCreateTextField",
    "field_id": "str:cm:apicreatetextfield",
    "display_type": "text"
}
Example create single select field response payload from Ortto’s CDP
{
    "name": "apiCreateSingleSelectField",
    "field_id": "str:cm:apicreatesingleselectfield",
    "display_type": "single_select"
    "values": [
        "option1",
        "option 2"
    ]
}

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.