List recipients

Overview

See who's on a campaign's list, and whether each recipient's email address and phone number are valid.

Use this to check a list before launching or to see progress after.

You'll need the campaign_id.

Returns one entry per recipient, with totals and a data-quality summary for the whole list.

Prerequisites

A bearer token. See Authentication.
The campaign's id (campaignId).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/campaign/{campaignId}/audiences

Authentication

Partner or Account token

The campaign must belong to an account inside your own account tree; otherwise 403.
A campaign id that doesn't exist returns 404.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`campaignId`	path	integer	Yes	The campaign's id. Digits only.
`search_value`	query	string	No	Text to search for, up to 255 characters. Matches part of the value.
`search_field`	query	string	No	Where to search: `email`, `phone`, `customer_name`, `requestor_name`, `company`, or `all` (default) for all five.
`sort_field`	query	string	No	The field to sort by: `created_at` (default), `email`, `phone`, `customer_name` or `requestor_name`.
`sort_by`	query	string	No	`asc` or `desc` (either case). Default `desc`.
`page`	query	integer	No	The page to return, from `1`. Default `1`.
`limit`	query	integer	No	Recipients per page, `10`–`100`. Default `10`. Values below 10 are raised to 10; above 100 returns `422`.

Request body

None.

Request payload

None.

Response body

This response is not wrapped in an outer data object: status and data sit at the top level, with the paging fields in links and meta.

Field	Type	Description
`status`	string	`success`.
`data`	object	The recipients and the list summary.
`data.audiences`	array of objects	The recipients on this page, newest first by default. Test sends are included.
`data.audiences[].id`	integer	The recipient's id.
`data.audiences[].email`	string or null	The recipient's email address, or `null`.
`data.audiences[].phone`	string or null	The recipient's phone number, or `null`.
`data.audiences[].requestor_name`	string or null	Who requested the review, or `null`.
`data.audiences[].customer_name`	string or null	The recipient's name, or `null`.
`data.audiences[].company`	string or null	The recipient's company, or `null`.
`data.audiences[].validation_status`	string	`valid` when the email or the phone is valid, otherwise `invalid`.
`data.audiences[].is_email_valid`	string	`valid`, `invalid`, `duplicate`, `skipped`, `unsubscribed`, or `N/A` when there is no email.
`data.audiences[].is_phone_valid`	string	`valid`, `invalid`, `duplicate`, `skipped`, `unsubscribed`, or `N/A` when there is no phone.
`data.audiences[].is_test`	boolean	`true` for a test send.
`data.audiences[].contact_quality`	string	`excellent` (email and phone valid), `good` (one valid) or `poor` (neither).
`data.audiences[].created_at`	string	When the recipient was added (`Y-m-d H:i:s`).
`data.audiences[].updated_at`	string	When the recipient last changed (`Y-m-d H:i:s`).
`data.kpis`	object	Totals for the whole list. All but `total_test_audience` leave out test sends.
`data.kpis.total_audience`	integer	Recipients.
`data.kpis.total_valid_emails`	integer	Recipients with a valid email address.
`data.kpis.total_valid_phones`	integer	Recipients with a valid phone number.
`data.kpis.total_with_both_contacts`	integer	Recipients with both valid.
`data.kpis.total_invalid_emails`	integer	Recipients whose email is invalid or a duplicate.
`data.kpis.total_invalid_phones`	integer	Recipients whose phone is invalid or a duplicate.
`data.kpis.total_with_no_contacts`	integer	Recipients with neither a valid email nor a valid phone.
`data.kpis.total_kiosk_audience`	integer	Recipients added from a kiosk.
`data.kpis.total_test_audience`	integer	Test sends.
`data.kpis.email_validation_rate`	number	Percentage of recipients with a valid email address.
`data.kpis.phone_validation_rate`	number	Percentage of recipients with a valid phone number.
`data.kpis.both_contacts_rate`	number	Percentage of recipients with both valid.
`data.summary`	object	A data-quality summary of the list.
`data.summary.insights`	array of strings	Short notes on email and SMS reach, e.g. `Excellent email reach potential`. Empty when the list is empty.
`data.summary.data_quality_score`	object	An overall score for the list.
`data.summary.data_quality_score.score`	number	0–100, weighted 40% email rate, 40% phone rate, 20% both.
`data.summary.data_quality_score.grade`	string	`A+`, `A`, `B`, `C`, `D` or `F`.
`data.summary.data_quality_score.status`	string	`excellent` (70 or more), `good` (50 or more) or `needs_improvement`.
`data.campaign_info`	object	The campaign.
`data.campaign_info.id`	integer	The campaign's id.
`data.campaign_info.name`	string	The campaign's name.
`data.campaign_info.status`	string	The campaign's status.
`data.campaign_info.file_status`	string	Status of the uploaded recipient file: `pending`, `processing`, `completed` or `failed`.
`data.campaign_info.created_at`	string	When the campaign was created (`Y-m-d H:i:s`).
`data.campaign_info.updated_at`	string	When the campaign last changed (`Y-m-d H:i:s`).
`links`	object	URLs of the first, last, previous and next pages.
`links.first`	string	URL of the first page.
`links.last`	string	URL of the last page.
`links.prev`	string or null	URL of the previous page, or `null`.
`links.next`	string or null	URL of the next page, or `null`.
`meta`	object	Paging details.
`meta.current_page`	integer	The page returned.
`meta.from`	integer or null	Position of the first recipient on this page, or `null` when the page is empty.
`meta.last_page`	integer	The last page number.
`meta.links`	array of objects	Page links for a pager, each with `url`, `label`, `page` and `active`.
`meta.path`	string	The endpoint URL without the query string.
`meta.per_page`	integer	Recipients per page.
`meta.to`	integer or null	Position of the last recipient on this page, or `null` when the page is empty.
`meta.total`	integer	Recipients across all pages, including test sends.

