Audiences
Create audience
- Base URL
https://api.polymorfa.com- Required permission
campaigns:manage
Creates an audience from inline members (at most 1,000) or from an uploaded CSV file (fileId + mapping). Numbers are normalized to E.164 and repeated numbers are kept once. A file import accepts at most 100,000 data rows; a larger file is refused with 413 and must be split. The response reports how many rows were invalid, with up to 20 samples. recipientCount is the number of stored members; any client-supplied count is ignored. If your team deleted an audience profile for one of these numbers in the last 30 days, the request returns 409 naming the row (numbered as in invalidRows), and nothing is added.
Team keys require campaigns:manage. Project tokens are not accepted.
Headers
Idempotency-Keystringlength1–255Optional key, 1 to 255 bytes of UTF-8, that makes this request safe to retry for 24 hours. A retry with the same key, credential,
Polymorfa-Versionand request is not applied again: it returns200withIdempotent-Replayed: trueand the replay result described for this operation. Reusing the key for a different request returns422 idempotency_conflict. A retry sent while the original is still running waits for it and then returns its result. A request that failed left no record, so retrying it with the same key runs it again. Access to the resource is checked again on every retry. A replay returns the audience as it is now, with the original import counts. If the audience was deleted after the original request, a replay returns410 resource_gone.
Body
namestringrequiredlength1–200Human-readable name for this resource.
sourcestringDefaults to
csvwithfileId, otherwisemanual.Allowed valuescsvmanualapimembersarray of objectmax items1000Members associated with this management create audience request.
Show 2 child fields
fileIdstringlength1–512File id returned by the audience upload URL. UTF-8 CSV with a header row; comma, semicolon or tab separated.
mappingobjectStructured mapping values for this management create audience request.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 13 child fields
Show 4 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
409The request conflicts with the resource's current state.
410The requested retained payload is no longer available.
413Request body exceeds the endpoint limit.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/audiences" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"name": "string",
"source": "csv",
"recipientCount": 0,
"fileId": "string",
"columns": [
"string"
],
"sampleRow": {},
"mapping": {},
"createdAt": 0,
"updatedAt": 0,
"duplicateCount": 0,
"invalidCount": 0,
"invalidRows": [
{
"row": 1,
"reason": "missing_phone"
}
]
}
}Create audience from campaign
- Base URL
https://api.polymorfa.com- Required permission
campaigns:manage
Creates an audience from the recipients of a previous campaign that had one outcome, to send them a follow-up campaign. The members are a snapshot taken when the request runs: later receipts, reads or replies on the source campaign do not change the audience. Numbers on the team's opt-out list are left out and counted in optedOutCount; each member keeps the template variables it had on the source campaign. Outcomes: delivered (the device confirmed delivery), not_delivered (sent, with no delivery confirmation), read, not_read (sent and not read, including sends never delivered), replied, not_replied (sent and no reply was attributed), and failed (confirmed failed sends; sends whose outcome is uncertain, such as a timeout waiting for WhatsApp, are excluded). Read outcomes depend on the recipient's read receipts. 404 means the campaign is not in your team (or not in projectId when given); 409 means no recipient that is not opted out has the outcome, and nothing is created.
Team keys require campaigns:manage. Project tokens are not accepted.
Body
namestringrequiredlength1–200Human-readable name for this resource.
campaignIdstring (uuid)requiredThe campaign whose recipients are selected.
projectIdstring (uuid)Optional. When given, the campaign must belong to this project.
outcomestringrequiredSpecifies outcome for this schema.
Allowed valuesdeliverednot_deliveredreadnot_readrepliednot_repliedfailed
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 14 child fields
Show 3 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
409The request conflicts with the resource's current state.
curl -X POST "https://api.polymorfa.com/platform/audiences/from-campaign" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"campaignId": "00000000-0000-4000-8000-000000000000",
"outcome": "delivered"
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"name": "string",
"source": "campaign",
"recipientCount": 0,
"fileId": "string",
"columns": [
"string"
],
"sampleRow": {},
"mapping": {},
"createdAt": 0,
"updatedAt": 0,
"sourceCampaignId": "00000000-0000-4000-8000-000000000000",
"outcome": "delivered",
"matchedCount": 0,
"optedOutCount": 0
}
}Create audience upload url
- Base URL
https://api.polymorfa.com- Required permission
campaigns:manage
Public Management API. Team keys require campaigns:manage. Project tokens are not accepted.
Body
Responses
200Success
dataanyrequiredOperation result.
Show 3 headers
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
curl -X POST "https://api.polymorfa.com/platform/audiences/uploads" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{}'{
"data": null
}List audiences
- Base URL
https://api.polymorfa.com- Required permission
campaigns:read
Public Management API. Team keys require campaigns:read. Project tokens are not accepted.
Responses
200Success
dataanyrequiredOperation result.
Show 3 headers
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
curl "https://api.polymorfa.com/platform/audiences" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": null
}List audience members
- Base URL
https://api.polymorfa.com- Required permission
campaigns:read
Lists an audience's members in the order they were added, with cursor pagination.
Team keys require campaigns:read. Project tokens are not accepted.
Path parameters
listIdstringrequiredIdentifier for the list.
Query parameters
cursorstringlength1–256Specifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 4 child fields
pageobjectrequiredSpecifies page for this schema.
Show 2 child fields
Show 3 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
curl "https://api.polymorfa.com/platform/audiences/<listId>/members" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"phone": "string",
"variables": {},
"createdAt": 0
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}Get audience
- Base URL
https://api.polymorfa.com- Required permission
campaigns:read
Public Management API. Team keys require campaigns:read. Project tokens are not accepted.
Path parameters
listIdstringrequiredIdentifier for the list.
Responses
200Success
dataanyrequiredOperation result.
Show 3 headers
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
curl "https://api.polymorfa.com/platform/audiences/<listId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": null
}Add audience members
- Base URL
https://api.polymorfa.com- Required permission
campaigns:manage
Adds up to 1,000 members to an audience. A number already in the audience is skipped. Invalid entries are reported, not added. If your team deleted an audience profile for one of these numbers in the last 30 days, the request returns 409 naming the row (numbered as in invalidRows), and nothing is added.
Team keys require campaigns:manage. Project tokens are not accepted.
Path parameters
listIdstringrequiredIdentifier for the list.
Headers
Idempotency-Keystringlength1–255Optional key, 1 to 255 bytes of UTF-8, that makes this request safe to retry for 24 hours. A retry with the same key, credential,
Polymorfa-Versionand request is not applied again: it returns200withIdempotent-Replayed: trueand the replay result described for this operation. Reusing the key for a different request returns422 idempotency_conflict. A retry sent while the original is still running waits for it and then returns its result. A request that failed left no record, so retrying it with the same key runs it again. Access to the resource is checked again on every retry. A replay returns the original counts. The audience must still exist.
Body
membersarray of objectrequireditems1–1000At most 1,000 members per request.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 6 child fields
Show 4 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
409The request conflicts with the resource's current state.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/audiences/<listId>/members" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"members": [
{
"phone": "string"
}
]
}'{
"data": {
"listId": "00000000-0000-4000-8000-000000000000",
"added": 0,
"recipientCount": 0,
"duplicateCount": 0,
"invalidCount": 0,
"invalidRows": [
{
"row": 1,
"reason": "missing_phone"
}
]
}
}Delete audience
- Base URL
https://api.polymorfa.com- Required permission
campaigns:manage
Public Management API. Team keys require campaigns:manage. Project tokens are not accepted.
Path parameters
listIdstringrequiredIdentifier for the list.
Responses
200Success
dataanyrequiredOperation result.
Show 3 headers
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
curl -X DELETE "https://api.polymorfa.com/platform/audiences/<listId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": null
}Delete audience member
- Base URL
https://api.polymorfa.com- Required permission
campaigns:manage
Removes one member by phone number. The number is normalized the same way as on import. Campaigns that already launched keep the recipients they copied.
Team keys require campaigns:manage. Project tokens are not accepted.
Path parameters
listIdstringrequiredIdentifier for the list.
phonestringrequiredPhone number in international format.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 4 child fields
Show 3 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
curl -X DELETE "https://api.polymorfa.com/platform/audiences/<listId>/members/<phone>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"removed": true,
"listId": "00000000-0000-4000-8000-000000000000",
"phone": "string",
"recipientCount": 0
}
}