Retrieving people’s data

Learn how to use the Ortto API to retrieve data from existing people's records in your Ortto account’s customer data platform (CDP) through the examples on this page.

Requests to retrieve people’s records in your Ortto CDP are submitted as a single POST method call to the following URL:

https://api.ap3api.com/v1/people/get

In a given request:

  • the actual people’s data retrieved from the CDP is determined by the specified fields values, and

  • the people records retrieved are filtered by the specified q and filter values.

Each copyable code example on this page is annotated with callouts along with associated explanations.

cURL example

cURL example request to retrieve select data from people’s records in the Ortto CDP
curl --request POST 'https://api.ap3api.com/v1/person/get' \ (1)
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \ (2)
     --header 'Content-Type: application/json' \
     --data '{
        "limit": 100, (3)
        "sort_by_field_id": "str::last", (4)
        "sort_order": "asc", (5)
        "offset": 0, (6)
        "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"], (7)
        "filter": { (8)
          "$has_any_value": {
            "field_id": "str::first"
          }
        }
      }'
1 The API endpoint for retrieving data from one or more people’s records in Ortto.
2 The custom API key configured as part of the getting started process.
3 The limit defines the page length (i.e. 100) of all people retrieved in the response from the request.
4 The sort_by_field_id defines the person field (i.e. Last name) used to sort the people returned from your Ortto account’s CDP.
5 The sort_order is only used when sort_by_field_id is specified in the same request. The sort_order value defines the order in which people records are returned, based on the sort_by_field_id element’s person field values. In this case, people are returned in ascending (asc) alphabetical order of their Last name values.
6 The offset defines the point in the CDP from which the next page of people are retrieved, which in this case is from the first person’s record in the CDP.
7 The fields define which person fields' data is returned from the CDP for each person’s record. In this example, data from a person custom field (i.e. str:cm:job-title) in each person’s record from the CDP.
Learn more about working with custom fields in the User guide, and how to derive their field IDs in the API reference docs.
8 The filter defines which people’s records are filtered and retrieved from the CDP based on whether or not they possess a person field’s value. In this example, only people’s records with the First name specified are retrieved from the CDP.

Node.js example

Node.js example of the same cURL request (described above) to retrieve select data from people’s records in the Ortto CDP
const data = {
  "limit": 100, (3)
  "sort_by_field_id": "str::last", (4)
  "sort_order": "asc", (5)
  "offset": 0, (6)
  "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"], (7)
  "filter": { (8)
    "$has_any_value": {
      "field_id": "str::first"
    }
  }
};

request({
  url: 'https://api.ap3api.com/v1/person/get', (1)
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY', (2)
    'Content-Type': 'application/json'
  },
  json: data
}, (err, resp, body) => {
  console.log("API response:", body);
});

Response example

The following response payload is an example from the cURL and Node.js examples above, which retrieved select data (specified through fields in the request) from people’s records in an Ortto CDP (consisting of only 5 people records).
In reality, your Ortto CDP is likely to consist of hundreds to many thousands of people records.

Response payload example from the cURL or Node.js request above
{
   "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
}

Retrieving the next page of contacts

If we retrieve the first page of contacts like so:

curl --request POST \
  --url https://api.ap3api.com/v1/person/get \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: X-API-KEY' \
  --data '{
	"limit": 50,
}'

The response is:

