# Build an audience

> Create a reusable list of numbers and template variables from inline members or a CSV file, then keep it up to date.

An audience is a list of phone numbers, each with its own template variables,
that belongs to your team. Any campaign in any project of that team can use it.
Polymorfa stores the members, counts them, and copies them into a campaign when
the campaign launches.

Audiences are a team-level resource. Use a team key: `campaigns:read` to
read, `campaigns:manage` to change. Project tokens are refused on every
audience route.

To keep customer-supplied attributes and consent assertions by phone number,
see [Manage audience profiles](https://docs.polymorfa.com/campaigns/audience-profiles).

## Create an audience

**Console:**

1. Open **Campaigns**, then **Audiences**, and select **Upload CSV**.
2. Choose a UTF-8 CSV file with a header row.
3. Under **Map columns**, set one column's role to **Phone** and each column
   you want in messages to **Variable**, with its variable name. Set other
   columns to **Ignore**.
4. Enter a **List name** and select **Save list**.

The **Audiences** table shows each list's source, recipients and columns. To
remove one, open its row actions and select **Delete list**.

**API:**

Send up to 1,000 members in the request body.

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/audiences" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "September launch",
    "members": [
      { "phone": "+14155550100", "variables": { "first_name": "Ada", "plan": "pro" } },
      { "phone": "+442071838750", "variables": { "first_name": "Alan" } }
    ]
  }'
```

```typescript TypeScript
const audience = await platform.audiences.create({
  name: "September launch",
  members: [
    { phone: "+14155550100", variables: { first_name: "Ada", plan: "pro" } },
    { phone: "+442071838750", variables: { first_name: "Alan" } },
  ],
});

console.log(audience.data.data.id, audience.data.data.invalidRows);
```

*TypeScript:*

Audiences use the team client.

The response returns the audience and what the import did with your input:

```json
{
  "data": {
    "id": "3b2f0c4e-6c1a-4a9b-9a53-6b7c9d0e1f22",
    "name": "September launch",
    "source": "manual",
    "recipientCount": 2,
    "duplicateCount": 0,
    "invalidCount": 0,
    "invalidRows": []
  }
}
```

`recipientCount` is the number of members Polymorfa stored. A count you send in
the request is ignored. To import a file through the API, see
[Import a CSV file](#import-a-csv-file).

## Import a CSV file

Importing a file takes three requests: ask for an upload URL, upload the file,
then create the audience from the stored file.

Ask for an upload URL. It is single use and expires shortly after it is issued.

```bash
curl -X POST "https://api.polymorfa.com/platform/audiences/uploads" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

Upload the file to that URL. The response returns `storageId`.

```bash
curl -X POST "$UPLOAD_URL" \
  -H "Content-Type: text/csv" \
  --data-binary @contacts.csv
```

Create the audience from the stored file, passing `storageId` as `fileId` and
naming the columns.

```bash
curl -X POST "https://api.polymorfa.com/platform/audiences" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "September launch",
    "fileId": "'"$STORAGE_ID"'",
    "mapping": {
      "phone": "Mobile",
      "variables": { "first_name": "First name", "plan": "Plan" }
    }
  }'
```

`mapping.phone` names the column that holds the number. `mapping.variables`
maps each template variable name to the column that supplies it. Column names
match exactly first, then without regard to letter case.

Polymorfa reads the file on the server. The file must be UTF-8 and have a header
row. The separator is detected from the header line: comma, semicolon or tab,
and comma when the line is ambiguous. Quoted fields, doubled quotes inside a
quoted field, line breaks inside a quoted field, and LF, CRLF or CR line endings
are all read correctly. Blank lines are ignored.

Send either `members` or `fileId` with `mapping`. A request carrying both is
refused.

## Number and variable rules

| Rule | Value |
| --- | --- |
| Number format | International. Spaces, dots, hyphens and parentheses are ignored; a leading `00` is read as `+`; digits without `+` are read as already including the country code |
| Number length | 8 to 15 digits including the country code, and a possible length for that country |
| Variables per member | At most 50 |
| Variable name | Starts with a letter, digit or `_`, then up to 63 more characters from letters, digits, `_`, `.` and `-` |
| Variable value | A string, number or boolean, stored as a string of at most 1,024 characters |
| Members per request | At most 1,000 |
| Data rows per file import | At most 100,000 |

A national number with no country code cannot be resolved and is reported as
invalid. A file with more than 100,000 data rows is refused with `413`: split it
into smaller files and import each one.

## Read what the import rejected

Every create and append reports the rows it did not store, so you can fix and
resend only those:

| Field | Meaning |
| --- | --- |
| `recipientCount` | Members in the audience after the request |
| `duplicateCount` | Valid entries skipped because the number repeated in the request or is already in the audience |
| `invalidCount` | Entries that failed validation |
| `invalidRows` | Up to 20 samples, each with `row` and `reason` |

`reason` is `missing_phone`, `invalid_phone`, `invalid_variables` or
`invalid_entry`. For inline members, `row` is the 1-based position in the array.
For a file, `row` is the spreadsheet row number, where the header is row 1.

## Keep an audience up to date

```bash cURL
# Add up to 1,000 members
curl -X POST "https://api.polymorfa.com/platform/audiences/$LIST_ID/members" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "members": [{ "phone": "+14155550101", "variables": { "first_name": "Grace" } }] }'

# Page through members in the order they were added
curl "https://api.polymorfa.com/platform/audiences/$LIST_ID/members?limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# Remove one member
curl -X DELETE "https://api.polymorfa.com/platform/audiences/$LIST_ID/members/%2B14155550101" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
await platform.audiences.addMembers("<audience-id>", {
  members: [{ phone: "+14155550101", variables: { first_name: "Grace" } }],
});
```

