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.
|
When |
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. |
|
The |
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|
Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:
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:
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:
{
"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.
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:
{
"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.
|
When |
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:
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:
{
"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!