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

BanSafe

View as Markdown

The BanSafe number object

Attributes

  • sessionIdstring (uuid)required

    Identifier of the connected Polymorfa session.

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • phoneNumberstringrequired

    Phone number in international format.

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • healthnumberrequirednullablerange0–100

    Estimate of present account Health. Higher is healthier. Read healthSource, healthReliability, and healthFeatureCoverage with it.

  • bandstringrequired

    Specifies band for this management ban safe number.

    Allowed valuesgoodfairpoorfailingunknown
  • healthSourcestringrequired

    Estimator family. rules_v1 is deterministic; unavailable carries no numeric Health.

    Allowed valuesrules_v1ml_modelunavailable
  • healthEstimatorVersionstringrequirednullable

    Version of the estimator that produced Health.

  • healthModelVersionstringrequirednullable

    Learned-model artifact version. Null for rules_v1.

  • healthEvaluatedAtstring (date-time)requirednullable

    Timestamp for health evaluated at.

  • healthFeatureCoveragenumberrequirednullablerange0–1

    Specifies health feature coverage for this management ban safe number.

  • healthReliabilitystringrequired

    Support category, not a confidence score.

    Allowed valuesrules_basedvalidatedunavailable
  • healthUnavailableReasonstringrequirednullable

    Specifies health unavailable reason for this management ban safe number.

    Allowed valuesno_active_modelinvalid_active_modelinsufficient_fresh_features
  • healthProbabilitiesobjectrequirednullable

    Specifies health probabilities for this management ban safe number.

    Show 4 child fields
  • mostLikelyHealthStatestringrequirednullable

    Specifies most likely health state for this management ban safe number.

    Allowed valueshealthylimitedrestrictedbanned
  • healthExplanationobjectrequirednullable

    Specifies health explanation for this management ban safe number.

    Show 4 child fields
  • observedAccountStateobjectrequirednullable

    Specifies observed account state for this management ban safe number.

    Show 3 child fields
  • enforcementobjectrequirednullable

    Specifies enforcement for this management ban safe number.

    Show 15 child fields
The BanSafe number object
{
  "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)required

    Identifier for this resource.

  • sessionIdstring (uuid)required

    Identifier of the connected Polymorfa session.

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • phoneNumberstringrequired

    Phone number in international format.

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • kindstringrequired

    Kind discriminator for this object.

    Allowed valuescap_warningcap_reachedtimelocktemporary_banpermanent_banconnect_blockedcustomer_report
  • sourcestringrequired

    Specifies source for this management ban safe incident.

    Allowed valuesruntimecustomer
  • resolutionstringrequired

    Specifies resolution for this management ban safe incident.

  • ambiguousbooleanrequired

    Whether ambiguous.

  • startedAtstring (date-time)required

    Timestamp for started at.

  • endsAtstring (date-time)requirednullable

    Timestamp for ends at.

  • closedAtstring (date-time)requirednullable

    Timestamp for closed at.

  • closedBystringrequirednullable

    Specifies closed by for this management ban safe incident.

  • claimIdstring (uuid)requirednullable

    Identifier for the claim.

  • notestringrequirednullablemax length500

    Specifies note for this management ban safe incident.

  • reportedBystringrequirednullable

    Specifies reported by for this management ban safe incident.

  • createdAtstring (date-time)required

    ISO 8601 timestamp when this resource was created.

The BanSafe incident object
{
  "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)required

    Identifier of the Polymorfa project that owns this resource.

  • versionintegerrequiredmin0

    Specifies version for this native project health policy.

  • enabledbooleanrequired

    Whether this feature is enabled.

  • thresholdintegerrequiredrange0–100

    Specifies threshold for this native project health policy.

  • sessionActionstringrequired

    Specifies session action for this native project health policy.

    Allowed valuesnonestopslow_downlog_out
  • slowDownMpsnumberrequirednullablegreater than0

    Specifies slow down mps for this native project health policy.

  • emailNotificationbooleanrequired

    Whether email notification.

  • webhookNotificationbooleanrequired

    Whether webhook notification.

  • integrationsobjectrequired

    Structured integrations values for this native project health policy.

    Show 2 child fields
The health rule object
{
  "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

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

    Specifies idempotency key for this header parameter.

Body

  • sessionstringrequiredlength1–256

    Identifier of the connected Polymorfa session.

  • occurredAtstring (date-time)

    Timestamp for occurred at.

  • notestringmax length500

    Specifies note for this management report ban safe incident input.

Responses

  • 200Success
    • dataobjectrequired

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

GET/platform/bansafe/healthPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • 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 18 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/healthcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/health" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/health/{session}/historyPlatform API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Query parameters

  • sincestring (date-time)

    Specifies since for this query parameter.

  • limitintegerrange1–720

    Specifies limit for this query parameter.

    Default 720

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.
GET /platform/bansafe/health/{session}/historycURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/health/<session>/history" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/signalsPlatform API
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 objectrequired

      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/bansafe/signalscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/signals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "key": "string",
      "label": "string",
      "group": "string",
      "kind": "number",
      "unit": "count",
      "description": "string"
    }
  ]
}