*TypeScript:*

Page through members with `platform.audiences.listMembers(audienceId, { cursor })`,
passing `page.nextCursor` from the previous page.

Member listing is cursor-paginated: `limit` is 1 to 100 and defaults to 25, and
`page.nextCursor` carries the next page until `page.hasMore` is `false`.
Adding a number that is already a member skips it and reports it in
`duplicateCount`. Removing a member changes the audience only. A campaign that
already launched keeps the recipients it copied.

Duplicating a campaign linked to an audience creates a draft with that same
audience. The copy takes the audience's members when it launches, including
membership changes since the original launch. A campaign without an audience
copies its recipients into the new draft.

## Retarget a previous campaign

Build an audience from the recipients of a campaign you already sent, filtered
by what happened to them, then send those people a follow-up campaign.

**Console:**

Open the launched campaign, then select **Retarget…** in its actions menu.
Choose the outcome, name the audience and create it.

**API:**

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/audiences/from-campaign" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring launch: did not read",
    "campaignId": "'"$CAMPAIGN_ID"'",
    "outcome": "not_read"
  }'
```

```typescript TypeScript
const followUp = await platform.audiences.createFromCampaign({
  name: "Spring launch: did not read",
  campaignId: "<campaign-id>",
  outcome: "not_read",
});
console.log(followUp.data.data.recipientCount, followUp.data.data.optedOutCount);
```

*TypeScript:*

The SDK sends this request once. After a lost response, list your audiences
before you create another.

| `outcome` | Recipients selected |
| --- | --- |
| `delivered` | Their device confirmed delivery |
| `not_delivered` | Sent, with no delivery confirmation |
| `read` | Read the message |
| `not_read` | Sent and not read, including messages never delivered |
| `replied` | Replied to the message |
| `not_replied` | Sent, and no reply was attributed to them |
| `failed` | Confirmed failed sends; uncertain delivery and older ambiguous outcomes are excluded |

Read outcomes depend on the recipient's read receipts: a recipient who turned
them off is never `read`. Replies are attributed the same way as in
[campaign analytics](https://docs.polymorfa.com/campaigns/send#follow-the-send).

The response is the new audience, with `source` set to `campaign`, plus:

| Field | Meaning |
| --- | --- |
| `recipientCount` | Members in the new audience |
| `matchedCount` | Recipients of the source campaign with that outcome |
| `optedOutCount` | Matched recipients left out because the number is on the team's opt-out list |
| `sourceCampaignId`, `outcome` | What the audience was built from |

The audience is a snapshot taken when the request runs. Receipts, reads and
replies that arrive later do not change it; create a new audience to pick them
up. Each member keeps the template variables it had on the source campaign.
Numbers on the opt-out list are left out now, and any number that opts out
before the follow-up launches is still skipped at launch. A number whose
[audience profile](https://docs.polymorfa.com/campaigns/audience-profiles) was deleted in the last
30 days is left out too.

`projectId` is optional. When you send it, the campaign must belong to that
project. The request needs a team key with `campaigns:manage`, like other
audience writes. `404` means the campaign is not in your team (or not in
`projectId`). `409` means no recipient outside the opt-out list has that
outcome, and nothing is created.

## Retry safely

Creating an audience and adding members accept an `Idempotency-Key` header.
Send one so that a retry after a timeout or a lost response does not create a
second audience or report the first request's members as duplicates.

```bash
curl -X POST "https://api.polymorfa.com/platform/audiences/$LIST_ID/members" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2026-09-24-batch-7" \
  -d '{ "members": [{ "phone": "+14155550102" }] }'
```

| Retry within 24 hours | Response |
| --- | --- |
| Add members: same key, same credential, same `Polymorfa-Version` and same body | `200` with `Idempotent-Replayed: true` and the first request's counts. Nothing is written again |
| Create: same key, same credential, same `Polymorfa-Version` and same body | `200` with `Idempotent-Replayed: true`, the audience as it is now and the first request's import counts. Nothing is written again |
| Same key, different body | `422 idempotency_conflict` |
| Sent while the first request is still running | Waits for the first request, then returns its result |
| After the first request failed | Runs again. A failed request leaves no record of the key |

A replayed append returns the counts from the first request, not the
audience's current size. A replayed create returns the audience as it is now,
with the first request's `duplicateCount`, `invalidCount` and `invalidRows`. If
that audience was deleted, the retry returns `410 resource_gone`. Each
retry checks your access again, so a retry for a deleted audience, or with a
credential that lost access, fails. Keys are scoped to the credential that sent
them.

## Use the audience in a campaign

Set `recipientListId` on the campaign. Its members are copied into the campaign
when the campaign launches, numbers on the team's opt-out list are skipped, and
`recipientCount` is set from the rows that were actually created. See
[Send a campaign](https://docs.polymorfa.com/campaigns/send) and
[Opt-outs and STOP replies](https://docs.polymorfa.com/campaigns/opt-outs).

## See also

- [Save an audience segment](https://docs.polymorfa.com/campaigns/segments)
- [Manage audience profiles](https://docs.polymorfa.com/campaigns/audience-profiles)
- [Audience API reference](https://docs.polymorfa.com/api/audiences/create-audience)
