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

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

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

shell
 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

javascript
 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

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

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

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

shell
 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:

json
 {
   "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
}