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:
-
valid parameters, headers, and request body values, as well as
-
the response payload.
HTTP method and request resource
POST https://api.ap3api.com/v1/person/get
Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:
For example: https://api.eu.ap3api.com/v1/<entity/endpoint> All other Ortto users will use the default service endpoint (https://api.ap3api.com/). |
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.
{
"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"
}
}
}
This endpoint also supports the use of AND/OR for filter conditions, as shown below for "$and" (AND).
$and
to join filter conditions{
"limit": 100,
"sort_by_field_id": "str::last",
"sort_order": "asc",
"offset": 0,
"fields": ["str::id", "str::last", "str::email"],
"filter": {
"$and": [
{
"$has_any_value": {
"field_id": "str::last"
}
},
{
"$str::is": {
"field_id": "str::email",
"value": "contact@email.com"
}
}
]
}
}
The AND/OR conditions can also be nested. The following example shows a query for people who:
-
Are located in Australia
AND
-
Have the label "VIP" OR the label "Highly engaged".
{
"limit": 100,
"sort_by_field_id": "str::last",
"sort_order": "asc",
"offset": 0,
"fields": ["str::id", "str::first", "str::last", "str::email"],
"filter": {
"$and": [
{
"$str::is": {
"field_id": "geo::country",
"value": "Australia"
}
},
{
"$or": [
{
"$str::is": {
"field_id": "str:cm:label",
"value": "VIP"
}
},
{
"$str::is": {
"field_id": "str:cm:label",
"value": "Highly engaged"
}
}
]
}
]
}
}
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 |
---|---|---|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
|
The |
|
The |
|
|
|
The |
|
The
If you are pairing To retrieve a list of archived contacts:
Or to use
|
|
Object containing a person’s field_ID (representing a person field) used for filtering |
The Therefore, a construct like:
where Similarly, the following construct would return people who do have their first name defined:
You can also join filter conditions with AND/OR. The following construct shows an example for using
|
|
|
The |
|
|
Use
|
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 |
|
A string whose value is this person’s first name. |
Last name |
|
A string whose value is this person’s last name. |
Phone number |
|
A phone number object of two members consisting of valid country code digits ( |
|
A string whose value is this person’s email address. |
|
City |
|
A geographical data object consisting of a member |
Country |
|
A geographical data object consisting of a member |
Birthday |
|
A date object consisting of members |
Region |
|
A geographical data object consisting of a member |
Postal |
|
A string whose value is this person’s current postal code. |
Tags |
|
An array whose string values are all tags currently specified on this person. |
Tag IDs |
|
An array whose integer values are the internal Ortto ID of all tags currently specified on this person. |
GDPR |
|
A boolean value where |
|
A string whose value is any ID used to uniquely identify this person. |
|
|
A boolean value where |
|
|
A string value representing the activity context message, when the email subscription permission was set to |
|
|
A string value representing the activity context message, when the email subscription permission was set to |
|
|
A boolean value where |
|
|
A string value representing the activity context message, when the SMS subscription permission was set to |
|
|
A string value representing the activity context message, when the SMS subscription permission was set to |
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 iscm
, 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 |
---|---|
|
Boolean |
|
Date (object) |
|
Geographical data (object) |
|
Integer. |
|
Phone number (object) |
|
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.
{
"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 |
---|---|
|
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. |
|
A hash of meta data containing information about the matches to your contacts GET request, including:
|
|
The offset which was set on this request. |
|
The offset for fetching the next page of contacts. |
|
When retrieving the next page of contacts, provide this cursor_id. |
|
Whether or not there is a next page of contacts. |