Audience segments
The audience segment object
Attributes
idstring (uuid)requiredIdentifier for this resource.
namestringrequiredlength1–100Human-readable name for this resource.
revisionintegerrequiredmin1Specifies revision for this management audience segment.
rulesobjectrequiredSpecifies rules for this management audience segment.
Show 2 child fields
createdAtintegerrequiredmin0Unix timestamp in milliseconds when this resource was created.
updatedAtintegerrequiredmin0Unix timestamp in milliseconds when this resource was last updated.
{
"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
- 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–100Human-readable name for this resource.
rulesobjectrequiredSpecifies rules for this schema.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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.
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
}
]
}
]
}
}'{
"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
- 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
cursorstringSpecifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 6 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.
curl "https://api.polymorfa.com/platform/audience-segments" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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
segmentIdstringrequiredIdentifier for the segment.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/audience-segments/<segmentId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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
segmentIdstringrequiredIdentifier for the segment.
Body
expectedRevisionintegerrequiredmin1Specifies expected revision for this schema.
namestringlength1–100Human-readable name for this resource.
rulesobjectSpecifies rules for this schema.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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.
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
}'{
"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
- 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
rulesobjectrequiredSpecifies rules for this schema.
Show 2 child fields
Responses
200Success
dataobjectrequiredStructured 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.
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
}
]
}
]
}
}'{
"data": {
"matchedCount": 0,
"optedOutCount": 0,
"consentWithheldCount": 0,
"eligibleCount": 0,
"sample": [
{
"phone": "string",
"tags": [
"string"
]
}
],
"evaluatedAt": 0
}
}Preview audience segment
- 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
segmentIdstringrequiredIdentifier for the segment.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/audience-segments/<segmentId>/preview" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"matchedCount": 0,
"optedOutCount": 0,
"consentWithheldCount": 0,
"eligibleCount": 0,
"sample": [
{
"phone": "string",
"tags": [
"string"
]
}
],
"evaluatedAt": 0,
"revision": 1
}
}Delete audience segment
- 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
segmentIdstringrequiredIdentifier for the segment.
Query parameters
expectedRevisionintegerrequiredrange1–9007199254740991Specifies expected revision for this query parameter.
Responses
200Success
dataobjectrequiredStructured 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.
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"{
"data": {
"deleted": true,
"id": "00000000-0000-4000-8000-000000000000"
}
}