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 |
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!