List ban safe telemetry history

GET/platform/bansafe/telemetry/{session}/historyPlatform API
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

  • sessionstringrequired

    Identifier 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.

  • cursorstring

    Specifies cursor for this query parameter.

  • limitintegerrange1–50

    Specifies limit for this query parameter.

    Default 10

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.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/telemetry/{session}/historycURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/telemetry/<session>/history" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/collectionPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • 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 4 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/collectioncURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/collection" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/health-actionsPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • sessionstringlength1–256

    Identifier of the connected Polymorfa session.

  • statusstring

    Current status of this resource or operation.

    Allowed valuespendingrunningsucceededfailedcancelled
  • 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 17 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/health-actionscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/health-actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/findingsPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • sessionstringlength1–256

    Identifier of the connected Polymorfa session.

  • statusstring

    Current status of this resource or operation.

    Allowed valuesopenacknowledgedresolved
  • severitystring

    Specifies severity for this query parameter.

    Allowed valuesinfowarningcritical
  • 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 21 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/findingscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/findings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/enforcementPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • rungstring

    Specifies rung for this query parameter.

    Allowed valuesnonenotifythrottleblock_coldsuspend
  • 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 33 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/enforcementcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/enforcement" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/incidentsPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • sessionstringlength1–256

    Identifier of the connected Polymorfa session.

  • 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 17 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/incidentscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/incidents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/claimsPlatform API
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

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

  • sessionstringlength1–256

    Identifier of the connected Polymorfa session.

  • statusstring

    Current status of this resource or operation.

    Allowed valuesfiledunder_reviewapproveddeniedpaidreversed
  • 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 19 child fields
    • pageobjectrequired

      Specifies page for this schema.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/bansafe/claimscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/claims" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/messaging/projects/{projectId}/health-policyMessaging API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Project health threshold and configured actions
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
GET /messaging/projects/{projectId}/health-policycURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/projects/<projectId>/health-policy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/health/{session}Platform API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/bansafe/health/{session}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/health/<session>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/telemetry/{session}Platform API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/bansafe/telemetry/{session}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/telemetry/<session>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/bansafe/claims/{claimId}Platform API
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

  • claimIdstringrequired

    Identifier for the claim.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/bansafe/claims/{claimId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/bansafe/claims/<claimId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/projects/{projectId}/safe-modePlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/projects/{projectId}/safe-modecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/safe-mode" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/sessions/{sessionId}/safe-modePlatform API
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–64

    Database session UUID or stable session slug.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/sessions/{sessionId}/safe-modecURL
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/safe-mode" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/projects/{projectId}/warmup-planPlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

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/projects/{projectId}/warmup-plancURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/warmup-plan" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/projects/{projectId}/health-policyPlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/projects/{projectId}/health-policycURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/health-policy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/projects/{projectId}/insurance-evidencePlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

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.
GET /platform/projects/{projectId}/insurance-evidencecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/insurance-evidence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "banInsuranceIncluded": true
  }
}