Response payload

{
  "status": "success",
  "data": {
    "audiences": [
      {
        "id": 25,
        "email": "[email protected]",
        "phone": null,
        "requestor_name": null,
        "customer_name": "Jane Smith",
        "company": null,
        "validation_status": "valid",
        "is_email_valid": "valid",
        "is_phone_valid": "N/A",
        "is_test": false,
        "contact_quality": "good",
        "created_at": "2026-10-01 08:02:35",
        "updated_at": "2026-10-01 08:02:35"
      }
    ],
    "kpis": {
      "total_audience": 1,
      "total_valid_emails": 1,
      "total_valid_phones": 0,
      "total_with_both_contacts": 0,
      "total_invalid_emails": 0,
      "total_invalid_phones": 0,
      "total_with_no_contacts": 0,
      "total_kiosk_audience": 0,
      "total_test_audience": 0,
      "email_validation_rate": 100,
      "phone_validation_rate": 0,
      "both_contacts_rate": 0
    },
    "summary": {
      "insights": [
        "Excellent email reach potential",
        "Limited SMS campaign potential"
      ],
      "data_quality_score": {
        "score": 40,
        "grade": "F",
        "status": "needs_improvement"
      }
    },
    "campaign_info": {
      "id": 4823,
      "name": "Spring Review Campaign",
      "status": "draft",
      "file_status": "pending",
      "created_at": "2026-10-01 08:02:04",
      "updated_at": "2026-10-01 08:02:08"
    }
  },
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/audiences?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/audiences?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "page": null,
        "active": false
      },
      {
        "url": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/audiences?page=1",
        "label": "1",
        "page": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "page": null,
        "active": false
      }
    ],
    "path": "https://production-api.shoutaboutus.com/api/v1/campaign/4823/audiences",
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Campaign outside your account

{
  "message": "The selected campaign does not belong to your company.",
  "status": "error",
  "errors": []
}

404 Campaign not found

{
  "message": "Campaign not found",
  "status": "error",
  "errors": []
}

422 Invalid filter value

{
  "message": "The selected search field is invalid. (and 1 more error)",
  "errors": {
    "search_field": [
      "The selected search field is invalid."
    ],
    "sort_field": [
      "The selected sort field is invalid."
    ]
  }
}

Status	Meaning
`200`	A page of recipients, with totals for the whole list.
`401`	The token is missing, expired or invalid.
`403`	The campaign belongs to an account outside your tree.
`404`	No campaign has that id.
`422`	A filter value isn't allowed, or `limit` is above 100.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/campaign/4823/audiences?limit=10" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'