Skip to content
Shortcut: /, ⌘K or Ctrl+K

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.

View as Markdown

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.

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.

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

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.

Shell
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.

Shell
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.

Shell
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#

RuleValue
Number formatInternational. Spaces, dots, hyphens and parentheses are ignored; a leading 00 is read as +; digits without + are read as already including the country code
Number length8 to 15 digits including the country code, and a possible length for that country
Variables per memberAt most 50
Variable nameStarts with a letter, digit or _, then up to 63 more characters from letters, digits, _, . and -
Variable valueA string, number or boolean, stored as a string of at most 1,024 characters
Members per requestAt most 1,000
Data rows per file importAt 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:

FieldMeaning
recipientCountMembers in the audience after the request
duplicateCountValid entries skipped because the number repeated in the request or is already in the audience
invalidCountEntries that failed validation
invalidRowsUp 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#

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

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

outcomeRecipients selected
deliveredTheir device confirmed delivery
not_deliveredSent, with no delivery confirmation
readRead the message
not_readSent and not read, including messages never delivered
repliedReplied to the message
not_repliedSent, and no reply was attributed to them
failedConfirmed 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.

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

FieldMeaning
recipientCountMembers in the new audience
matchedCountRecipients of the source campaign with that outcome
optedOutCountMatched recipients left out because the number is on the team's opt-out list
sourceCampaignId, outcomeWhat 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 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.

Shell
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 hoursResponse
Add members: same key, same credential, same Polymorfa-Version and same body200 with Idempotent-Replayed: true and the first request's counts. Nothing is written again
Create: same key, same credential, same Polymorfa-Version and same body200 with Idempotent-Replayed: true, the audience as it is now and the first request's import counts. Nothing is written again
Same key, different body422 idempotency_conflict
Sent while the first request is still runningWaits for the first request, then returns its result
After the first request failedRuns 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 and Opt-outs and STOP replies.

See also#