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

Audiences

View as Markdown

Create audience

POST/platform/audiencesPlatform API
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–255

    Optional 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-Version and request is not applied again: it returns 200 with Idempotent-Replayed: true and the replay result described for this operation. Reusing the key for a different request returns 422 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 returns 410 resource_gone.

Body

  • namestringrequiredlength1–200

    Human-readable name for this resource.

  • sourcestring

    Defaults to csv with fileId, otherwise manual.

    Allowed valuescsvmanualapi
  • membersarray of objectmax items1000

    Members associated with this management create audience request.

    Show 2 child fields
  • fileIdstringlength1–512

    File id returned by the audience upload URL. UTF-8 CSV with a header row; comma, semicolon or tab separated.

  • mappingobject

    Structured mapping values for this management create audience request.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured 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`).
POST /platform/audiencescURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

POST/platform/audiences/from-campaignPlatform API
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–200

    Human-readable name for this resource.

  • campaignIdstring (uuid)required

    The campaign whose recipients are selected.

  • projectIdstring (uuid)

    Optional. When given, the campaign must belong to this project.

  • outcomestringrequired

    Specifies outcome for this schema.

    Allowed valuesdeliverednot_deliveredreadnot_readrepliednot_repliedfailed

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
POST /platform/audiences/from-campaigncURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

POST/platform/audiences/uploadsPlatform API
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
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
POST /platform/audiences/uploadscURL
Not available with the Test key. Use a team key or project token.
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 '{}'
Response
{
  "data": null
}

List audiences

GET/platform/audiencesPlatform API
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
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/audiencescURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audiences" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

List audience members

GET/platform/audiences/{listId}/membersPlatform API
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

  • listIdstringrequired

    Identifier for the list.

Query parameters

  • cursorstringlength1–256

    Specifies cursor for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 4 child fields
    • pageobjectrequired

      Specifies 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.
GET /platform/audiences/{listId}/memberscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audiences/<listId>/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "phone": "string",
      "variables": {},
      "createdAt": 0
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Get audience

GET/platform/audiences/{listId}Platform API
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

  • listIdstringrequired

    Identifier for the list.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/audiences/{listId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audiences/<listId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

Add audience members

POST/platform/audiences/{listId}/membersPlatform API
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

  • listIdstringrequired

    Identifier for the list.

Headers

  • Idempotency-Keystringlength1–255

    Optional 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-Version and request is not applied again: it returns 200 with Idempotent-Replayed: true and the replay result described for this operation. Reusing the key for a different request returns 422 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–1000

    At most 1,000 members per request.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured 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`).
POST /platform/audiences/{listId}/memberscURL
Not available with the Test key. Use a team key or project token.
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"
    }
  ]
}'
Response
{
  "data": {
    "listId": "00000000-0000-4000-8000-000000000000",
    "added": 0,
    "recipientCount": 0,
    "duplicateCount": 0,
    "invalidCount": 0,
    "invalidRows": [
      {
        "row": 1,
        "reason": "missing_phone"
      }
    ]
  }
}

Delete audience

DELETE/platform/audiences/{listId}Platform API
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

  • listIdstringrequired

    Identifier for the list.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
DELETE /platform/audiences/{listId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/audiences/<listId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

Delete audience member

DELETE/platform/audiences/{listId}/members/{phone}Platform API
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

  • listIdstringrequired

    Identifier for the list.

  • phonestringrequired

    Phone number in international format.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
DELETE /platform/audiences/{listId}/members/{phone}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/audiences/<listId>/members/<phone>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "removed": true,
    "listId": "00000000-0000-4000-8000-000000000000",
    "phone": "string",
    "recipientCount": 0
  }
}