List audiences (recipients)

Overview

Get the paginated, searchable, sortable list of audience recipients for a campaign, plus aggregate validation KPIs, a quality summary, and basic campaign info.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.
• The campaignId of the record you are targeting.

Base URL

Endpoint

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

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• When the campaign has a company_id, it is scoped in-controller. This matches the caller's person.company_id against that company or its parent/grandparent.

• Partner- and Account-tier users inside the campaign's company tree may read it.

• Returns 404 if the campaign is not found.

• Returns 403 if it belongs to another company.

Rate limit

• No rate limit.

Path parameters

Query parameters

• Query: page (integer, optional) — page number, min:1.
• Query: limit (integer, optional) — page size, 10–100 (values below 10 are raised to 10), default 10.
• Query: search_value (string, optional) — max:255; substring match.
• Query: search_field (string, optional) — one of email, phone, customer_name, requestor_name, company, all (default all searches across all five).
• Query: sort_by (string, optional) — asc or desc (case-insensitive), default desc.
• Query: sort_field (string, optional) — one of created_at, email, phone, customer_name, requestor_name; default created_at.

Response

• data.audiences:
• id (integer)
• email (string|null)
• phone (string|null)
• requestor_name (string|null)
• customer_name (string|null)
• company (string|null)
• validation_status (string)
• is_email_valid (string) — e.g. valid / invalid / duplicate
• is_phone_valid (string) — e.g. valid / invalid / duplicate
• is_test (bool)
• contact_quality (string) — derived: excellent / good / poor
• created_at (string Y-m-d H:i:s | null)
• updated_at (string Y-m-d H:i:s | null)
• data.kpis (object) — total_audience, total_valid_emails, total_valid_phones, total_with_both_contacts, total_invalid_emails, total_invalid_phones, total_with_no_contacts, total_kiosk_audience, total_test_audience (ints; all but total_test_audience exclude is_test), plus email_validation_rate, phone_validation_rate, both_contacts_rate (floats, %).
• data.summary (object) — insights (array of strings) and data_quality_score{ score (float), grade (string A+.F), status (excellent|good|needs_improvement) }.
• data.campaign_info (object) — id, name, status, file_status (= request_file_status), created_at, updated_at.

Note: this endpoint does NOT use the page rule for slicing beyond the default page query-parameter resolution. Pagination metadata (links, meta) is merged at the top level of the response, beside status and data; data.audiences itself is a plain array of rows.

200 Success · 200

{
  "status": "success",
  "data": {
    "audiences": [
      {
        "id": 101,
        "email": "[email protected]",
        "phone": "+15551234567",
        "requestor_name": "Store Manager",
        "customer_name": "John Doe",
        "company": "Acme Co",
        "validation_status": "validated",
        "is_email_valid": "valid",
        "is_phone_valid": "valid",
        "is_test": false,
        "contact_quality": "excellent",
        "created_at": "2026-06-25 10:14:02",
        "updated_at": "2026-06-25 10:14:02"
      }
    ],
    "kpis": {
      "total_audience": 67,
      "total_valid_emails": 52,
      "total_valid_phones": 43,
      "total_with_both_contacts": 38,
      "total_invalid_emails": 15,
      "total_invalid_phones": 24,
      "total_with_no_contacts": 6,
      "total_kiosk_audience": 10,
      "total_test_audience": 5,
      "email_validation_rate": 77.61,
      "phone_validation_rate": 64.18,
      "both_contacts_rate": 56.72
    },
    "summary": {
      "insights": ["Good email reach potential", "Moderate SMS campaign potential"],
      "data_quality_score": { "score": 67.46, "grade": "C", "status": "good" }
    },
    "campaign_info": {
      "id": 1,
      "name": "Summer Campaign 2024",
      "status": "draft",
      "file_status": "completed",
      "created_at": "2026-06-20 08:00:00",
      "updated_at": "2026-06-25 10:14:02"
    }
  },
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/campaign/55/audiences?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/campaign/55/audiences?page=3",
    "prev": null,
    "next": "https://production-api.shoutaboutus.com/api/v1/campaign/55/audiences?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://production-api.shoutaboutus.com/api/v1/campaign/55/audiences",
    "per_page": 10,
    "to": 10,
    "total": 24
  }
}

Errors

Example request

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