Retrieve one or more people (get)

The get Ortto endpoint of the person entity is used to retrieve data from one or more person records in Ortto’s customer data platform (CDP).

This page provides descriptions of this endpoint’s:

HTTP method and request resource

POST https://api.ap3api.com/v1/person/get

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 whose valid elements are listed in the table below.

The following JSON object is an example of field and object data that Ortto can recognize to get data from one or more person records in your Ortto account’s CDP.

Example get people request body from Ortto’s CDP
{
  "limit": 100,
  "sort_by_field_id": "str::last",
  "sort_order": "asc",
  "offset": 0,
  "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"],
  "filter": {
    "$has_any_value": {
      "field_id": "str::first"
    }
  }
}

Valid request body elements

The following table lists all valid request body elements (arrays, objects, or fields), which are available to this endpoint.

Element Type Description

limit

integer between 1 to 500
(default value is 50)

The limit element value determines the number of people to be returned by Ortto from the request.
This value also represents the "page" length of people (for pagination purposes), since potentially many thousands of people records could be retrieved from a single request. This element can be used in conjunction with offset to retrieve subsequent pages of people records.
If this limit element is not specified in the request, or an integer value beyond the permitted maximum is specified, then this value is assumed to be 50.

sort_order

string with value asc or desc
(default value is desc)

The sort_order element determines the order in which the people returned are sorted, based on the sort_by_field_id member value. Specifying this sort_order member is only relevant when the sort_by_field_id member is also specified.

sort_by_field_id

string

The sort_by_field_id element whose field ID value specifies the person field used to sort the people returned from your Ortto account’s CDP.

offset

integer with a default value of 0

The offset element represents the count of people records in your Ortto account’s CDP for pagination purposes, and is the point from which the next page of people (defined by the limit member value) is retrieved.

cursor_id

string containing a UUID value
(e.g. 00609c898a4490c5800a5453)

The cursor_id element is the UUID for the start of the first person record in the next page of people (defined by the limit member value). This value is retrieved from the previous /v1/person/get endpoint request.

fields

array of string values

The fields array contains person field ID values that define the person fields of the person records returned by Ortto from the request.

q

string

The q element is a valid text string used to filter the people records returned by Ortto from the request.

filter

Object containing a person’s field ID (representing a person field) used for filtering

The filter element contains a field member that determines whether records are filtered with ($has_any_value) or without ($has_no_value) a person field’s value.

Therefore, a construct like:

"filter": {
  "$has_no_value": {
    "field_id": "str::first"
  }
}

where str::first is the person’s First name field would filter and return people who do not have their first name defined.

Similarly, the following construct would return people who do have their first name defined:

"filter": {
  "$has_any_value": {
    "field_id": "str::first"
  }
}

Person fields

In Ortto, a person field:

  • contains the data for a specific piece of information (i.e. field) about each person in Ortto’s CDP,

  • is referenced via the Ortto API using a specific ID format, and

  • could be a built in Ortto field or a custom field you have defined yourself (which also has its own ID format), and

  • is returned by Ortto in the response, based on the fields array values submitted in the request to this endpoint.

Data about the following built-in person fields can be obtained through Ortto’s API when retrieving people from the CDP.

Field name (in product) Field ID Returns

First name

str::first

A string whose value is this person’s first name.

Last name

str::last

A string whose value is this person’s last name.

Phone number

phn::phone

A phone number object of two members consisting of valid country code digits (c) and a phone number (n), representing this person’s phone number.

Email

str::email

A string whose value is this person’s email address.

City

geo::city

A geographical data object consisting of a member name whose string value is this person’s current city.

Country

geo::country

A geographical data object consisting of a member name whose string value is this person’s current country.

Birthday

dtz::b

A date object consisting of members year, month and day whose respective integer values represent this person’s date of birth, along with a timezone string representing the person’s current time zone.

Region

geo::region

A geographical data object consisting of a member name whose string value is this person’s current region (e.g. state or province) within their country.

Postal

str::postal

A string whose value is this person’s current postal code.

Tags

tags

An array whose string values are all tags currently specified on this person.

Tag IDs

u4s::t

An array whose integer values are the internal Ortto ID of all tags currently specified on this person.

GDPR

bol::gdpr

A boolean value where true flags that GDPR is a requirement for this person, or false if not.

External ID

str::ei

A string whose value is any ID used to uniquely identify this person.

Email subscription permission

bol::p

A boolean value where true flags that the person has their Email permission set to true, or Subscribed through the Ortto user interface (UI), and false flags that this person’s permission is set to false (or Unsubscribed).

