Retrieving data from a single person

Learn how to use the Ortto API to retrieve data from a single person in your Ortto account’s customer data platform (CDP) based on a unique field value of that person, such as their email address or their external ID.

Requests to retrieve data from a single person in your Ortto CDP are submitted as a single POST method call to the following URL:


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

which is the same endpoint used to retrieve people’s data.

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/).

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

Based on the person’s email address

cURL example

cURL example request to retrieve data from a single person in the Ortto CDP (based on the person’s email address)

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 '{
        "offset": 0, <3>
        "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"], <4> 
        "filter": { <5>
          "$str::is": {
            "field_id": "str::email",
            "value": "alex@example.com"
          }
        }
      }'

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 `offset` defines the point in the CDP from which people are retrieved, which in this case is from the first person’s record in the CDP. (This element is optional since its default value is `0`.)
4	The `fields` define which person fields' data is returned from the CDP for each person’s record.
5	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 the person’s record whose email address (`str::email`) matches the `value` specified is retrieved from the CDP.

This request generates a response example similar to the one below.

Node.js example

Node.js example of the same cURL request (described above) to retrieve data from a single person in the Ortto CDP (based on the person’s email address)

javascript
 const data = {
  "offset": 0, 
  "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"], 
  "filter": { 
    "$str::is": {
      "field_id": "str::email",
      "value": "alex@example.com"
    }
  }
};

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

Based on the person’s external ID

cURL example

cURL example request to retrieve data from a single person in the Ortto CDP (based on the person’s external ID)

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 '{
        "offset": 0, <3>
        "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"], <4> 
        "filter": { <5>
          "$str::is": {
            "field_id": "str::ei",
            "value": "c533532fe5d16c7d4fa4c7f0"
          }
        }
      }'

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 `offset` defines the point in the CDP from which people are retrieved, which in this case is from the first person’s record in the CDP. (This element is optional since its default value is `0`.)
4	The `fields` define which person fields' data is returned from the CDP for each person’s record.
5	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 the person’s record whose external ID (`str::ei`) matches the `value` specified is retrieved from the CDP.

This request generates a response example similar to the one below.

Node.js example

Node.js example of the same cURL request (described above) to retrieve data from a single person in the Ortto CDP (based on the person’s email address)

javascript
 const data = {
  "offset": 0, 
  "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"], 
  "filter": { 
    "$str::is": {
      "field_id": "str::ei",
      "value": "c533532fe5d16c7d4fa4c7f0"
    }
  }
};

request({
  url: 'https://api.ap3api.com/v1/person/get', 
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR-CUSTOM-API-KEY', 
    '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 email address examples, as well as cURL and Node.js external ID examples above, which retrieved select data (specified through fields in the request) for a single person’s record in an Ortto CDP.

Response payload example from the cURL or Node.js requests above

json
 {
   "contacts":[
      {
         "id":"0061b02b24f9b6f85dcb1e00",
         "fields":{
            "str::email":"alex@example.com",
            "str::first":"Alex"
         }
      }
   ],
   "meta":{
      "total_contacts":5,
      "total_organizations":0,
      "total_matches":1,
      "total_subscribers":0
   },
   "offset":0,
   "next_offset":1,
   "cursor_id":"0062452c630993474f058988",
   "has_more":false
}