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.
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"
}
}
}
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:
|
|
|
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. |