Context message for the email unsubscribe action

str::u-ctx

A string value representing the activity context message, when the email subscription permission was set to false.
These messages appear in people’s Activities updates in the Ortto UI.

Context message for the email subscribe action

str::s-ctx

A string value representing the activity context message, when the email subscription permission was set to true.
These messages appear in people’s Activities updates in the Ortto UI.

SMS subscription permission

bol::sp

A boolean value where false flags that the person has their SMS permission set to false, or Unsubscribed through the Ortto UI, and true flags that this person’s permission is set to true (or Subscribed).
If this person field is not specified in the request, then this value is assumed to be false by default.

Context message for the SMS subscribe action

str::soi-ctx

A string value representing the activity context message, when the SMS subscription permission was set to true.
These messages appear in people’s Activities updates in the Ortto UI.

Context message for the SMS unsubscribe action

str::soo-ctx

A string value representing the activity context message, when the SMS subscription permission was set to false.
These messages appear in people’s Activities updates in the Ortto UI.

Person field ID format

Each person field is referenced by an ID.

Since Ortto integrates with many third-party products, references to most person fields in Ortto’s CDP are both strongly-typed and namespace-specific. Therefore, for most person fields, the field’s ID is based on the format:

  • type:namespace:field-name

For:

  • Ortto’s own built-in person fields, the namespace value is unnecessary and is omitted. Hence, these built-in fields are referenced by an ID based on the format:

    • type::field-name

  • Your own custom person fields in Ortto, the namespace value is cm, and hence, these custom fields are referenced by an ID based on the format:

    • type:cm:field-name

    • Data from custom fields can also be retrieved in person records from requests to this endpoint.

    • The field-name for custom fields is typically based on their configured names converted to kebab-case.

Person field type abbreviations

The following person field type abbreviations are used to form the first part (type) of each person field’s ID for built-in fields:

Field type abbreviation Type of value

bol

Boolean

dtz

Date (object)

geo

Geographical data (object)

int

Integer.
For internal operations and calculations, the Ortto API treats decimal values as integers multiplied by 1,000. This is done to preserve the precision of values resulting from these calculations.

phn

Phone number (object)

str

String

Response payload

The response payload consists of a JSON object whose elements are 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 get people response payload from Ortto’s CDP
{
   "contacts":[
      {
         "id":"0061b02b24f9b6f85dcb1e00",
         "fields":{
            "str::ei":"c533532fe5d16c7d4fa4c7f0",
            "str::email":"alex@example.com",
            "str::first":"Alex"
         }
      },
      {
         "id":"006153c064088217368efb00",
         "fields":{
            "str::email":"chris.hiedler@example.com",
            "str::first":"Chris",
            "str::last":"Hiedler"
         }
      },
      {
         "id":"006153c064088217368ef500",
         "fields":{
            "str::email":"alex.kodjo@example.com",
            "str::first":"Alex",
            "str::last":"Kodjo"
         }
      },
      {
         "id":"006153c064088217368ef800",
         "fields":{
            "str::email":"lana.romeijn@example.com",
            "str::first":"Lana",
            "str::last":"Romeijn"
         }
      },
      {
         "id":"0061b12ed91681ad2bbe4100",
         "fields":{
            "idt::o":"106153c398e0fdf2320c0700",
            "str::email":"chris.smith@example.com",
            "str::first":"Chris",
            "str::last":"Smith",
            "str:cm:job-title":"Technician"
         }
      }
   ],
   "meta":{
      "total_contacts":5,
      "total_organizations":0,
      "total_matches":5,
      "total_subscribers":5
   },
   "offset":0,
   "next_offset":5,
   "cursor_id":"0062299d655c7cf67184e1e0",
   "has_more":false
}

Response payload elements

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

Element Description

contacts

An array of contacts with an id and a fields hash which contacts the list of fields you requested to be returned. Note that if a contact has an associated organization it will include a idt::o field, which is the ID of the organization with which this contact is associated.

meta

A hash of meta data containing information about the matches to your contacts GET request, including:

  • total_contacts - Number of people in your database in total

  • total_organizations - Number of organizations in your database in total

  • total_matches - Number of people matching your query or filter

  • total_subscribers - Number of contacts in your database who are subscribed to receive email marketing

offset

The offset which was set on this request.

next_offset

The offset for fetching the next page of contacts.

cursor_id

When retrieving the next page of contacts, provide this cursor_id.

has_more

Whether or not there is a next page of contacts.