{
   "contacts":[
      {
         "id":"00609c9e644490c5800da401",
         "fields":{
            "idt::o":"10609c9eba4490c5800dad00"
         }
      },
      {
         "id":"00609c9db64490c5800d9900",
         "fields":{
            "idt::o":"10609c9ddbb2bdea4cbc3601"
         }
      },
      {
         "id":"00609c9cf04490c5800d6101",
         "fields":{
            "idt::o":"10609c9d1bb2bdea4cbbf900"
         }
      },
      {
         "id":"00609c9a34b2bdea4cbb4300",
         "fields":{
            "idt::o":"10609c9b9d4490c5800d5701"
         }
      },
      {
         "id":"00609c96254490c5800cc101"
      },
      {
         "id":"00609c93d34490c5800c5400",
         "fields":{
            "idt::o":"10609c93d34490c5800c5700"
         }
      },
      {
         "id":"00609c934bb2bdea4cba2d01",
         "fields":{
            "idt::o":"10609c93a64490c5800c4e00"
         }
      },
      {
         "id":"00609c8f71b2bdea4cb8af00",
         "fields":{
            "idt::o":"10609c8fa24490c5800b8c01"
         }
      },
      {
         "id":"00609c8f1f4490c5800b7401",
         "fields":{
            "idt::o":"10609c8f594490c5800b8300"
         }
      },
      {
         "id":"00609c8e5e4490c5800b5300"
      },
      {
         "id":"00609c89df4490c5800a6c01",
         "fields":{
            "idt::o":"10609c8a25b2bdea4cb7e500"
         }
      },
      {
         "id":"00609c86fc4490c5800a0600",
         "fields":{
            "idt::o":"10609c87424490c5800a1501"
         }
      },
      {
         "id":"00609c85b8b2bdea4cb6e001",
         "fields":{
            "idt::o":"10609c86414490c58009e200"
         }
      },
      {
         "id":"00609c7db2a9b4c251966500"
      },
      {
         "id":"00609c7bc34490c580075f01",
         "fields":{
            "idt::o":"10609c7c15a9b4c25195ee00"
         }
      },
      {
         "id":"00609c7b5da9b4c25195c800"
      },
      {
         "id":"00609c75f94490c580064001",
         "fields":{
            "idt::o":"10609c761f4490c580064900"
         }
      },
      {
         "id":"00609c6824c536dc9bbf3200",
         "fields":{
            "idt::o":"10609c6908c536dc9bbf5d01"
         }
      },
      {
         "id":"00609c67ab241bfc04733901",
         "fields":{
            "idt::o":"10609c67ab241bfc04733c01"
         }
      },
      {
         "id":"00609c672cc536dc9bbefd00",
         "fields":{
            "idt::o":"10609c6776241bfc04732d01"
         }
      },
      {
         "id":"00609c6683241bfc0472fc01"
      },
      {
         "id":"00609c65b0c536dc9bbead00",
         "fields":{
            "idt::o":"10609c65b0c536dc9bbeb000"
         }
      },
      {
         "id":"00609c6586c536dc9bbe9b01",
         "fields":{
            "idt::o":"10609c6586c536dc9bbe9e01"
         }
      },
      {
         "id":"00609c5b40241bfc046ef200",
         "fields":{
            "idt::o":"10609c5b5b241bfc046f0101"
         }
      },
      {
         "id":"00609c5825241bfc046e6c01",
         "fields":{
            "idt::o":"10609c5884c536dc9bbbb800"
         }
      },
      {
         "id":"00609c50a5c536dc9bba9300"
      },
      {
         "id":"00609c4df8241bfc046c8701",
         "fields":{
            "idt::o":"10609c4e12c536dc9bb9f700"
         }
      },
      {
         "id":"00609c4d20c536dc9bb9e700"
      },
      {
         "id":"00609c4b9d241bfc046bc300",
         "fields":{
            "idt::o":"10609c4bd5241bfc046be000"
         }
      },
      {
         "id":"00609c4aafc536dc9bb9db01"
      },
      {
         "id":"00609c4aac241bfc046b7c01",
         "fields":{
            "idt::o":"10609c4b22241bfc046b9c00"
         }
      },
      {
         "id":"00609c46c1241bfc046b3f00",
         "fields":{
            "idt::o":"10609c470ac536dc9bb90e01"
         }
      },
      {
         "id":"00609c460dc536dc9bb8ce01",
         "fields":{
            "idt::o":"10609c4632241bfc046b3900"
         }
      },
      {
         "id":"00609c45a2241bfc046b3100",
         "fields":{
            "idt::o":"10609c45b9c536dc9bb8c201"
         }
      },
      {
         "id":"00609c3efb241bfc046a6f01"
      },
      {
         "id":"00609c3d01c536dc9bb76e00",
         "fields":{
            "idt::o":"10609c3d30c536dc9bb77101"
         }
      },
      {
         "id":"00609c3a7d241bfc04682c01",
         "fields":{
            "idt::o":"10609c3a8f241bfc04683501"
         }
      },
      {
         "id":"00609c3a63c536dc9bb75900",
         "fields":{
            "idt::o":"10609c3aa0241bfc04684100"
         }
      },
      {
         "id":"00609c38f8241bfc0467f901"
      },
      {
         "id":"00609c376dc536dc9bb70500",
         "fields":{
            "idt::o":"10609c37d9241bfc0467c901"
         }
      },
      {
         "id":"00609c3752c536dc9bb6ff01",
         "fields":{
            "idt::o":"10609c37d7241bfc0467c601"
         }
      },
      {
         "id":"00609c2f74c536dc9bb53700",
         "fields":{
            "idt::o":"10609c2f9bc536dc9bb53d01"
         }
      },
      {
         "id":"00609c2d3e241bfc04663601",
         "fields":{
            "idt::o":"10609c3085241bfc04671e01"
         }
      },
      {
         "id":"00609c2addc536dc9bb4a100"
      },
      {
         "id":"00609c265d241bfc04646e01",
         "fields":{
            "idt::o":"10609c266c241bfc04647700"
         }
      },
      {
         "id":"00609c2460241bfc0463f300"
      },
      {
         "id":"00609c2321c536dc9bb42100",
         "fields":{
            "idt::o":"10609c23a0c536dc9bb43600"
         }
      },
      {
         "id":"00609c2136241bfc04631a01",
         "fields":{
            "idt::o":"10609c2164c536dc9bb3e100"
         }
      },
      {
         "id":"00609c2128241bfc04631101",
         "fields":{
            "idt::o":"10609c2149c536dc9bb3da00"
         }
      },
      {
         "id":"00609c1f7c241bfc0462ce00"
      }
   ],
   "meta":{
      "total_contacts":3204,
      "total_organizations":0,
      "total_matches":3204,
      "total_subscribers":3118
   },
   "offset":0,
   "next_offset":50,
   "cursor_id":"00609ca2444490c5800e0605",
   "has_more":true
}

