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

Audience profiles

View as Markdown

Create audience profile import

POST/platform/audience-profile-importsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Queues a bounded CSV import of customer-supplied team profiles. Exact CSV header names can be mapped to profile fields. At most one import is active per team. Files contain at most 10 MiB and 10,000 rows; the CSV is removed after completion or cancellation. The same replay key, file and mapping return the existing job. Requires beta enrollment.

Team keys require campaigns:manage. Project tokens are not accepted.

Body

  • replayKeystringrequiredlength1–128pattern^[A-Za-z0-9._:-]+$

    Specifies replay key for this schema.

  • csvBase64string (byte)requiredlength1–13981016

    UTF-8 CSV encoded as standard padded base64; decoded file at most 10 MiB and 10,000 data rows. The tags cell holds a JSON array of strings and the attributes cell a JSON object, quoted as CSV requires, for example +15550100001,"[""vip""]","{""city"":""Lisbon""}".

  • mappingobject

    Maps profile fields to exact CSV header names. Required when the CSV uses different headers; unmapped CSV columns are ignored.

    Show 8 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 13 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.
  • 409The request conflicts with the resource's current state.
  • 413Request body exceeds the endpoint limit.
POST /platform/audience-profile-importscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/audience-profile-imports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "replayKey": "string",
  "csvBase64": "string"
}'
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "state": "queued",
    "totalValid": 0,
    "invalidCount": 0,
    "invalidSamples": [
      {
        "row": 2,
        "reason": "string"
      }
    ],
    "conflictSamples": [
      {
        "row": 2,
        "reason": "quota"
      }
    ],
    "processedValid": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "conflictCount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "completedAt": 0
  }
}

List audience profiles

GET/platform/audience-profilesPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Lists customer-supplied profiles for the team with cursor pagination. Deleted profiles are omitted.

Team keys require campaigns:read. Project tokens are not accepted.

Query parameters

  • cursorstring (uuid)

    Specifies cursor for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • tagstringmin length1pattern^[^\u0000-\u001f\u007f]+$

    Only profiles that carry this exact tag.

    • UTF-8 size: At most 48 UTF-8 bytes

  • phonePrefixstringpattern^\+[0-9]{1,15}$

    Only profiles whose E.164 phone number starts with this prefix, such as +4479.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 8 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.
GET /platform/audience-profilescURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audience-profiles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "phone": "string",
      "revision": 1,
      "tags": [
        "string"
      ],
      "attributes": {},
      "provenance": {
        "source": "api",
        "reference": "string"
      },
      "createdAt": 0,
      "updatedAt": 0
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Get audience profile

GET/platform/audience-profiles/{phone}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Gets one customer-supplied profile by its E.164 phone. Deleted profiles return 404.

Team keys require campaigns:read. Project tokens are not accepted.

Path parameters

  • phonestringrequired

    Phone number in international format.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 8 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/audience-profiles/{phone}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audience-profiles/<phone>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "phone": "string",
    "revision": 1,
    "tags": [
      "string"
    ],
    "attributes": {},
    "provenance": {
      "source": "api",
      "reference": "string"
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}

Get audience profile import

GET/platform/audience-profile-imports/{jobId}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Returns aggregate counts and up to 20 row-number/reason samples. Raw phone numbers and custom values are not included. Reports expire 30 days after completion or cancellation.

Team keys require campaigns:read. Project tokens are not accepted.

Path parameters

  • jobIdstringrequired

    Identifier for the job.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 13 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/audience-profile-imports/{jobId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audience-profile-imports/<jobId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "state": "queued",
    "totalValid": 0,
    "invalidCount": 0,
    "invalidSamples": [
      {
        "row": 2,
        "reason": "string"
      }
    ],
    "conflictSamples": [
      {
        "row": 2,
        "reason": "quota"
      }
    ],
    "processedValid": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "conflictCount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "completedAt": 0
  }
}

Put audience profile

PUT/platform/audience-profiles/{phone}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Creates a bounded team profile, or replaces tags and attributes at the observed revision. A stale revision returns 409. To recreate a profile deleted in the last 30 days, send the revision the delete returned as expectedRevision; a put without it returns 409 with a message naming that revision. A consent assertion records the customer's statement; it does not clear an opt-out or authorize a send. This beta requires enrollment and release eligibility.

Team keys require campaigns:manage. Project tokens are not accepted.

Path parameters

  • phonestringrequired

    Phone number in international format.

Body

  • expectedRevisionintegermin1

    Required to edit or recreate a deleted profile; omit only for first creation.

  • tagsarray of stringrequiredmax items20item max length48

    Tags associated with this schema.

  • attributesobjectrequiredmax properties20

    Structured attributes values for this schema.

  • provenanceobject

    Structured provenance values for this schema.

    Show 2 child fields
  • consentobject

    Structured consent values for this schema.

    Show 5 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 8 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.
PUT /platform/audience-profiles/{phone}cURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/audience-profiles/<phone>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "string"
  ],
  "attributes": {}
}'
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "phone": "string",
    "revision": 1,
    "tags": [
      "string"
    ],
    "attributes": {},
    "provenance": {
      "source": "api",
      "reference": "string"
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}

Cancel audience profile import

DELETE/platform/audience-profile-imports/{jobId}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Stops the next batch and removes the CSV. Already committed profile edits remain. Cancellation and report reads remain available after beta withdrawal.

Team keys require campaigns:manage. Project tokens are not accepted.

Path parameters

  • jobIdstringrequired

    Identifier for the job.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 13 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/audience-profile-imports/{jobId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/audience-profile-imports/<jobId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "state": "queued",
    "totalValid": 0,
    "invalidCount": 0,
    "invalidSamples": [
      {
        "row": 2,
        "reason": "string"
      }
    ],
    "conflictSamples": [
      {
        "row": 2,
        "reason": "quota"
      }
    ],
    "processedValid": 0,
    "createdCount": 0,
    "updatedCount": 0,
    "conflictCount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "completedAt": 0
  }
}

Delete audience profile

DELETE/platform/audience-profiles/{phone}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Removes profile fields, consent assertions and reusable audience-list memberships at the observed revision, and clears the preview row of each audience the phone belonged to. Recipients already added to campaigns (including drafts), previously uploaded files and opt-outs are not changed. The phone's deletion record is kept for 30 days; revision is its revision. During that time, adding the phone to an audience returns 409, and recreating the profile requires expectedRevision set to this revision. Deletion remains available after beta withdrawal.

Team keys require campaigns:manage. Project tokens are not accepted.

Path parameters

  • phonestringrequired

    Phone number in international format.

Query parameters

  • expectedRevisionstringrequired

    The profile revision you last read. A different current revision returns 409.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 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.
DELETE /platform/audience-profiles/{phone}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/audience-profiles/<phone>?expectedRevision=<expectedRevision>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "deleted": true,
    "phone": "string",
    "revision": 2
  }
}