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

Audience segments

View as Markdown

The audience segment object

Attributes

  • idstring (uuid)required

    Identifier for this resource.

  • namestringrequiredlength1–100

    Human-readable name for this resource.

  • revisionintegerrequiredmin1

    Specifies revision for this management audience segment.

  • rulesobjectrequired

    Specifies rules for this management audience segment.

    Show 2 child fields
  • createdAtintegerrequiredmin0

    Unix timestamp in milliseconds when this resource was created.

  • updatedAtintegerrequiredmin0

    Unix timestamp in milliseconds when this resource was last updated.

The audience segment object
{
  "id": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "revision": 1,
  "rules": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "negate": true,
        "conditions": [
          {
            "field": "tag",
            "operator": "contains",
            "value": null
          }
        ]
      }
    ]
  },
  "createdAt": 0,
  "updatedAt": 0
}

Create audience segment

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

Saves a named rule set over the team's audience profiles. A team holds at most 100 segments. Every campaign a rule names must belong to the team. Both audience betas, campaigns.audience-profiles and campaigns.segments, must be available; otherwise the request answers 403 feature_unavailable.

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

Body

  • namestringrequiredlength1–100

    Human-readable name for this resource.

  • rulesobjectrequired

    Specifies rules for this schema.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 6 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.
POST /platform/audience-segmentscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/audience-segments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "rules": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "conditions": [
          {
            "field": "tag",
            "operator": "contains",
            "value": null
          }
        ]
      }
    ]
  }
}'
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "revision": 1,
    "rules": {
      "match": "all",
      "groups": [
        {
          "match": "all",
          "conditions": [
            null
          ]
        }
      ]
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}

List audience segments

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

Lists the team's saved segments with cursor pagination. Reads stay available after beta withdrawal.

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

Query parameters

  • cursorstring

    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 6 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-segmentscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audience-segments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "revision": 1,
      "rules": {
        "match": "all",
        "groups": [
          {
            "match": "all",
            "conditions": [
              null
            ]
          }
        ]
      },
      "createdAt": 0,
      "updatedAt": 0
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Get audience segment

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

Returns one saved segment.

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

Path parameters

  • segmentIdstringrequired

    Identifier for the segment.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 6 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-segments/{segmentId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audience-segments/<segmentId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "revision": 1,
    "rules": {
      "match": "all",
      "groups": [
        {
          "match": "all",
          "conditions": [
            null
          ]
        }
      ]
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}

Update audience segment

PATCH/platform/audience-segments/{segmentId}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Replaces the name, the rules or both at the observed revision; a stale revision answers 409. A draft campaign that uses the segment evaluates the new rules when it launches. Campaigns already launched keep their recipients. Both audience betas, campaigns.audience-profiles and campaigns.segments, must be available; otherwise the request answers 403 feature_unavailable.

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

Path parameters

  • segmentIdstringrequired

    Identifier for the segment.

Body

  • expectedRevisionintegerrequiredmin1

    Specifies expected revision for this schema.

  • namestringlength1–100

    Human-readable name for this resource.

  • rulesobject

    Specifies rules for this schema.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 6 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.
PATCH /platform/audience-segments/{segmentId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PATCH "https://api.polymorfa.com/platform/audience-segments/<segmentId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedRevision": 1
}'
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "revision": 1,
    "rules": {
      "match": "all",
      "groups": [
        {
          "match": "all",
          "conditions": [
            null
          ]
        }
      ]
    },
    "createdAt": 0,
    "updatedAt": 0
  }
}

Preview audience segment rules

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

Evaluates unsaved rules now and returns counts and up to five masked matching profiles. Nothing is saved. A campaign evaluates its segment again when it launches, so counts can change. Both audience betas, campaigns.audience-profiles and campaigns.segments, must be available; otherwise the request answers 403 feature_unavailable.

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

Body

  • rulesobjectrequired

    Specifies rules for this schema.

    Show 2 child fields

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 6 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.
POST /platform/audience-segments/previewcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/audience-segments/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": {
    "match": "all",
    "groups": [
      {
        "match": "all",
        "conditions": [
          {
            "field": "tag",
            "operator": "contains",
            "value": null
          }
        ]
      }
    ]
  }
}'
Response
{
  "data": {
    "matchedCount": 0,
    "optedOutCount": 0,
    "consentWithheldCount": 0,
    "eligibleCount": 0,
    "sample": [
      {
        "phone": "string",
        "tags": [
          "string"
        ]
      }
    ],
    "evaluatedAt": 0
  }
}

Preview audience segment

GET/platform/audience-segments/{segmentId}/previewPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Evaluates the saved segment now and returns counts, up to five masked matching profiles and the evaluated revision. Both audience betas, campaigns.audience-profiles and campaigns.segments, must be available; otherwise the request answers 403 feature_unavailable.

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

Path parameters

  • segmentIdstringrequired

    Identifier for the segment.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 7 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.
GET /platform/audience-segments/{segmentId}/previewcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/audience-segments/<segmentId>/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "matchedCount": 0,
    "optedOutCount": 0,
    "consentWithheldCount": 0,
    "eligibleCount": 0,
    "sample": [
      {
        "phone": "string",
        "tags": [
          "string"
        ]
      }
    ],
    "evaluatedAt": 0,
    "revision": 1
  }
}

Delete audience segment

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

Deletes the segment at the observed revision. Answers 409 while an unlaunched draft campaign uses it as its audience. Launched campaigns keep their recipients and segmentSnapshot; their segmentId becomes null. Deletion stays available after beta withdrawal.

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

Path parameters

  • segmentIdstringrequired

    Identifier for the segment.

Query parameters

  • expectedRevisionintegerrequiredrange1–9007199254740991

    Specifies expected revision for this query parameter.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      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.
  • 409The request conflicts with the resource's current state.
DELETE /platform/audience-segments/{segmentId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/audience-segments/<segmentId>?expectedRevision=<expectedRevision>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "deleted": true,
    "id": "00000000-0000-4000-8000-000000000000"
  }
}