We retrieve the second page of contacts like this:

curl --request POST \
  --url http://localhost:8100/v1/person/get \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: X-API-KEY' \
  --data '{
	"limit": 50,
        "offset": 50,
        "cursor_id": "00609ca377b2bdea4cbd4645"
}'

And then we receive the next 50 contacts with the offset, next_offset and cursor_id updated:

{
   "contacts":[
      {
         "id":"00609c1f7c241bfc0462ce00"
      },
      {
         "id":"00609c1e70241bfc04600501"
      },
      {
         "id":"00609c1d30241bfc045fe100",
         "fields":{
            "idt::o":"10609c1dcec536dc9bb35001"
         }
      },
      {
         "id":"00609c1cf2241bfc045fda01",
         "fields":{
            "idt::o":"10609c1ec6241bfc0462a800"
         }
      },
      {
         "id":"00609c18ac241bfc045f3600"
      },
      {
         "id":"00609c15f9241bfc04422b01",
         "fields":{
            "idt::o":"10609c16f9241bfc0442b200"
         }
      },
      {
         "id":"00609c065a241bfc04402100",
         "fields":{
            "idt::o":"10609c06a9c536dc9baec701"
         }
      },
      {
         "id":"00609c0527c536dc9badc001",
         "fields":{
            "idt::o":"10609c054e241bfc04401700"
         }
      },
      {
         "id":"00609c0476c536dc9bad8100"
      },
      {
         "id":"00609c041a241bfc04400901"
      },
      {
         "id":"00609c038b241bfc043ffe00",
         "fields":{
            "idt::o":"10609c03e9c536dc9bad4901"
         }
      },
      {
         "id":"00609c01eb241bfc043fe701",
         "fields":{
            "idt::o":"10609c01fb241bfc043ff000"
         }
      },
      {
         "id":"00609bfe80241bfc043f7a00",
         "fields":{
            "idt::o":"10609bfec0241bfc043f7f01"
         }
      },
      {
         "id":"00609bf9f5241bfc043eb301",
         "fields":{
            "idt::o":"10609bfa56241bfc043ebc00"
         }
      },
      {
         "id":"00609bf875c536dc9baaa300",
         "fields":{
            "idt::o":"1060992abdf990e1f935da01"
         }
      },
      {
         "id":"00609bf6ad241bfc043d8001",
         "fields":{
            "idt::o":"10609bf6e2c536dc9ba9d000"
         }
      },
      {
         "id":"00609bf41ac536dc9ba98b00",
         "fields":{
            "idt::o":"10609bf7f3241bfc043dec00"
         }
      },
      {
         "id":"00609bf401c536dc9ba97f01",
         "fields":{
            "idt::o":"10609bf494c536dc9ba9a301"
         }
      },
      {
         "id":"00609bf3b4241bfc043cc300",
         "fields":{
            "idt::o":"10609bf3b4241bfc043cc600"
         }
      },
      {
         "id":"00609bf295c536dc9ba90a01",
         "fields":{
            "idt::o":"10609bf2a5241bfc043cb200"
         }
      },
      {
         "id":"00609bf25b241bfc043cac00",
         "fields":{
            "idt::o":"10609bf2be241bfc043cb500"
         }
      },
      {
         "id":"00609bf04bc536dc9ba8a001"
      },
      {
         "id":"00609bef37c536dc9ba86700",
         "fields":{
            "idt::o":"10609bf076241bfc043c6b00"
         }
      },
      {
         "id":"00609beefe241bfc043c1901",
         "fields":{
            "idt::o":"10609bef48241bfc043c2a00"
         }
      },
      {
         "id":"00609beea3241bfc04369a00",
         "fields":{
            "idt::o":"10609beed0241bfc0436a001"
         }
      },
      {
         "id":"00609bee5bc536dc9ba81101"
      },
      {
         "id":"00609bee04c536dc9ba7f000",
         "fields":{
            "idt::o":"10609bee18241bfc04369400"
         }
      },
      {
         "id":"00609bedbac536dc9ba7c601",
         "fields":{
            "idt::o":"10609bedfdc536dc9ba7ea00"
         }
      },
      {
         "id":"00609bed11c536dc9ba79c00"
      },
      {
         "id":"00609bebd8241bfc04368801"
      },
      {
         "id":"00609beaecc536dc9ba6c100"
      },
      {
         "id":"00609be513c536dc9ba57b01"
      },
      {
         "id":"00609be4ebc536dc9ba56600",
         "fields":{
            "idt::o":"10609be55bc536dc9ba58c00"
         }
      },
      {
         "id":"00609be37b241bfc04353c01",
         "fields":{
            "idt::o":"106080b9775f7b1b2c7efa00"
         }
      },
      {
         "id":"00609be073241bfc0434f300",
         "fields":{
            "idt::o":"10609be092241bfc0434f601"
         }
      },
      {
         "id":"00609bde31241bfc0434ca01",
         "fields":{
            "idt::o":"10609bde4d241bfc0434cd00"
         }
      },
      {
         "id":"00609bdb10c536dc9b9f7d00",
         "fields":{
            "idt::o":"10609bddbbc536dc9ba3da01"
         }
      },
      {
         "id":"00609bda97241bfc04347e01",
         "fields":{
            "idt::o":"10609bdabb241bfc04348500"
         }
      },
      {
         "id":"00609bd771c536dc9b9eaa00",
         "fields":{
            "idt::o":"10609bd7a5c536dc9b9eb601"
         }
      },
      {
         "id":"00609bd70ec536dc9b9e9a01"
      },
      {
         "id":"00609bd21ac536dc9b9d4f00",
         "fields":{
            "idt::o":"10609bd288241bfc0433c201"
         }
      },
      {
         "id":"00609bcecac536dc9b9cc401"
      },
      {
         "id":"00609bcab5241bfc0432a900",
         "fields":{
            "idt::o":"10609bcb00c536dc9b9c1401"
         }
      },
      {
         "id":"00609bca6d241bfc04329701"
      },
      {
         "id":"00609bc917c536dc9b9bda00"
      },
      {
         "id":"00609bc5c0c536dc9b99c801",
         "fields":{
            "idt::o":"10609bc610c536dc9b99cf00"
         }
      },
      {
         "id":"00609bc598241bfc04317e00",
         "fields":{
            "idt::o":"10609bc598241bfc04318100"
         }
      },
      {
         "id":"00609bc577241bfc04317501",
         "fields":{
            "idt::o":"10609bc577241bfc04317801"
         }
      },
      {
         "id":"00609bc4dac536dc9b99b300"
      },
      {
         "id":"00609bc41b241bfc04312d01"
      }
   ],
   "meta":{
      "total_contacts":3205,
      "total_organizations":0,
      "total_matches":3205,
      "total_subscribers":3119
   },
   "offset":50,
   "next_offset":100,
   "cursor_id":"00609ca377b2bdea4cbd4645",
   "has_more":true
}