Retrieving audience members and subscribers

You may wish to retrieve all of the contacts who are subscribed to a particular audience. To get all the members of an audience regardless of subscription status, you simply provide an audience_id to POST /person/get. This will return all audience members regardless of their subscription status. You can provide an additional filter key of audience_filter which will allow you to refine your results.

`audience_filter`	When `audience_id` provided to POST /person/get
subscribers	Audience members who can receive emails (both subscribed globally and not unsubscribed from this audience)
unsubscribed	Audience members who can’t receive emails (either unsubscribed globally or from this specific audience)
unsubscribed-from-audience	Get all people who are members of this audience, but who are unsubscribed from it for email.
email-subscribers	Get all audience members who are subscribed to this audience for email.
sms-subscribers	Get all audience members who are subscribed to this audience for SMS.

NOTE: The audience_id comes from the Ortto UI. You can find it by navigating to the audience you wish to reference and copying the ID from the URL. For example, if you are looking at an audience and the URL is https://ortto.app/myinstance/audiences/60a350243945d90a792f830c/performance?from=audiences-index&key=- then the audience_id is 60a350243945d90a792f830c.

Requests to retrieve audience members and subscribers in Ortto are submitted as a single POST method to the following URL:


 https://api.ap3api.com/v1/person/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/).

Getting all members of an audience

To see all members a particular audience you can specify audience_id on a POST /person/get request like so:

shell
 curl --request POST 'https://api.ap3api.com/v1/person/get' \
     --header 'X-Api-Key: YOUR-API-KEY-HERE' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "limit": 100,
      "sort_by_field_id": "str::last",
      "sort_order": "asc",
      "offset": 0,
      "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"],
      "audience_id": "60f8f39f073f8835fa829e3b"
    }'

Your response will look like this:

json
 {
  "contacts": [
    {
      "id": "00624536230993474f078a00",
      "fields": {
        "str::email": "chris@ortto.com",
        "str::first": "Chris",
        "str::last": "Sharkey"
      }
    },
    (....more contacts here)
  ],
  "meta":{
    "total_contacts": 101,
    "total_organizations": 0,
    "total_matches": 101,
    "total_subscribers": 101
  },
  "offset": 0,
  "next_offset": 100,
  "cursor_id": "00625f78453a0e7647768685",
  "has_more": true
}

If has_more is true, there are more pages of results and you can send the cursor_id and offset (with the value from next_offset) in subsequent requests to page through the results. See the next section for an example of how to do this.

Getting the second page of audience members

If your audience response has has_more set to true, it will also have a cursor_id and a next_offset. Here is an example of using that cursor_id and offset (with the value from next_offset) to get the second page of audience members.

shell
 curl --request POST 'https://api.ap3api.com/v1/person/get' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "limit": 100,
      "sort_by_field_id": "str::last",
      "sort_order": "asc",
      "offset": 0,
      "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"],
      "audience_id": "6241681069639ee210f8a29a",
      "offset": 100,
      "cursor_id": "00625f78453a0e7647768685"
    }'

Your response will look like this:

json
 {
  "contacts": [
    {
      "id": "00624536230993474f078a00",
      "fields": {
        "str::email": "chris@ortto.com",
        "str::first": "Chris",
        "str::last": "Sharkey"
      }
    }
  ],
  "meta": {
    "total_contacts": 101,
    "total_organizations": 0,
    "total_matches": 101,
    "total_subscribers": 101
  },
  "offset": 100,
  "next_offset": 101,
  "cursor_id": "006260b9abb19cae664dacab",
  "has_more": false
}

If has_more is false then there are no more results. If has_more` is true, you can repeat the process with the new cursor_id and next_offset to get the next page, and continue in this fashion until you have all of the results. Once has_more is false, there are no more results and your work is complete!

Using audience_filter to get specific results for the audience

By providing an audience_filter with one of the following values, you can get specific members of the audience based on their subscription status.

`audience_filter`	When `audience_id` provided to POST /person/get
subscribers	Audience members who can receive emails (both subscribed globally and not unsubscribed from this audience)
unsubscribed	Audience members who can’t receive emails (either unsubscribed globally or from this specific audience)
unsubscribed-from-audience	Get all people who are members of this audience, but who are unsubscribed from it for email.
email-subscribers	Get all audience members who are subscribed to this audience for email.
sms-subscribers	Get all audience members who are subscribed to this audience for SMS.

In the below example, we retrieve all subscribers for this audience:

shell
 curl --request POST 'https://api.ap3api.com/v1/person/get' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "limit": 100,
      "sort_by_field_id": "str::last",
      "sort_order": "asc",
      "offset": 0,
      "fields": ["str::first", "str::last", "str::email", "str:cm:job-title"],
      "audience_id": "6241681069639ee210f8a29a",
      "audience_filter": "subscribers"
    }'

Your response will look like this:

json
 {
  "contacts": [
    {
      "id": "00624536230993474f078a00",
      "fields": {
        "str::email": "chris@ortto.com",
        "str::first": "Chris",
        "str::last": "Sharkey"
      }
    }
  ],
  "meta": {
    "total_contacts": 101,
    "total_organizations": 0,
    "total_matches": 101,
    "total_subscribers": 101
  },
  "offset": 100,
  "next_offset": 101,
  "cursor_id": "006260b9abb19cae664dacab",
  "has_more": false
}

If has_more is false then there are no more results. If has_more is true, you can repeat the process with the new cursor_id and next_offset (as offset) to get the next page, and continue in this fashion until you have all of the results. Once has_more is false, there are no more results and your work is complete!