BanSafe
The BanSafe number object
Attributes
sessionIdstring (uuid)requiredIdentifier of the connected Polymorfa session.
sessionstringrequiredIdentifier of the connected Polymorfa session.
phoneNumberstringrequiredPhone number in international format.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
healthnumberrequirednullablerange0–100Estimate of present account Health. Higher is healthier. Read healthSource, healthReliability, and healthFeatureCoverage with it.
bandstringrequiredSpecifies band for this management ban safe number.
Allowed valuesgoodfairpoorfailingunknownhealthSourcestringrequiredEstimator family. rules_v1 is deterministic; unavailable carries no numeric Health.
Allowed valuesrules_v1ml_modelunavailablehealthEstimatorVersionstringrequirednullableVersion of the estimator that produced Health.
healthModelVersionstringrequirednullableLearned-model artifact version. Null for rules_v1.
healthEvaluatedAtstring (date-time)requirednullableTimestamp for health evaluated at.
healthFeatureCoveragenumberrequirednullablerange0–1Specifies health feature coverage for this management ban safe number.
healthReliabilitystringrequiredSupport category, not a confidence score.
Allowed valuesrules_basedvalidatedunavailablehealthUnavailableReasonstringrequirednullableSpecifies health unavailable reason for this management ban safe number.
Allowed valuesno_active_modelinvalid_active_modelinsufficient_fresh_featureshealthProbabilitiesobjectrequirednullableSpecifies health probabilities for this management ban safe number.
Show 4 child fields
mostLikelyHealthStatestringrequirednullableSpecifies most likely health state for this management ban safe number.
Allowed valueshealthylimitedrestrictedbannedhealthExplanationobjectrequirednullableSpecifies health explanation for this management ban safe number.
Show 4 child fields
observedAccountStateobjectrequirednullableSpecifies observed account state for this management ban safe number.
Show 3 child fields
enforcementobjectrequirednullableSpecifies enforcement for this management ban safe number.
Show 15 child fields
{
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"health": 0,
"band": "good",
"healthSource": "rules_v1",
"healthEstimatorVersion": "string",
"healthModelVersion": "string",
"healthEvaluatedAt": "2026-09-22T12:00:00Z",
"healthFeatureCoverage": 0,
"healthReliability": "rules_based",
"healthUnavailableReason": "no_active_model",
"healthProbabilities": {
"healthy": 0,
"limited": 0,
"restricted": 0,
"banned": 0
},
"mostLikelyHealthState": "healthy",
"healthExplanation": {
"penalties": {
"conduct": 0,
"delivery": 0,
"connection": 0,
"restriction": 0,
"total": 0
},
"factors": [
{
"group": "direct_condition",
"key": "observed_limited",
"penalty": 0,
"observedValue": 0,
"sampleSize": 0
}
],
"measuredGroups": [
"direct_condition"
],
"missingGroups": [
"direct_condition"
]
},
"observedAccountState": {
"state": "healthy",
"observedAt": "2026-09-22T12:00:00Z",
"source": "account_check"
},
"enforcement": {
"rung": "none",
"previousRung": "none",
"teamFloor": "none",
"reason": "string",
"source": "automatic",
"throughputPerMinute": 0,
"blocksUnsolicited": true,
"suspended": true,
"startedAt": "2026-09-22T12:00:00Z",
"eligibleLiftAt": "2026-09-22T12:00:00Z",
"exitProgress": 0,
"blockingFindings": [
"string"
],
"operatorHold": true,
"appealState": "none",
"state": "applied"
}
}The BanSafe incident object
Attributes
idstring (uuid)requiredIdentifier for this resource.
sessionIdstring (uuid)requiredIdentifier of the connected Polymorfa session.
sessionstringrequiredIdentifier of the connected Polymorfa session.
phoneNumberstringrequiredPhone number in international format.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
kindstringrequiredKind discriminator for this object.
Allowed valuescap_warningcap_reachedtimelocktemporary_banpermanent_banconnect_blockedcustomer_reportsourcestringrequiredSpecifies source for this management ban safe incident.
Allowed valuesruntimecustomerresolutionstringrequiredSpecifies resolution for this management ban safe incident.
ambiguousbooleanrequiredWhether ambiguous.
startedAtstring (date-time)requiredTimestamp for started at.
endsAtstring (date-time)requirednullableTimestamp for ends at.
closedAtstring (date-time)requirednullableTimestamp for closed at.
closedBystringrequirednullableSpecifies closed by for this management ban safe incident.
claimIdstring (uuid)requirednullableIdentifier for the claim.
notestringrequirednullablemax length500Specifies note for this management ban safe incident.
reportedBystringrequirednullableSpecifies reported by for this management ban safe incident.
createdAtstring (date-time)requiredISO 8601 timestamp when this resource was created.
{
"id": "00000000-0000-4000-8000-000000000000",
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"kind": "cap_warning",
"source": "runtime",
"resolution": "string",
"ambiguous": true,
"startedAt": "2026-09-22T12:00:00Z",
"endsAt": "2026-09-22T12:00:00Z",
"closedAt": "2026-09-22T12:00:00Z",
"closedBy": "string",
"claimId": "00000000-0000-4000-8000-000000000000",
"note": "string",
"reportedBy": "string",
"createdAt": "2026-09-22T12:00:00Z"
}The health rule object
Attributes
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
versionintegerrequiredmin0Specifies version for this native project health policy.
enabledbooleanrequiredWhether this feature is enabled.
thresholdintegerrequiredrange0–100Specifies threshold for this native project health policy.
sessionActionstringrequiredSpecifies session action for this native project health policy.
Allowed valuesnonestopslow_downlog_outslowDownMpsnumberrequirednullablegreater than0Specifies slow down mps for this native project health policy.
emailNotificationbooleanrequiredWhether email notification.
webhookNotificationbooleanrequiredWhether webhook notification.
integrationsobjectrequiredStructured integrations values for this native project health policy.
Show 2 child fields
{
"projectId": "00000000-0000-4000-8000-000000000000",
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true,
"integrations": {
"emailConfigured": true,
"webhookConfigured": true
}
}Create ban safe incident
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Records that WhatsApp restricted or banned one of your numbers. Send the same Idempotency-Key to retry safely for the same number; a repeat returns the original report. Reusing the key for a different number returns 422 bansafe_incident_idempotency_scope_conflict.
Requires sessions:manage. Project tokens only access resources in their own project.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
sessionstringrequiredlength1–256Identifier of the connected Polymorfa session.
occurredAtstring (date-time)Timestamp for occurred at.
notestringmax length500Specifies note for this management report ban safe incident input.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 5 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.
422`bansafe_incident_idempotency_scope_conflict`: this key was already used to report a different number. Use a different key only for a different report.
curl -X POST "https://api.polymorfa.com/platform/bansafe/incidents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>" \
-H "Content-Type: application/json" \
-d '{
"session": "string"
}'{
"data": {
"incidentId": "00000000-0000-4000-8000-000000000000",
"created": true,
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"occurredAt": "2026-09-22T12:00:00Z"
}
}List ban safe health
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists present Health, findings counts, and the active Polymorfa restriction for every number in one project. Health is a 0 to 100 estimate from rules v1 or a validated learned model. It remains null until enough fresh evidence is available.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
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 18 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/bansafe/health" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"health": 0,
"band": "good",
"healthSource": "rules_v1",
"healthEstimatorVersion": "string",
"healthModelVersion": "string",
"healthEvaluatedAt": "2026-09-22T12:00:00Z",
"healthFeatureCoverage": 0,
"healthReliability": "rules_based",
"healthUnavailableReason": "no_active_model",
"healthProbabilities": {
"healthy": 0,
"limited": 0,
"restricted": 0,
"banned": 0
},
"mostLikelyHealthState": "healthy",
"healthExplanation": {
"penalties": {
"conduct": 0,
"delivery": 0,
"connection": 0,
"restriction": 0,
"total": 0
},
"factors": [
{
"group": "direct_condition",
"key": "observed_limited",
"penalty": 0,
"observedValue": 0,
"sampleSize": 0
}
],
"measuredGroups": [
"direct_condition"
],
"missingGroups": [
"direct_condition"
]
},
"observedAccountState": {
"state": "healthy",
"observedAt": "2026-09-22T12:00:00Z",
"source": "account_check"
},
"enforcement": {
"rung": "none",
"previousRung": "none",
"teamFloor": "none",
"reason": "string",
"source": "automatic",
"throughputPerMinute": 0,
"blocksUnsolicited": true,
"suspended": true,
"startedAt": "2026-09-22T12:00:00Z",
"eligibleLiftAt": "2026-09-22T12:00:00Z",
"exitProgress": 0,
"blockingFindings": [
"string"
],
"operatorHold": true,
"appealState": "none",
"state": "applied"
}
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe health history
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns the newest Health evaluations since the requested date, up to the limit, ordered oldest to newest. Each point carries its estimator source and version, evidence coverage, reliability, and availability reason.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Query parameters
sincestring (date-time)Specifies since for this query parameter.
limitintegerrange1–720Specifies limit for this query parameter.
Default720
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/bansafe/health/<session>/history" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"points": [
{
"health": 0,
"band": "good",
"healthSource": "rules_v1",
"healthEstimatorVersion": "string",
"healthModelVersion": "string",
"healthEvaluatedAt": "2026-09-22T12:00:00Z",
"healthFeatureCoverage": 0,
"healthReliability": "rules_based",
"healthUnavailableReason": "no_active_model",
"healthProbabilities": {
"healthy": 0,
"limited": 0,
"restricted": 0,
"banned": 0
},
"mostLikelyHealthState": "healthy",
"healthExplanation": {
"penalties": {
"conduct": 0,
"delivery": 0,
"connection": 0,
"restriction": 0,
"total": 0
},
"factors": [
{
"group": "direct_condition",
"key": "observed_limited",
"penalty": null,
"observedValue": null,
"sampleSize": null
}
],
"measuredGroups": [
"direct_condition"
],
"missingGroups": [
"direct_condition"
]
},
"observedAccountState": {
"state": "healthy",
"observedAt": "2026-09-22T12:00:00Z",
"source": "account_check"
}
}
]
}
}List ban safe signals
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists the bounded numeric, boolean, enum, histogram, and error-code aggregate signals that BanSafe can return. The catalogue contains no message content, recipient identifiers, or raw telemetry records.
Requires sessions:read. Project tokens only access resources in their own project.
Responses
200Success
dataarray of objectrequiredStructured 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/bansafe/signals" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"key": "string",
"label": "string",
"group": "string",
"kind": "number",
"unit": "count",
"description": "string"
}
]
}List ban safe telemetry history
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns the newest supported telemetry snapshots for one number. Signals are fixed-schema safe aggregates with explicit measured state; raw records and identifiers inside them are not returned.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Query parameters
sincestring (date-time)Specifies since for this query parameter.
untilstring (date-time)Specifies until for this query parameter.
cursorstringSpecifies cursor for this query parameter.
limitintegerrange1–50Specifies limit for this query parameter.
Default10
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.
404The requested resource was not found inside the authenticated team or project scope.
curl "https://api.polymorfa.com/platform/bansafe/telemetry/<session>/history" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"bucketStart": "2026-09-22T12:00:00Z",
"flushedAt": "2026-09-22T12:00:00Z",
"receivedAt": "2026-09-22T12:00:00Z",
"partial": true,
"recordVersion": 0,
"signals": [
{
"key": "string",
"label": "string",
"group": "string",
"kind": "number",
"unit": "count",
"description": "string",
"measured": true,
"value": 0,
"sampleSize": 0,
"codes": [
{
"code": null,
"count": null
}
]
}
]
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe collection
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists telemetry collection freshness for the numbers in one project. Status is derived from ingested records and does not guess whether a collector flag is configured.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
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 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/bansafe/collection" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"collection": {
"state": "fresh",
"latestFlushedAt": "2026-09-22T12:00:00Z",
"latestReceivedAt": "2026-09-22T12:00:00Z",
"freshUntil": "2026-09-22T12:00:00Z",
"recordVersion": 0,
"collectorVersion": 0,
"partial": true,
"droppedRecords": 0
}
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe health actions
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists the durable customer-visible outcomes of project Health rule actions, newest first. Internal leases, retry bookkeeping, runtime identifiers, and free-form outcomes are omitted.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
sessionstringlength1–256Identifier of the connected Polymorfa session.
statusstringCurrent status of this resource or operation.
Allowed valuespendingrunningsucceededfailedcancelledcursorstringSpecifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 17 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/bansafe/health-actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"mode": "apply",
"action": "stop",
"status": "pending",
"health": 0,
"threshold": 0,
"healthSource": "rules_v1",
"estimatorVersion": "string",
"modelVersion": "string",
"slowDownMps": 0,
"evaluatedAt": "2026-09-22T12:00:00Z",
"createdAt": "2026-09-22T12:00:00Z",
"completedAt": "2026-09-22T12:00:00Z",
"outcome": "applied"
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe findings
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists safety findings across the team, filterable by project, number, status, and severity. Evidence is numbers only and never contains message content or a recipient identifier.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
sessionstringlength1–256Identifier of the connected Polymorfa session.
statusstringCurrent status of this resource or operation.
Allowed valuesopenacknowledgedresolvedseveritystringSpecifies severity for this query parameter.
Allowed valuesinfowarningcriticalcursorstringSpecifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 21 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/bansafe/findings" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"key": "string",
"title": "string",
"summary": "string",
"fix": "string",
"status": "open",
"severity": "info",
"occurrences": 0,
"reopenedCount": 0,
"evidence": {},
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"firstSeenAt": "2026-09-22T12:00:00Z",
"lastSeenAt": "2026-09-22T12:00:00Z",
"acknowledgedAt": "2026-09-22T12:00:00Z",
"acknowledgedBy": "string",
"acknowledgementNote": "string",
"snoozedUntil": "2026-09-22T12:00:00Z",
"resolvedAt": "2026-09-22T12:00:00Z",
"resolveReason": "clean"
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe enforcement
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists every number Polymorfa is currently restricting, what the restriction blocks, and the exact condition that lifts it.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
rungstringSpecifies rung for this query parameter.
Allowed valuesnonenotifythrottleblock_coldsuspendcursorstringSpecifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 33 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/bansafe/enforcement" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"rung": "none",
"previousRung": "none",
"teamFloor": "none",
"reason": "string",
"source": "automatic",
"throughputPerMinute": 0,
"blocksUnsolicited": true,
"suspended": true,
"health": 0,
"band": "good",
"healthSource": "rules_v1",
"healthEstimatorVersion": "string",
"healthModelVersion": "string",
"healthEvaluatedAt": "2026-09-22T12:00:00Z",
"healthFeatureCoverage": 0,
"healthReliability": "rules_based",
"healthUnavailableReason": "no_active_model",
"healthProbabilities": {
"healthy": 0,
"limited": 0,
"restricted": 0,
"banned": 0
},
"mostLikelyHealthState": "healthy",
"healthExplanation": {
"penalties": {
"conduct": 0,
"delivery": 0,
"connection": 0,
"restriction": 0,
"total": 0
},
"factors": [
{
"group": "direct_condition",
"key": "observed_limited",
"penalty": 0,
"observedValue": 0,
"sampleSize": 0
}
],
"measuredGroups": [
"direct_condition"
],
"missingGroups": [
"direct_condition"
]
},
"observedAccountState": {
"state": "healthy",
"observedAt": "2026-09-22T12:00:00Z",
"source": "account_check"
},
"blockingFindings": [
"string"
],
"startedAt": "2026-09-22T12:00:00Z",
"eligibleLiftAt": "2026-09-22T12:00:00Z",
"liftRequires": "string",
"operatorHold": true,
"appealState": "none",
"state": "applied"
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe incidents
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists the WhatsApp restrictions and customer reports recorded for the team's numbers.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
sessionstringlength1–256Identifier of the connected Polymorfa session.
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 17 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/bansafe/incidents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"kind": "cap_warning",
"source": "runtime",
"resolution": "string",
"ambiguous": true,
"startedAt": "2026-09-22T12:00:00Z",
"endsAt": "2026-09-22T12:00:00Z",
"closedAt": "2026-09-22T12:00:00Z",
"closedBy": "string",
"claimId": "00000000-0000-4000-8000-000000000000",
"note": "string",
"reportedBy": "string",
"createdAt": "2026-09-22T12:00:00Z"
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List ban safe claims
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Lists the Ban Credit claims filed on your numbers, newest first. A claim is filed automatically when a ban is recorded on a number whose plan includes Ban Credit; there is no request to file one.
Requires sessions:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringIdentifier of the Polymorfa project that owns this resource.
sessionstringlength1–256Identifier of the connected Polymorfa session.
statusstringCurrent status of this resource or operation.
Allowed valuesfiledunder_reviewapproveddeniedpaidreversedcursorstringSpecifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 19 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/bansafe/claims" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"incidentId": "00000000-0000-4000-8000-000000000000",
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"status": "filed",
"verdict": "other_device",
"windowStart": "2026-09-22T12:00:00Z",
"windowEnd": "2026-09-22T12:00:00Z",
"measuredCents": 0,
"capCents": 0,
"amountCents": 0,
"evidence": {
"attributionRuleVersion": 1,
"windowDays": 1,
"deviceEvidence": true,
"otherDevices": 0,
"restrictedInWindow": true,
"criticalFindingDays": 0,
"sharedConnection": true,
"measuredHours": 0,
"simultaneousCalls": true,
"linkedDeviceInteractive": true
},
"summary": "string",
"reason": "string",
"decidedAt": "2026-09-22T12:00:00Z",
"paidAt": "2026-09-22T12:00:00Z",
"createdAt": "2026-09-22T12:00:00Z"
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}Get project health policy
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Project health threshold and configured actions
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 9 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/messaging/projects/<projectId>/health-policy" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true,
"integrations": {
"emailConfigured": true,
"webhookConfigured": true
}
}
}Get ban safe health
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns one number's present Health estimate and model metadata, retained open and acknowledged findings with their observation times, directly observed account state, the active Polymorfa restriction, and how that restriction lifts. Recorded findings and observed state remain separate from the estimate.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 17 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/bansafe/health/<session>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"health": 0,
"band": "good",
"healthSource": "rules_v1",
"healthEstimatorVersion": "string",
"healthModelVersion": "string",
"healthEvaluatedAt": "2026-09-22T12:00:00Z",
"healthFeatureCoverage": 0,
"healthReliability": "rules_based",
"healthUnavailableReason": "no_active_model",
"healthProbabilities": {
"healthy": 0,
"limited": 0,
"restricted": 0,
"banned": 0
},
"mostLikelyHealthState": "healthy",
"healthExplanation": {
"penalties": {
"conduct": 0,
"delivery": 0,
"connection": 0,
"restriction": 0,
"total": 0
},
"factors": [
{
"group": "direct_condition",
"key": "observed_limited",
"penalty": 0,
"observedValue": 0,
"sampleSize": 0
}
],
"measuredGroups": [
"direct_condition"
],
"missingGroups": [
"direct_condition"
]
},
"observedAccountState": {
"state": "healthy",
"observedAt": "2026-09-22T12:00:00Z",
"source": "account_check"
},
"warmup": {
"enabled": true,
"tenureSource": "history",
"tenureDay": 0,
"allowance": 0,
"sentToday": 0,
"resetsAt": "2026-09-22T12:00:00Z",
"curve": [
{
"day": 0,
"allowance": 0
}
]
},
"findings": [
{
"id": "00000000-0000-4000-8000-000000000000",
"key": "string",
"title": "string",
"summary": "string",
"fix": "string",
"status": "open",
"severity": "info",
"occurrences": 0,
"reopenedCount": 0,
"evidence": {},
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"firstSeenAt": "2026-09-22T12:00:00Z",
"lastSeenAt": "2026-09-22T12:00:00Z",
"acknowledgedAt": "2026-09-22T12:00:00Z",
"acknowledgedBy": "string",
"acknowledgementNote": "string",
"snoozedUntil": "2026-09-22T12:00:00Z",
"resolvedAt": "2026-09-22T12:00:00Z",
"resolveReason": "clean"
}
],
"liftRequires": "string",
"appealState": "none"
}
}Get ban safe telemetry
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns collection availability and the latest supported telemetry snapshot for one number. Empty collection is reported as not collected, not as a disabled collector.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 5 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/bansafe/telemetry/<session>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"collection": {
"state": "fresh",
"latestFlushedAt": "2026-09-22T12:00:00Z",
"latestReceivedAt": "2026-09-22T12:00:00Z",
"freshUntil": "2026-09-22T12:00:00Z",
"recordVersion": 0,
"collectorVersion": 0,
"partial": true,
"droppedRecords": 0
},
"snapshot": {
"bucketStart": "2026-09-22T12:00:00Z",
"flushedAt": "2026-09-22T12:00:00Z",
"receivedAt": "2026-09-22T12:00:00Z",
"partial": true,
"recordVersion": 0,
"signals": [
{
"key": "string",
"label": "string",
"group": "string",
"kind": "number",
"unit": "count",
"description": "string",
"measured": true,
"value": 0,
"sampleSize": 0,
"codes": [
{
"code": null,
"count": null
}
]
}
]
}
}
}Get ban safe claim
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns one claim: the 30 days it covers, the credits that number consumed in them, the most the plan returns, what the claim returns, what the ban was attributed to, and the evidence counts behind that.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
claimIdstringrequiredIdentifier for the claim.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 19 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/bansafe/claims/<claimId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"incidentId": "00000000-0000-4000-8000-000000000000",
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"status": "filed",
"verdict": "other_device",
"windowStart": "2026-09-22T12:00:00Z",
"windowEnd": "2026-09-22T12:00:00Z",
"measuredCents": 0,
"capCents": 0,
"amountCents": 0,
"evidence": {
"attributionRuleVersion": 1,
"windowDays": 1,
"deviceEvidence": true,
"otherDevices": 0,
"restrictedInWindow": true,
"criticalFindingDays": 0,
"sharedConnection": true,
"measuredHours": 0,
"simultaneousCalls": true,
"linkedDeviceInteractive": true
},
"summary": "string",
"reason": "string",
"decidedAt": "2026-09-22T12:00:00Z",
"paidAt": "2026-09-22T12:00:00Z",
"createdAt": "2026-09-22T12:00:00Z"
}
}Get project safe mode ceiling
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns the most visible sending behaviour any number in this project may use. Every setting is off by default. entitled reports whether the plan includes BanSafe Lite, which Safe Mode is part of, and entitlementReason gives the reason a raise would be refused.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
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 "https://api.polymorfa.com/platform/projects/<projectId>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"ceiling": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"entitled": true,
"entitlementReason": "string"
}
}Get number safe mode
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns the project ceiling, this number's override, the policy in force, and what the number last reported it is running. mismatch is true when the two differ. entitled reports whether the plan includes BanSafe Lite, which Safe Mode is part of, and entitlementReason gives the reason a raise would be refused.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
sessionIdstringrequiredlength1–64Database session UUID or stable session slug.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 9 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/sessions/<sessionId>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"project": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"override": {
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
},
"effective": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"applied": {
"observedAt": "2026-09-22T12:00:00Z",
"presence": "string",
"typing": "string",
"reads": "string",
"pacing": "string"
},
"mismatch": true,
"entitled": true,
"entitlementReason": "string"
}
}Get project warmup plan settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns whether numbers in this project have a daily allowance, the two settings that shape the ramp, the per-number daily cap it climbs to, and the projected allowance day by day. entitled reports whether the plan includes BanSafe Lite, which the warm-up plan is part of.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
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/projects/<projectId>/warmup-plan" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"plan": {
"enabled": true,
"warmupDays": 1,
"dailyStart": 1
},
"ceiling": 1,
"curve": [
{
"day": 0,
"allowance": 0
}
],
"entitled": true,
"entitlementReason": "string"
}
}Get project health policy settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns the health threshold and the actions configured for numbers in this project. Integration flags report whether email and webhook delivery are ready to use.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 9 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/projects/<projectId>/health-policy" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true,
"integrations": {
"emailConfigured": true,
"webhookConfigured": true
}
}
}Get insurance evidence settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Returns whether evidence collection about other linked devices is enabled and whether any number in the project has Ban Credit included in its plan. Collection is off until explicitly enabled.
Requires sessions:read. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/projects/<projectId>/insurance-evidence" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"enabled": true,
"banInsuranceIncluded": true
}
}Update project health policy
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Replaces the project policy when version matches the stored version. The rule triggers only when an available health estimate is below threshold. Stopping disconnects a session while retaining its linked credentials; logging out requires relinking.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
versionintegerrequiredmin0Specifies version for this native update project health policy input.
enabledbooleanrequiredWhether this feature is enabled.
thresholdintegerrequiredrange0–100Specifies threshold for this native update project health policy input.
sessionActionstringrequiredSpecifies session action for this native update project health policy input.
Allowed valuesnonestopslow_downlog_outslowDownMpsnumberrequirednullablegreater than0Specifies slow down mps for this native update project health policy input.
emailNotificationbooleanrequiredWhether email notification.
webhookNotificationbooleanrequiredWhether webhook notification.
Responses
200Project health policy updated
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 9 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409Version conflict or selected notification integration unavailable
500Internal server error
curl -X PUT "https://api.polymorfa.com/messaging/projects/<projectId>/health-policy" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true
}'{
"success": true,
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true,
"integrations": {
"emailConfigured": true,
"webhookConfigured": true
}
}
}Update project safe mode ceiling
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Sets the most visible behaviour any number in this project may use. Send only the settings you want to change. Presence and read receipts are visible to the people these numbers message: turning them on makes a number appear online, exposes last seen subject to the account's privacy settings, and puts blue ticks on incoming messages. Raising a setting requires a plan that includes BanSafe Lite, and lowering one is always allowed. A signed-in caller must be a team owner, admin, or developer.
Requires sessions:manage. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
presencestringSpecifies presence for this management update project safe mode input.
Allowed valuesdarkonline_while_sendingonline_hourstypingstringSpecifies typing for this management update project safe mode input.
Allowed valuesoffbefore_textbefore_allreadsstringSpecifies reads for this management update project safe mode input.
Allowed valuesoffreplied_chatsall_inboundpacingstringSpecifies pacing for this management update project safe mode input.
Allowed valuesoffjitteredconversationonlineStartintegerrange0–23Specifies online start for this management update project safe mode input.
onlineEndintegerrange0–23Specifies online end for this management update project safe mode input.
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.
402`safe_mode_not_entitled`: Safe Mode is part of BanSafe Lite, which is not included on this number's plan. Lowering a setting always works.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
}'{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"ceiling": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"entitled": true,
"entitlementReason": "string"
}
}Update number safe mode
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Sets one number's Safe Mode. Each setting accepts inherit to follow the project ceiling. An override may only be equally or more conservative than the ceiling; a more visible value is refused with safe_mode_exceeds_project_ceiling. Raising a setting requires a plan that includes BanSafe Lite, and lowering one is always allowed. A signed-in caller must be a team owner, admin, or developer.
Requires sessions:manage. Project tokens only access resources in their own project.
Path parameters
sessionIdstringrequiredlength1–64Database session UUID or stable session slug.
Body
presencestringSpecifies presence for this management update session safe mode input.
Allowed valuesinheritdarkonline_while_sendingonline_hourstypingstringSpecifies typing for this management update session safe mode input.
Allowed valuesinheritoffbefore_textbefore_allreadsstringSpecifies reads for this management update session safe mode input.
Allowed valuesinheritoffreplied_chatsall_inboundpacingstringSpecifies pacing for this management update session safe mode input.
Allowed valuesinheritoffjitteredconversation
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 9 child fields
Show 3 headers
400A path, query, or request-body value did not pass validation.
401Missing/invalid credential for this audience.
402`safe_mode_not_entitled`: Safe Mode is part of BanSafe Lite, which is not included on this number's plan. Lowering a setting always works.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
curl -X PUT "https://api.polymorfa.com/platform/sessions/<sessionId>/safe-mode" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
}'{
"data": {
"session": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"project": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"override": {
"presence": "inherit",
"typing": "inherit",
"reads": "inherit",
"pacing": "inherit"
},
"effective": {
"presence": "dark",
"typing": "off",
"reads": "off",
"pacing": "off",
"onlineStart": 0,
"onlineEnd": 0
},
"applied": {
"observedAt": "2026-09-22T12:00:00Z",
"presence": "string",
"typing": "string",
"reads": "string",
"pacing": "string"
},
"mismatch": true,
"entitled": true,
"entitlementReason": "string"
}
}Update project warmup plan settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Turns the warm-up plan on or off for a project and sets how long the ramp takes and how many messages a number may send on its first day. Send only the settings you want to change. While the plan is on, a send past a number's allowance is refused with bansafe_daily_allowance_reached and campaign recipients are deferred to the next reset. Turning the plan on requires a plan that includes BanSafe Lite; turning it off is always allowed. A signed-in caller must be a team owner, admin, or developer.
Requires sessions:manage. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
enabledbooleanWhether this feature is enabled.
warmupDaysintegerrange1–90Specifies warmup days for this management update project warmup plan input.
dailyStartintegerrange1–2000Specifies daily start for this management update project warmup plan input.
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.
402`warmup_plan_not_entitled`: the warm-up plan is part of BanSafe Lite, which is not included on this project's plan. Turning the plan off always works.
403Authenticated but lacks the required scope/role/audience.
404The requested resource was not found inside the authenticated team or project scope.
503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/warmup-plan" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"warmupDays": 1,
"dailyStart": 1
}'{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"plan": {
"enabled": true,
"warmupDays": 1,
"dailyStart": 1
},
"ceiling": 1,
"curve": [
{
"day": 0,
"allowance": 0
}
],
"entitled": true,
"entitlementReason": "string"
}
}Update project health policy settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Replaces the project policy when the supplied version matches the stored version. The rule applies only when an available health estimate is below the threshold; an unavailable estimate triggers no action. Stopping disconnects a session and retains its linked credentials. Logging out requires relinking.
Requires sessions:manage. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
versionintegerrequiredmin0Specifies version for this management update project health policy input.
enabledbooleanrequiredWhether this feature is enabled.
thresholdintegerrequiredrange0–100Specifies threshold for this management update project health policy input.
sessionActionstringrequiredSpecifies session action for this management update project health policy input.
Allowed valuesnonestopslow_downlog_outslowDownMpsnumberrequirednullablegreater than0Specifies slow down mps for this management update project health policy input.
emailNotificationbooleanrequiredWhether email notification.
webhookNotificationbooleanrequiredWhether webhook notification.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 9 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 PUT "https://api.polymorfa.com/platform/projects/<projectId>/health-policy" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true
}'{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"version": 0,
"enabled": true,
"threshold": 0,
"sessionAction": "none",
"slowDownMps": 0,
"emailNotification": true,
"webhookNotification": true,
"integrations": {
"emailConfigured": true,
"webhookConfigured": true
}
}
}Update insurance evidence settings
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Enables or disables collection of counts about other linked devices. Collection never includes messages, recipient identities, or device names. Disabling collection discards stored device evidence. A 503 propagation_pending means the setting was stored but a connected number has not confirmed it; retry the request. A signed-in caller must be an team owner, admin, or developer.
Requires sessions:manage. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Body
enabledbooleanrequiredWhether this feature is enabled.
Responses
200Success
dataobjectrequiredStructured 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.
503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/insurance-evidence" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'{
"data": {
"projectId": "00000000-0000-4000-8000-000000000000",
"enabled": true,
"banInsuranceIncluded": true
}
}Retract ban safe incident
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Withdraws a customer report and returns its incident record. Repeating the request returns the closed record. An incident observed from WhatsApp cannot be withdrawn and returns 409 bansafe_incident_not_a_report. An unknown incident returns 404.
Team keys require sessions:manage. Project tokens are not accepted.
Path parameters
incidentIdstringrequiredIdentifier for the incident.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 17 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/bansafe/incidents/<incidentId>/retract" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"sessionId": "00000000-0000-4000-8000-000000000000",
"session": "string",
"phoneNumber": "string",
"projectId": "00000000-0000-4000-8000-000000000000",
"kind": "cap_warning",
"source": "runtime",
"resolution": "string",
"ambiguous": true,
"startedAt": "2026-09-22T12:00:00Z",
"endsAt": "2026-09-22T12:00:00Z",
"closedAt": "2026-09-22T12:00:00Z",
"closedBy": "string",
"claimId": "00000000-0000-4000-8000-000000000000",
"note": "string",
"reportedBy": "string",
"createdAt": "2026-09-22T12:00:00Z"
}
}