Update project health policy

PUT/messaging/projects/{projectId}/health-policyMessaging API
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)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • versionintegerrequiredmin0

    Specifies version for this native update project health policy input.

  • enabledbooleanrequired

    Whether this feature is enabled.

  • thresholdintegerrequiredrange0–100

    Specifies threshold for this native update project health policy input.

  • sessionActionstringrequired

    Specifies session action for this native update project health policy input.

    Allowed valuesnonestopslow_downlog_out
  • slowDownMpsnumberrequirednullablegreater than0

    Specifies slow down mps for this native update project health policy input.

  • emailNotificationbooleanrequired

    Whether email notification.

  • webhookNotificationbooleanrequired

    Whether webhook notification.

Responses

  • 200Project health policy updated
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
PUT /messaging/projects/{projectId}/health-policycURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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

PUT/platform/projects/{projectId}/safe-modePlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • presencestring

    Specifies presence for this management update project safe mode input.

    Allowed valuesdarkonline_while_sendingonline_hours
  • typingstring

    Specifies typing for this management update project safe mode input.

    Allowed valuesoffbefore_textbefore_all
  • readsstring

    Specifies reads for this management update project safe mode input.

    Allowed valuesoffreplied_chatsall_inbound
  • pacingstring

    Specifies pacing for this management update project safe mode input.

    Allowed valuesoffjitteredconversation
  • onlineStartintegerrange0–23

    Specifies online start for this management update project safe mode input.

  • onlineEndintegerrange0–23

    Specifies online end for this management update project safe mode input.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 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.
PUT /platform/projects/{projectId}/safe-modecURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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

PUT/platform/sessions/{sessionId}/safe-modePlatform API
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–64

    Database session UUID or stable session slug.

Body

  • presencestring

    Specifies presence for this management update session safe mode input.

    Allowed valuesinheritdarkonline_while_sendingonline_hours
  • typingstring

    Specifies typing for this management update session safe mode input.

    Allowed valuesinheritoffbefore_textbefore_all
  • readsstring

    Specifies reads for this management update session safe mode input.

    Allowed valuesinheritoffreplied_chatsall_inbound
  • pacingstring

    Specifies pacing for this management update session safe mode input.

    Allowed valuesinheritoffjitteredconversation

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
PUT /platform/sessions/{sessionId}/safe-modecURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

PUT/platform/projects/{projectId}/warmup-planPlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • enabledboolean

    Whether this feature is enabled.

  • warmupDaysintegerrange1–90

    Specifies warmup days for this management update project warmup plan input.

  • dailyStartintegerrange1–2000

    Specifies daily start for this management update project warmup plan input.

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.
  • 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.
PUT /platform/projects/{projectId}/warmup-plancURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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

PUT/platform/projects/{projectId}/health-policyPlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • versionintegerrequiredmin0

    Specifies version for this management update project health policy input.

  • enabledbooleanrequired

    Whether this feature is enabled.

  • thresholdintegerrequiredrange0–100

    Specifies threshold for this management update project health policy input.

  • sessionActionstringrequired

    Specifies session action for this management update project health policy input.

    Allowed valuesnonestopslow_downlog_out
  • slowDownMpsnumberrequirednullablegreater than0

    Specifies slow down mps for this management update project health policy input.

  • emailNotificationbooleanrequired

    Whether email notification.

  • webhookNotificationbooleanrequired

    Whether webhook notification.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
PUT /platform/projects/{projectId}/health-policycURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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

PUT/platform/projects/{projectId}/insurance-evidencePlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Body

  • enabledbooleanrequired

    Whether this feature is enabled.

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.
  • 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.
PUT /platform/projects/{projectId}/insurance-evidencecURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "banInsuranceIncluded": true
  }
}

Retract ban safe incident

POST/platform/bansafe/incidents/{incidentId}/retractPlatform API
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

  • incidentIdstringrequired

    Identifier for the incident.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
POST /platform/bansafe/incidents/{incidentId}/retractcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/bansafe/incidents/<incidentId>/retract" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
  }
}