Retrieve one or more people (get)

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.

type

string

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

type can accept the following values:

• "" (this the default value and will search for all contacts. It can be used with other elements described in this table, including filters as required)
• archived

If you are pairing type with archived, you cannot use filters or other elements (only the query string is accepted).

To retrieve a list of archived contacts:

json
 
{
  "type": "archived"
}

Or to use type with a filter, you can construct the body something like this:

json
 
{
"type": "",
"filter": {
  "$str::is": {
    "field_id": "str::email",
    "value": "contact@email.com"
}
}
}

filter

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

The filter element contains a field member that determines how records are filtered.

Therefore, a construct like:

json
 
"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:

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

You can also join filter conditions with AND/OR. The following construct shows an example for using $or (OR):

json
 
"filter": {
  "$or": [
    {
    "$str::is": {
      "field_id": "str::name",
      "value": "John Smith"
      }
    },
    {
    "$str::is": {
      "field_id": "str::email",
      "value": "jsmith@email.com"
      }
    }
  ]
}

→ field_id

string

The field_id element enables you to filter results by a field ID. This returns records that have the specified field populated and can be used in conjunction with value to filter records by specific field values.

→ value

string

Use value to specify a specific field value you wish to return contact records by. For example, this can be helpful if you are looking for a specific contact and filter by the contact’s email address:

json
 
"filter": {
  "$str::is":{
    "field_id": "str::email",
    "value": "contact@email.com"
}
}

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.

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

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.