# BanSafe

## Endpoints

- `POST /platform/bansafe/incidents`: [Create ban safe incident](https://docs.polymorfa.com/api/bansafe/create-ban-safe-incident) (Platform API)
- `GET /platform/bansafe/health`: [List ban safe health](https://docs.polymorfa.com/api/bansafe/list-ban-safe-health) (Platform API)
- `GET /platform/bansafe/health/{session}/history`: [List ban safe health history](https://docs.polymorfa.com/api/bansafe/list-ban-safe-health-history) (Platform API)
- `GET /platform/bansafe/signals`: [List ban safe signals](https://docs.polymorfa.com/api/bansafe/list-ban-safe-signals) (Platform API)
- `GET /platform/bansafe/telemetry/{session}/history`: [List ban safe telemetry history](https://docs.polymorfa.com/api/bansafe/list-ban-safe-telemetry-history) (Platform API)
- `GET /platform/bansafe/collection`: [List ban safe collection](https://docs.polymorfa.com/api/bansafe/list-ban-safe-collection) (Platform API)
- `GET /platform/bansafe/health-actions`: [List ban safe health actions](https://docs.polymorfa.com/api/bansafe/list-ban-safe-health-actions) (Platform API)
- `GET /platform/bansafe/findings`: [List ban safe findings](https://docs.polymorfa.com/api/bansafe/list-ban-safe-findings) (Platform API)
- `GET /platform/bansafe/enforcement`: [List ban safe enforcement](https://docs.polymorfa.com/api/bansafe/list-ban-safe-enforcement) (Platform API)
- `GET /platform/bansafe/incidents`: [List ban safe incidents](https://docs.polymorfa.com/api/bansafe/list-ban-safe-incidents) (Platform API)
- `GET /platform/bansafe/claims`: [List ban safe claims](https://docs.polymorfa.com/api/bansafe/list-ban-safe-claims) (Platform API)
- `GET /messaging/projects/{projectId}/health-policy`: [Get project health policy](https://docs.polymorfa.com/api/bansafe/get-project-health-policy) (Messaging API)
- `GET /platform/bansafe/health/{session}`: [Get ban safe health](https://docs.polymorfa.com/api/bansafe/get-ban-safe-health) (Platform API)
- `GET /platform/bansafe/telemetry/{session}`: [Get ban safe telemetry](https://docs.polymorfa.com/api/bansafe/get-ban-safe-telemetry) (Platform API)
- `GET /platform/bansafe/claims/{claimId}`: [Get ban safe claim](https://docs.polymorfa.com/api/bansafe/get-ban-safe-claim) (Platform API)
- `GET /platform/projects/{projectId}/safe-mode`: [Get project safe mode ceiling](https://docs.polymorfa.com/api/bansafe/get-project-safe-mode-ceiling) (Platform API)
- `GET /platform/sessions/{sessionId}/safe-mode`: [Get number safe mode](https://docs.polymorfa.com/api/bansafe/get-number-safe-mode) (Platform API)
- `GET /platform/projects/{projectId}/warmup-plan`: [Get project warmup plan settings](https://docs.polymorfa.com/api/bansafe/get-project-warmup-plan-settings) (Platform API)
- `GET /platform/projects/{projectId}/health-policy`: [Get project health policy settings](https://docs.polymorfa.com/api/bansafe/get-project-health-policy-settings) (Platform API)
- `GET /platform/projects/{projectId}/insurance-evidence`: [Get insurance evidence settings](https://docs.polymorfa.com/api/bansafe/get-insurance-evidence-settings) (Platform API)
- `PUT /messaging/projects/{projectId}/health-policy`: [Update project health policy](https://docs.polymorfa.com/api/bansafe/update-project-health-policy) (Messaging API)
- `PUT /platform/projects/{projectId}/safe-mode`: [Update project safe mode ceiling](https://docs.polymorfa.com/api/bansafe/update-project-safe-mode-ceiling) (Platform API)
- `PUT /platform/sessions/{sessionId}/safe-mode`: [Update number safe mode](https://docs.polymorfa.com/api/bansafe/update-number-safe-mode) (Platform API)
- `PUT /platform/projects/{projectId}/warmup-plan`: [Update project warmup plan settings](https://docs.polymorfa.com/api/bansafe/update-project-warmup-plan-settings) (Platform API)
- `PUT /platform/projects/{projectId}/health-policy`: [Update project health policy settings](https://docs.polymorfa.com/api/bansafe/update-project-health-policy-settings) (Platform API)
- `PUT /platform/projects/{projectId}/insurance-evidence`: [Update insurance evidence settings](https://docs.polymorfa.com/api/bansafe/update-insurance-evidence-settings) (Platform API)
- `POST /platform/bansafe/incidents/{incidentId}/retract`: [Retract ban safe incident](https://docs.polymorfa.com/api/bansafe/retract-ban-safe-incident) (Platform API)

## The BanSafe number object

### Attributes

- `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
- `session` (string, required). Identifier of the connected Polymorfa session.
- `phoneNumber` (string, required). Phone number in international format.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `health` (number, required, nullable, range 0–100). Estimate of present account Health. Higher is healthier. Read healthSource, healthReliability, and healthFeatureCoverage with it.
- `band` (string, required). Specifies band for this management ban safe number. Values: `good`, `fair`, `poor`, `failing`, `unknown`.
- `healthSource` (string, required). Estimator family. rules_v1 is deterministic; unavailable carries no numeric Health. Values: `rules_v1`, `ml_model`, `unavailable`.
- `healthEstimatorVersion` (string, required, nullable). Version of the estimator that produced Health.
- `healthModelVersion` (string, required, nullable). Learned-model artifact version. Null for rules_v1.
- `healthEvaluatedAt` (string (date-time), required, nullable, format date-time). Timestamp for health evaluated at.
- `healthFeatureCoverage` (number, required, nullable, range 0–1). Specifies health feature coverage for this management ban safe number.
- `healthReliability` (string, required). Support category, not a confidence score. Values: `rules_based`, `validated`, `unavailable`.
- `healthUnavailableReason` (string, required, nullable). Specifies health unavailable reason for this management ban safe number. Values: `no_active_model`, `invalid_active_model`, `insufficient_fresh_features`.
- `healthProbabilities` (object, required, nullable). Specifies health probabilities for this management ban safe number.
  - `healthy` (number, required, range 0–1). Specifies healthy for this management ban safe health probability.
  - `limited` (number, required, range 0–1). Specifies limited for this management ban safe health probability.
  - `restricted` (number, required, range 0–1). Specifies restricted for this management ban safe health probability.
  - `banned` (number, required, range 0–1). Specifies banned for this management ban safe health probability.
- `mostLikelyHealthState` (string, required, nullable). Specifies most likely health state for this management ban safe number. Values: `healthy`, `limited`, `restricted`, `banned`.
- `healthExplanation` (object, required, nullable). Specifies health explanation for this management ban safe number.
  - `penalties` (object, required). Structured penalties values for this management ban safe health explanation.
    - `conduct` (number, required, range 0–100). Specifies conduct for this penalty.
    - `delivery` (number, required, range 0–100). Specifies delivery for this penalty.
    - `connection` (number, required, range 0–100). Specifies connection for this penalty.
    - `restriction` (number, required, range 0–100). Specifies restriction for this penalty.
    - `total` (number, required, range 0–100). Final total for this order or price summary.
  - `factors` (array of object, required, max items 8). Factors associated with this management ban safe health explanation.
    - `group` (string, required). Specifies group for this management ban safe health explanation factor. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
    - `key` (string, required). Specifies key for this management ban safe health explanation factor. Values: `observed_limited`, `observed_restricted`, `observed_banned`, `send_failures`, `receipt_errors`, `server_ack_tail`, `connection_failures`, `connection_churn`, `connection_disconnected`, `auto_reconnect_errors`, `keep_alive_errors`, `unanswered_first_contacts`, `unsolicited_sends`, `send_burst`, `fixed_send_rhythm`.
    - `penalty` (number, required, range 0–100). Specifies penalty for this management ban safe health explanation factor.
    - `observedValue` (number, required). Specifies observed value for this management ban safe health explanation factor.
    - `sampleSize` (integer, required, min 0). Specifies sample size for this management ban safe health explanation factor.
  - `measuredGroups` (array of string, required, max items 5, unique items). Measured groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
  - `missingGroups` (array of string, required, max items 5, unique items). Missing groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
- `observedAccountState` (object, required, nullable). Specifies observed account state for this management ban safe number.
  - `state` (string, required). Current lifecycle state of this resource. Values: `healthy`, `limited`, `restricted`, `banned`.
  - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
  - `source` (string, required). Specifies source for this management ban safe observed account state. Values: `account_check`, `restriction_event`.
- `enforcement` (object, required, nullable). Specifies enforcement for this management ban safe number.
  - `rung` (string, required). Specifies rung for this management ban safe number enforcement. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
  - `previousRung` (string, required). Specifies previous rung for this management ban safe number enforcement. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
  - `teamFloor` (string, required). The lowest restriction every number in this workspace is held to. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
  - `reason` (string, required). Reason for the reported state or outcome.
  - `source` (string, required). Specifies source for this management ban safe number enforcement. Values: `automatic`, `operator`.
  - `throughputPerMinute` (number, required, nullable). Messages per minute this number is paced to, or null when it is not paced.
  - `blocksUnsolicited` (boolean, required). First messages to people who never wrote to this number are refused outside Campaigns.
  - `suspended` (boolean, required). This number cannot originate a message. It still receives, reads, and shows presence.
  - `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
  - `eligibleLiftAt` (string (date-time), required, nullable, format date-time). Timestamp for eligible lift at.
  - `exitProgress` (integer, required, min 0). Consecutive checks already passed toward lifting.
  - `blockingFindings` (array of string, required). Blocking findings associated with this management ban safe number enforcement.
  - `operatorHold` (boolean, required). Whether operator hold.
  - `appealState` (string, required). Specifies appeal state for this management ban safe number enforcement. Values: `none`, `requested`, `granted`, `denied`.
  - `state` (string, required). `applying` while the number has not confirmed the restriction. Values: `applied`, `applying`.
```json
{
  "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

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
- `session` (string, required). Identifier of the connected Polymorfa session.
- `phoneNumber` (string, required). Phone number in international format.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `kind` (string, required). Kind discriminator for this object. Values: `cap_warning`, `cap_reached`, `timelock`, `temporary_ban`, `permanent_ban`, `connect_blocked`, `customer_report`.
- `source` (string, required). Specifies source for this management ban safe incident. Values: `runtime`, `customer`.
- `resolution` (string, required). Specifies resolution for this management ban safe incident.
- `ambiguous` (boolean, required). Whether ambiguous.
- `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
- `endsAt` (string (date-time), required, nullable, format date-time). Timestamp for ends at.
- `closedAt` (string (date-time), required, nullable, format date-time). Timestamp for closed at.
- `closedBy` (string, required, nullable). Specifies closed by for this management ban safe incident.
- `claimId` (string (uuid), required, nullable, format uuid). Identifier for the claim.
- `note` (string, required, nullable, max length 500). Specifies note for this management ban safe incident.
- `reportedBy` (string, required, nullable). Specifies reported by for this management ban safe incident.
- `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
```json
{
  "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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `version` (integer, required, min 0). Specifies version for this native project health policy.
- `enabled` (boolean, required). Whether this feature is enabled.
- `threshold` (integer, required, range 0–100). Specifies threshold for this native project health policy.
- `sessionAction` (string, required). Specifies session action for this native project health policy. Values: `none`, `stop`, `slow_down`, `log_out`.
- `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this native project health policy.
- `emailNotification` (boolean, required). Whether email notification.
- `webhookNotification` (boolean, required). Whether webhook notification.
- `integrations` (object, required). Structured integrations values for this native project health policy.
  - `emailConfigured` (boolean, required). Whether email configured.
  - `webhookConfigured` (boolean, required). Whether webhook configured.
```json
{
  "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 https://api.polymorfa.com/platform/bansafe/incidents` (Platform API)

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.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `session` (string, required, length 1–256). Identifier of the connected Polymorfa session.
- `occurredAt` (string (date-time), format date-time). Timestamp for occurred at.
- `note` (string, max length 500). Specifies note for this management report ban safe incident input.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/bansafe/incidents" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "session": "string"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `incidentId` (string (uuid), required, format uuid). Identifier for the incident.
  - `created` (boolean, required). False when the same Idempotency-Key already recorded this report.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `occurredAt` (string (date-time), required, format date-time). Timestamp for occurred at.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "incidentId": "00000000-0000-4000-8000-000000000000",
    "created": true,
    "sessionId": "00000000-0000-4000-8000-000000000000",
    "session": "string",
    "occurredAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 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.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

## List ban safe health

`GET https://api.polymorfa.com/platform/bansafe/health` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/health" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `health` (number, required, nullable, range 0–100). Estimate of present account Health. Higher is healthier. Read healthSource, healthReliability, and healthFeatureCoverage with it.
  - `band` (string, required). Specifies band for this management ban safe number. Values: `good`, `fair`, `poor`, `failing`, `unknown`.
  - `healthSource` (string, required). Estimator family. rules_v1 is deterministic; unavailable carries no numeric Health. Values: `rules_v1`, `ml_model`, `unavailable`.
  - `healthEstimatorVersion` (string, required, nullable). Version of the estimator that produced Health.
  - `healthModelVersion` (string, required, nullable). Learned-model artifact version. Null for rules_v1.
  - `healthEvaluatedAt` (string (date-time), required, nullable, format date-time). Timestamp for health evaluated at.
  - `healthFeatureCoverage` (number, required, nullable, range 0–1). Specifies health feature coverage for this management ban safe number.
  - `healthReliability` (string, required). Support category, not a confidence score. Values: `rules_based`, `validated`, `unavailable`.
  - `healthUnavailableReason` (string, required, nullable). Specifies health unavailable reason for this management ban safe number. Values: `no_active_model`, `invalid_active_model`, `insufficient_fresh_features`.
  - `healthProbabilities` (object, required, nullable). Specifies health probabilities for this management ban safe number.
    - `healthy` (number, required, range 0–1). Specifies healthy for this management ban safe health probability.
    - `limited` (number, required, range 0–1). Specifies limited for this management ban safe health probability.
    - `restricted` (number, required, range 0–1). Specifies restricted for this management ban safe health probability.
    - `banned` (number, required, range 0–1). Specifies banned for this management ban safe health probability.
  - `mostLikelyHealthState` (string, required, nullable). Specifies most likely health state for this management ban safe number. Values: `healthy`, `limited`, `restricted`, `banned`.
  - `healthExplanation` (object, required, nullable). Specifies health explanation for this management ban safe number.
    - `penalties` (object, required). Structured penalties values for this management ban safe health explanation.
      - `conduct` (number, required, range 0–100). Specifies conduct for this penalty.
      - `delivery` (number, required, range 0–100). Specifies delivery for this penalty.
      - `connection` (number, required, range 0–100). Specifies connection for this penalty.
      - `restriction` (number, required, range 0–100). Specifies restriction for this penalty.
      - `total` (number, required, range 0–100). Final total for this order or price summary.
    - `factors` (array of object, required, max items 8). Factors associated with this management ban safe health explanation.
      - `group` (string, required). Specifies group for this management ban safe health explanation factor. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
      - `key` (string, required). Specifies key for this management ban safe health explanation factor. Values: `observed_limited`, `observed_restricted`, `observed_banned`, `send_failures`, `receipt_errors`, `server_ack_tail`, `connection_failures`, `connection_churn`, `connection_disconnected`, `auto_reconnect_errors`, `keep_alive_errors`, `unanswered_first_contacts`, `unsolicited_sends`, `send_burst`, `fixed_send_rhythm`.
      - `penalty` (number, required, range 0–100). Specifies penalty for this management ban safe health explanation factor.
      - `observedValue` (number, required). Specifies observed value for this management ban safe health explanation factor.
      - `sampleSize` (integer, required, min 0). Specifies sample size for this management ban safe health explanation factor.
    - `measuredGroups` (array of string, required, max items 5, unique items). Measured groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
    - `missingGroups` (array of string, required, max items 5, unique items). Missing groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
  - `observedAccountState` (object, required, nullable). Specifies observed account state for this management ban safe number.
    - `state` (string, required). Current lifecycle state of this resource. Values: `healthy`, `limited`, `restricted`, `banned`.
    - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
    - `source` (string, required). Specifies source for this management ban safe observed account state. Values: `account_check`, `restriction_event`.
  - `enforcement` (object, required, nullable). Specifies enforcement for this management ban safe number.
    - `rung` (string, required). Specifies rung for this management ban safe number enforcement. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
    - `previousRung` (string, required). Specifies previous rung for this management ban safe number enforcement. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
    - `teamFloor` (string, required). The lowest restriction every number in this workspace is held to. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
    - `reason` (string, required). Reason for the reported state or outcome.
    - `source` (string, required). Specifies source for this management ban safe number enforcement. Values: `automatic`, `operator`.
    - `throughputPerMinute` (number, required, nullable). Messages per minute this number is paced to, or null when it is not paced.
    - `blocksUnsolicited` (boolean, required). First messages to people who never wrote to this number are refused outside Campaigns.
    - `suspended` (boolean, required). This number cannot originate a message. It still receives, reads, and shows presence.
    - `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
    - `eligibleLiftAt` (string (date-time), required, nullable, format date-time). Timestamp for eligible lift at.
    - `exitProgress` (integer, required, min 0). Consecutive checks already passed toward lifting.
    - `blockingFindings` (array of string, required). Blocking findings associated with this management ban safe number enforcement.
    - `operatorHold` (boolean, required). Whether operator hold.
    - `appealState` (string, required). Specifies appeal state for this management ban safe number enforcement. Values: `none`, `requested`, `granted`, `denied`.
    - `state` (string, required). `applying` while the number has not confirmed the restriction. Values: `applied`, `applying`.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe health history

`GET https://api.polymorfa.com/platform/bansafe/health/{session}/history` (Platform API)

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

- `session` (string, required). Identifier of the connected Polymorfa session.

### Query parameters

- `since` (string (date-time), format date-time). Specifies since for this query parameter.
- `limit` (integer, range 1–720). Specifies limit for this query parameter. Default: `720`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/health/<session>/history" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `points` (array of object, required). Points associated with this management ban safe health history.
    - `health` (number, required, nullable, range 0–100). Specifies health for this management ban safe health point.
    - `band` (string, required, nullable). Specifies band for this management ban safe health point. Values: `good`, `fair`, `poor`, `failing`, `unknown`.
    - `healthSource` (string, required). Specifies health source for this management ban safe health point. Values: `rules_v1`, `ml_model`, `unavailable`.
    - `healthEstimatorVersion` (string, required, nullable). Specifies health estimator version for this management ban safe health point.
    - `healthModelVersion` (string, required, nullable). Specifies health model version for this management ban safe health point.
    - `healthEvaluatedAt` (string (date-time), required, format date-time). Timestamp for health evaluated at.
    - `healthFeatureCoverage` (number, required, nullable, range 0–1). Specifies health feature coverage for this management ban safe health point.
    - `healthReliability` (string, required). Specifies health reliability for this management ban safe health point. Values: `rules_based`, `validated`, `unavailable`.
    - `healthUnavailableReason` (string, required, nullable). Specifies health unavailable reason for this management ban safe health point. Values: `no_active_model`, `invalid_active_model`, `insufficient_fresh_features`.
    - `healthProbabilities` (object, required, nullable). Specifies health probabilities for this management ban safe health point.
      - `healthy` (number, required, range 0–1). Specifies healthy for this management ban safe health probability.
      - `limited` (number, required, range 0–1). Specifies limited for this management ban safe health probability.
      - `restricted` (number, required, range 0–1). Specifies restricted for this management ban safe health probability.
      - `banned` (number, required, range 0–1). Specifies banned for this management ban safe health probability.
    - `mostLikelyHealthState` (string, required, nullable). Specifies most likely health state for this management ban safe health point. Values: `healthy`, `limited`, `restricted`, `banned`.
    - `healthExplanation` (object, required, nullable). Specifies health explanation for this management ban safe health point.
      - `penalties` (object, required). Structured penalties values for this management ban safe health explanation.
        - `conduct` (number, required, range 0–100). Specifies conduct for this penalty.
        - `delivery` (number, required, range 0–100). Specifies delivery for this penalty.
        - `connection` (number, required, range 0–100). Specifies connection for this penalty.
        - `restriction` (number, required, range 0–100). Specifies restriction for this penalty.
        - `total` (number, required, range 0–100). Final total for this order or price summary.
      - `factors` (array of object, required, max items 8). Factors associated with this management ban safe health explanation.
        - `group` (string, required). Specifies group for this management ban safe health explanation factor. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
        - `key` (string, required). Specifies key for this management ban safe health explanation factor. Values: `observed_limited`, `observed_restricted`, `observed_banned`, `send_failures`, `receipt_errors`, `server_ack_tail`, `connection_failures`, `connection_churn`, `connection_disconnected`, `auto_reconnect_errors`, `keep_alive_errors`, `unanswered_first_contacts`, `unsolicited_sends`, `send_burst`, `fixed_send_rhythm`.
        - `penalty` (number, required, range 0–100). Specifies penalty for this management ban safe health explanation factor.
        - `observedValue` (number, required). Specifies observed value for this management ban safe health explanation factor.
        - `sampleSize` (integer, required, min 0). Specifies sample size for this management ban safe health explanation factor.
      - `measuredGroups` (array of string, required, max items 5, unique items). Measured groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
      - `missingGroups` (array of string, required, max items 5, unique items). Missing groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
    - `observedAccountState` (object, required, nullable). Specifies observed account state for this management ban safe health point.
      - `state` (string, required). Current lifecycle state of this resource. Values: `healthy`, `limited`, `restricted`, `banned`.
      - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
      - `source` (string, required). Specifies source for this management ban safe observed account state. Values: `account_check`, `restriction_event`.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
        }
      }
    ]
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe signals

`GET https://api.polymorfa.com/platform/bansafe/signals` (Platform API)

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.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/signals" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `key` (string, required). Specifies key for this management ban safe signal definition.
  - `label` (string, required). Specifies label for this management ban safe signal definition.
  - `group` (string, required). Specifies group for this management ban safe signal definition.
  - `kind` (string, required). Kind discriminator for this object. Values: `number`, `boolean`, `enum`, `histogram`, `code_counts`.
  - `unit` (string, required). Specifies unit for this management ban safe signal definition. Values: `count`, `milliseconds`, `unix_milliseconds`, `ratio`, `none`.
  - `description` (string, required). Human-readable description of this resource.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "key": "string",
      "label": "string",
      "group": "string",
      "kind": "number",
      "unit": "count",
      "description": "string"
    }
  ]
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe telemetry history

`GET https://api.polymorfa.com/platform/bansafe/telemetry/{session}/history` (Platform API)

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

- `session` (string, required). Identifier of the connected Polymorfa session.

### Query parameters

- `since` (string (date-time), format date-time). Specifies since for this query parameter.
- `until` (string (date-time), format date-time). Specifies until for this query parameter.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–50). Specifies limit for this query parameter. Default: `10`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/telemetry/<session>/history" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `bucketStart` (string (date-time), required, format date-time). Specifies bucket start for this management ban safe telemetry snapshot.
  - `flushedAt` (string (date-time), required, format date-time). Timestamp for flushed at.
  - `receivedAt` (string (date-time), required, format date-time). Timestamp for received at.
  - `partial` (boolean, required). Whether partial.
  - `recordVersion` (integer, required, nullable, min 0). Specifies record version for this management ban safe telemetry snapshot.
  - `signals` (array of object, required). Signals associated with this management ban safe telemetry snapshot.
    - `key` (string, required). Specifies key for this management ban safe signal.
    - `label` (string, required). Specifies label for this management ban safe signal.
    - `group` (string, required). Specifies group for this management ban safe signal.
    - `kind` (string, required). Kind discriminator for this object. Values: `number`, `boolean`, `enum`, `histogram`, `code_counts`.
    - `unit` (string, required). Specifies unit for this management ban safe signal. Values: `count`, `milliseconds`, `unix_milliseconds`, `ratio`, `none`.
    - `description` (string, required). Human-readable description of this resource.
    - `measured` (boolean, required). Whether measured.
    - `value` (number or boolean or string or array, required, nullable). Value assigned to this field.
      - Accepts one of:
        - number
        - boolean
        - string
        - array
    - `sampleSize` (integer, required, nullable, min 0). Specifies sample size for this management ban safe signal.
    - `codes` (array of object, required, nullable). Codes associated with this management ban safe signal.
      - `code` (integer, required, min 0). Stable machine-readable code for this result.
      - `count` (integer, required, min 0). Number of matching resources.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe collection

`GET https://api.polymorfa.com/platform/bansafe/collection` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/collection" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `collection` (object, required). Specifies collection for this management ban safe collection session.
    - `state` (string, required). Current lifecycle state of this resource. Values: `fresh`, `stale`, `not_collected`, `unsupported`.
    - `latestFlushedAt` (string (date-time), required, nullable, format date-time). Timestamp for latest flushed at.
    - `latestReceivedAt` (string (date-time), required, nullable, format date-time). Timestamp for latest received at.
    - `freshUntil` (string (date-time), required, nullable, format date-time). Specifies fresh until for this management ban safe collection status.
    - `recordVersion` (integer, required, nullable, min 0). Specifies record version for this management ban safe collection status.
    - `collectorVersion` (integer, required, nullable, min 0). Specifies collector version for this management ban safe collection status.
    - `partial` (boolean, required, nullable). Whether partial.
    - `droppedRecords` (integer, required, nullable, min 0). Specifies dropped records for this management ban safe collection status.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe health actions

`GET https://api.polymorfa.com/platform/bansafe/health-actions` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `session` (string, length 1–256). Identifier of the connected Polymorfa session.
- `status` (string). Current status of this resource or operation. Values: `pending`, `running`, `succeeded`, `failed`, `cancelled`.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/health-actions" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `mode` (string, required). Operating mode selected for this feature. Values: `apply`, `clear`.
  - `action` (string, required). Action represented by this management ban safe health action. Values: `stop`, `slow_down`, `log_out`, `email`, `webhook`.
  - `status` (string, required). Current status of this resource or operation. Values: `pending`, `running`, `succeeded`, `failed`, `cancelled`.
  - `health` (number, required, range 0–100). Specifies health for this management ban safe health action.
  - `threshold` (number, required, range 0–100). Specifies threshold for this management ban safe health action.
  - `healthSource` (string, required). Specifies health source for this management ban safe health action. Values: `rules_v1`, `ml_model`.
  - `estimatorVersion` (string, required). Specifies estimator version for this management ban safe health action.
  - `modelVersion` (string, required, nullable). Specifies model version for this management ban safe health action.
  - `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this management ban safe health action.
  - `evaluatedAt` (string (date-time), required, format date-time). Timestamp for evaluated at.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `completedAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this operation completed.
  - `outcome` (string, required, nullable). Specifies outcome for this management ban safe health action. Values: `applied`, `cleared`, `notification_queued`, `superseded`, `expired`, `not_applied`, `delivery_failed`.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe findings

`GET https://api.polymorfa.com/platform/bansafe/findings` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `session` (string, length 1–256). Identifier of the connected Polymorfa session.
- `status` (string). Current status of this resource or operation. Values: `open`, `acknowledged`, `resolved`.
- `severity` (string). Specifies severity for this query parameter. Values: `info`, `warning`, `critical`.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/findings" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, nullable, format uuid). Identifier for this resource.
  - `key` (string, required, max length 64). Specifies key for this management ban safe finding.
  - `title` (string, required). Customer-visible name of the check. A `not_measured` entry carries the same title as a stored one.
  - `summary` (string, required). The evidence sentence for this finding, with the numbers from `evidence` already filled in. A number the check could not read reads as `unknown`, and a `not_measured` entry therefore reads as the sentence with no numbers in it. Empty for a key Polymorfa has retired.
  - `fix` (string, required). What to change to clear the finding. Empty for a key Polymorfa has retired.
  - `status` (string, required). Current status of this resource or operation. Values: `open`, `acknowledged`, `resolved`, `not_measured`.
  - `severity` (string, required, nullable). Specifies severity for this management ban safe finding. Values: `info`, `warning`, `critical`.
  - `occurrences` (integer, required, min 0). Specifies occurrences for this management ban safe finding.
  - `reopenedCount` (integer, required, min 0). Number of reopeneds.
  - `evidence` (object, required). Numbers only. Never message content, a message identifier, or a recipient identifier.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `firstSeenAt` (string (date-time), required, nullable, format date-time). Timestamp for first seen at.
  - `lastSeenAt` (string (date-time), required, nullable, format date-time). Timestamp for last seen at.
  - `acknowledgedAt` (string (date-time), required, nullable, format date-time). Timestamp for acknowledged at.
  - `acknowledgedBy` (string, required, nullable). Specifies acknowledged by for this management ban safe finding.
  - `acknowledgementNote` (string, required, nullable, max length 500). Specifies acknowledgement note for this management ban safe finding.
  - `snoozedUntil` (string (date-time), required, nullable, format date-time). Specifies snoozed until for this management ban safe finding.
  - `resolvedAt` (string (date-time), required, nullable, format date-time). Timestamp for resolved at.
  - `resolveReason` (string, required, nullable). Specifies resolve reason for this management ban safe finding. Values: `clean`, `key_retired`, `number_removed`, `stale`.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe enforcement

`GET https://api.polymorfa.com/platform/bansafe/enforcement` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `rung` (string). Specifies rung for this query parameter. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/enforcement" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `rung` (string, required). Specifies rung for this management ban safe enforcement summary. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
  - `previousRung` (string, required). Specifies previous rung for this management ban safe enforcement summary. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
  - `teamFloor` (string, required). Specifies team floor for this management ban safe enforcement summary. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
  - `reason` (string, required). Reason for the reported state or outcome.
  - `source` (string, required). Specifies source for this management ban safe enforcement summary. Values: `automatic`, `operator`.
  - `throughputPerMinute` (number, required, nullable). Specifies throughput per minute for this management ban safe enforcement summary.
  - `blocksUnsolicited` (boolean, required). Whether blocks unsolicited.
  - `suspended` (boolean, required). Whether suspended.
  - `health` (number, required, nullable, range 0–100). Estimate of present account Health. Higher is healthier. Read healthSource, healthReliability, and healthFeatureCoverage with it.
  - `band` (string, required). Specifies band for this management ban safe enforcement summary. Values: `good`, `fair`, `poor`, `failing`, `unknown`.
  - `healthSource` (string, required). Estimator family. rules_v1 is deterministic; unavailable carries no numeric Health. Values: `rules_v1`, `ml_model`, `unavailable`.
  - `healthEstimatorVersion` (string, required, nullable). Version of the estimator that produced Health.
  - `healthModelVersion` (string, required, nullable). Learned-model artifact version. Null for rules_v1.
  - `healthEvaluatedAt` (string (date-time), required, nullable, format date-time). Timestamp for health evaluated at.
  - `healthFeatureCoverage` (number, required, nullable, range 0–1). Specifies health feature coverage for this management ban safe enforcement summary.
  - `healthReliability` (string, required). Support category, not a confidence score. Values: `rules_based`, `validated`, `unavailable`.
  - `healthUnavailableReason` (string, required, nullable). Specifies health unavailable reason for this management ban safe enforcement summary. Values: `no_active_model`, `invalid_active_model`, `insufficient_fresh_features`.
  - `healthProbabilities` (object, required, nullable). Specifies health probabilities for this management ban safe enforcement summary.
    - `healthy` (number, required, range 0–1). Specifies healthy for this management ban safe health probability.
    - `limited` (number, required, range 0–1). Specifies limited for this management ban safe health probability.
    - `restricted` (number, required, range 0–1). Specifies restricted for this management ban safe health probability.
    - `banned` (number, required, range 0–1). Specifies banned for this management ban safe health probability.
  - `mostLikelyHealthState` (string, required, nullable). Specifies most likely health state for this management ban safe enforcement summary. Values: `healthy`, `limited`, `restricted`, `banned`.
  - `healthExplanation` (object, required, nullable). Specifies health explanation for this management ban safe enforcement summary.
    - `penalties` (object, required). Structured penalties values for this management ban safe health explanation.
      - `conduct` (number, required, range 0–100). Specifies conduct for this penalty.
      - `delivery` (number, required, range 0–100). Specifies delivery for this penalty.
      - `connection` (number, required, range 0–100). Specifies connection for this penalty.
      - `restriction` (number, required, range 0–100). Specifies restriction for this penalty.
      - `total` (number, required, range 0–100). Final total for this order or price summary.
    - `factors` (array of object, required, max items 8). Factors associated with this management ban safe health explanation.
      - `group` (string, required). Specifies group for this management ban safe health explanation factor. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
      - `key` (string, required). Specifies key for this management ban safe health explanation factor. Values: `observed_limited`, `observed_restricted`, `observed_banned`, `send_failures`, `receipt_errors`, `server_ack_tail`, `connection_failures`, `connection_churn`, `connection_disconnected`, `auto_reconnect_errors`, `keep_alive_errors`, `unanswered_first_contacts`, `unsolicited_sends`, `send_burst`, `fixed_send_rhythm`.
      - `penalty` (number, required, range 0–100). Specifies penalty for this management ban safe health explanation factor.
      - `observedValue` (number, required). Specifies observed value for this management ban safe health explanation factor.
      - `sampleSize` (integer, required, min 0). Specifies sample size for this management ban safe health explanation factor.
    - `measuredGroups` (array of string, required, max items 5, unique items). Measured groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
    - `missingGroups` (array of string, required, max items 5, unique items). Missing groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
  - `observedAccountState` (object, required, nullable). Specifies observed account state for this management ban safe enforcement summary.
    - `state` (string, required). Current lifecycle state of this resource. Values: `healthy`, `limited`, `restricted`, `banned`.
    - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
    - `source` (string, required). Specifies source for this management ban safe observed account state. Values: `account_check`, `restriction_event`.
  - `enforcement` (object, nullable). Specifies enforcement for this management ban safe enforcement summary.
    - `rung` (string, required). Specifies rung for this management ban safe number enforcement. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
    - `previousRung` (string, required). Specifies previous rung for this management ban safe number enforcement. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
    - `teamFloor` (string, required). The lowest restriction every number in this workspace is held to. Values: `none`, `notify`, `throttle`, `block_cold`, `suspend`.
    - `reason` (string, required). Reason for the reported state or outcome.
    - `source` (string, required). Specifies source for this management ban safe number enforcement. Values: `automatic`, `operator`.
    - `throughputPerMinute` (number, required, nullable). Messages per minute this number is paced to, or null when it is not paced.
    - `blocksUnsolicited` (boolean, required). First messages to people who never wrote to this number are refused outside Campaigns.
    - `suspended` (boolean, required). This number cannot originate a message. It still receives, reads, and shows presence.
    - `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
    - `eligibleLiftAt` (string (date-time), required, nullable, format date-time). Timestamp for eligible lift at.
    - `exitProgress` (integer, required, min 0). Consecutive checks already passed toward lifting.
    - `blockingFindings` (array of string, required). Blocking findings associated with this management ban safe number enforcement.
    - `operatorHold` (boolean, required). Whether operator hold.
    - `appealState` (string, required). Specifies appeal state for this management ban safe number enforcement. Values: `none`, `requested`, `granted`, `denied`.
    - `state` (string, required). `applying` while the number has not confirmed the restriction. Values: `applied`, `applying`.
  - `blockingFindings` (array of string, required). Blocking findings associated with this management ban safe enforcement summary.
  - `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
  - `eligibleLiftAt` (string (date-time), required, nullable, format date-time). Timestamp for eligible lift at.
  - `liftRequires` (string, required). Specifies lift requires for this management ban safe enforcement summary.
  - `operatorHold` (boolean, required). Whether operator hold.
  - `appealState` (string, required). Specifies appeal state for this management ban safe enforcement summary. Values: `none`, `requested`, `granted`, `denied`.
  - `state` (string, required). Current lifecycle state of this resource. Values: `applied`, `applying`.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe incidents

`GET https://api.polymorfa.com/platform/bansafe/incidents` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `session` (string, length 1–256). Identifier of the connected Polymorfa session.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/incidents" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `kind` (string, required). Kind discriminator for this object. Values: `cap_warning`, `cap_reached`, `timelock`, `temporary_ban`, `permanent_ban`, `connect_blocked`, `customer_report`.
  - `source` (string, required). Specifies source for this management ban safe incident. Values: `runtime`, `customer`.
  - `resolution` (string, required). Specifies resolution for this management ban safe incident.
  - `ambiguous` (boolean, required). Whether ambiguous.
  - `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
  - `endsAt` (string (date-time), required, nullable, format date-time). Timestamp for ends at.
  - `closedAt` (string (date-time), required, nullable, format date-time). Timestamp for closed at.
  - `closedBy` (string, required, nullable). Specifies closed by for this management ban safe incident.
  - `claimId` (string (uuid), required, nullable, format uuid). Identifier for the claim.
  - `note` (string, required, nullable, max length 500). Specifies note for this management ban safe incident.
  - `reportedBy` (string, required, nullable). Specifies reported by for this management ban safe incident.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## List ban safe claims

`GET https://api.polymorfa.com/platform/bansafe/claims` (Platform API)

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

- `projectId` (string). Identifier of the Polymorfa project that owns this resource.
- `session` (string, length 1–256). Identifier of the connected Polymorfa session.
- `status` (string). Current status of this resource or operation. Values: `filed`, `under_review`, `approved`, `denied`, `paid`, `reversed`.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/claims" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `incidentId` (string (uuid), required, format uuid). Identifier for the incident.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `filed`, `under_review`, `approved`, `denied`, `paid`, `reversed`.
  - `verdict` (string, required). Specifies verdict for this management ban safe claim. Values: `other_device`, `customer_conduct`, `shared_network`, `ours`, `inconclusive`, `simultaneous_calls`, `linked_device_interactive`.
  - `windowStart` (string (date-time), required, format date-time). Specifies window start for this management ban safe claim.
  - `windowEnd` (string (date-time), required, format date-time). Specifies window end for this management ban safe claim.
  - `measuredCents` (number, required, min 0, multiple of 0.000001). Credit quantity this number consumed inside the window, with up to six decimal places.
  - `capCents` (number, required, min 0, multiple of 0.000001). Maximum credit quantity this claim can return, with up to six decimal places.
  - `amountCents` (number, required, min 0, multiple of 0.000001). Credit quantity this claim returns, with up to six decimal places.
  - `evidence` (object, required). Specifies evidence for this management ban safe claim.
    - `attributionRuleVersion` (integer, required, nullable, min 1). Attribution rules used when the claim was filed. Null for claims filed before rule versioning.
    - `windowDays` (integer, required, min 1). Specifies window days for this management ban safe claim evidence.
    - `deviceEvidence` (boolean, required). Whether Ban Credit evidence collection is on for the project.
    - `otherDevices` (integer, required, min 0). Specifies other devices for this management ban safe claim evidence.
    - `restrictedInWindow` (boolean, required). Whether Polymorfa was restricting this number's sending inside the window.
    - `criticalFindingDays` (integer, required, min 0). Days one safety check stayed at its most serious level inside the window.
    - `sharedConnection` (boolean, required). Whether this number shared its connection with numbers that were being restricted.
    - `measuredHours` (integer, required, min 0). Hours of measured activity Polymorfa holds for the window.
    - `simultaneousCalls` (boolean, required). Whether simultaneous calls were on for this number inside the window. When true, Ban Credit does not cover the ban and the claim is denied when filed.
    - `linkedDeviceInteractive` (boolean, required). Whether this number sent an interactive message (buttons, lists, product messages, Flows and similar) from a linked device inside the window. When true, Ban Credit does not cover the ban and the claim is denied when filed. False can also mean not recorded: earlier claims report false, and sends before recording began are not backfilled.
  - `summary` (string, required). Specifies summary for this management ban safe claim.
  - `reason` (string, required). Reason for the reported state or outcome.
  - `decidedAt` (string (date-time), required, nullable, format date-time). Timestamp for decided at.
  - `paidAt` (string (date-time), required, nullable, format date-time). Timestamp for paid at.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get project health policy

`GET https://api.polymorfa.com/messaging/projects/{projectId}/health-policy` (Messaging API)

Required permission: `sessions:read`

**Required scope:** `sessions:read`

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/messaging/projects/<projectId>/health-policy" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Project health threshold and configured actions
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `version` (integer, required, min 0). Specifies version for this native project health policy.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `threshold` (integer, required, range 0–100). Specifies threshold for this native project health policy.
  - `sessionAction` (string, required). Specifies session action for this native project health policy. Values: `none`, `stop`, `slow_down`, `log_out`.
  - `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this native project health policy.
  - `emailNotification` (boolean, required). Whether email notification.
  - `webhookNotification` (boolean, required). Whether webhook notification.
  - `integrations` (object, required). Structured integrations values for this native project health policy.
    - `emailConfigured` (boolean, required). Whether email configured.
    - `webhookConfigured` (boolean, required). Whether webhook configured.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "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
    }
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get ban safe health

`GET https://api.polymorfa.com/platform/bansafe/health/{session}` (Platform API)

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

- `session` (string, required). Identifier of the connected Polymorfa session.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/health/<session>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `health` (number, required, nullable, range 0–100). Estimate of present account Health. Higher is healthier. Read healthSource, healthReliability, and healthFeatureCoverage with it.
  - `band` (string, required). Specifies band for this management ban safe number detail. Values: `good`, `fair`, `poor`, `failing`, `unknown`.
  - `healthSource` (string, required). Estimator family. rules_v1 is deterministic; unavailable carries no numeric Health. Values: `rules_v1`, `ml_model`, `unavailable`.
  - `healthEstimatorVersion` (string, required, nullable). Version of the estimator that produced Health.
  - `healthModelVersion` (string, required, nullable). Learned-model artifact version. Null for rules_v1.
  - `healthEvaluatedAt` (string (date-time), required, nullable, format date-time). Timestamp for health evaluated at.
  - `healthFeatureCoverage` (number, required, nullable, range 0–1). Specifies health feature coverage for this management ban safe number detail.
  - `healthReliability` (string, required). Support category, not a confidence score. Values: `rules_based`, `validated`, `unavailable`.
  - `healthUnavailableReason` (string, required, nullable). Specifies health unavailable reason for this management ban safe number detail. Values: `no_active_model`, `invalid_active_model`, `insufficient_fresh_features`.
  - `healthProbabilities` (object, required, nullable). Specifies health probabilities for this management ban safe number detail.
    - `healthy` (number, required, range 0–1). Specifies healthy for this management ban safe health probability.
    - `limited` (number, required, range 0–1). Specifies limited for this management ban safe health probability.
    - `restricted` (number, required, range 0–1). Specifies restricted for this management ban safe health probability.
    - `banned` (number, required, range 0–1). Specifies banned for this management ban safe health probability.
  - `mostLikelyHealthState` (string, required, nullable). Specifies most likely health state for this management ban safe number detail. Values: `healthy`, `limited`, `restricted`, `banned`.
  - `healthExplanation` (object, required, nullable). Specifies health explanation for this management ban safe number detail.
    - `penalties` (object, required). Structured penalties values for this management ban safe health explanation.
      - `conduct` (number, required, range 0–100). Specifies conduct for this penalty.
      - `delivery` (number, required, range 0–100). Specifies delivery for this penalty.
      - `connection` (number, required, range 0–100). Specifies connection for this penalty.
      - `restriction` (number, required, range 0–100). Specifies restriction for this penalty.
      - `total` (number, required, range 0–100). Final total for this order or price summary.
    - `factors` (array of object, required, max items 8). Factors associated with this management ban safe health explanation.
      - `group` (string, required). Specifies group for this management ban safe health explanation factor. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
      - `key` (string, required). Specifies key for this management ban safe health explanation factor. Values: `observed_limited`, `observed_restricted`, `observed_banned`, `send_failures`, `receipt_errors`, `server_ack_tail`, `connection_failures`, `connection_churn`, `connection_disconnected`, `auto_reconnect_errors`, `keep_alive_errors`, `unanswered_first_contacts`, `unsolicited_sends`, `send_burst`, `fixed_send_rhythm`.
      - `penalty` (number, required, range 0–100). Specifies penalty for this management ban safe health explanation factor.
      - `observedValue` (number, required). Specifies observed value for this management ban safe health explanation factor.
      - `sampleSize` (integer, required, min 0). Specifies sample size for this management ban safe health explanation factor.
    - `measuredGroups` (array of string, required, max items 5, unique items). Measured groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
    - `missingGroups` (array of string, required, max items 5, unique items). Missing groups associated with this management ban safe health explanation. Values: `direct_condition`, `delivery`, `connection`, `conduct`, `cadence`.
  - `observedAccountState` (object, required, nullable). Specifies observed account state for this management ban safe number detail.
    - `state` (string, required). Current lifecycle state of this resource. Values: `healthy`, `limited`, `restricted`, `banned`.
    - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
    - `source` (string, required). Specifies source for this management ban safe observed account state. Values: `account_check`, `restriction_event`.
  - `warmup` (object, required). Specifies warmup for this management ban safe number detail.
    - `enabled` (boolean, required). Whether this feature is enabled.
    - `tenureSource` (string, required, nullable). Retained evidence anchoring the ramp; null when legacy evidence cannot be classified. Values: `history`, `link`, `plan`.
    - `tenureDay` (integer, required, min 0). Whole days since the number's known tenure lower bound; zero when unknown.
    - `allowance` (integer, required, nullable, min 0). Messages allowed today; null when the plan is disabled.
    - `sentToday` (integer, required, nullable, min 0). Durable reservations in the active allowance window. Successful current reads return 0 before the first reservation; null remains accepted for older stored responses.
    - `resetsAt` (string (date-time), required, nullable, format date-time). Timestamp for resets at.
    - `curve` (array of object, required). Curve associated with this management ban safe number warmup.
      - `day` (integer, required, min 0). Days since the number's first proven activity.
      - `allowance` (integer, required, min 0). Messages allowed on that day.
  - `findings` (array of object, required). Findings associated with this management ban safe number detail.
    - `id` (string (uuid), required, nullable, format uuid). Identifier for this resource.
    - `key` (string, required, max length 64). Specifies key for this management ban safe finding.
    - `title` (string, required). Customer-visible name of the check. A `not_measured` entry carries the same title as a stored one.
    - `summary` (string, required). The evidence sentence for this finding, with the numbers from `evidence` already filled in. A number the check could not read reads as `unknown`, and a `not_measured` entry therefore reads as the sentence with no numbers in it. Empty for a key Polymorfa has retired.
    - `fix` (string, required). What to change to clear the finding. Empty for a key Polymorfa has retired.
    - `status` (string, required). Current status of this resource or operation. Values: `open`, `acknowledged`, `resolved`, `not_measured`.
    - `severity` (string, required, nullable). Specifies severity for this management ban safe finding. Values: `info`, `warning`, `critical`.
    - `occurrences` (integer, required, min 0). Specifies occurrences for this management ban safe finding.
    - `reopenedCount` (integer, required, min 0). Number of reopeneds.
    - `evidence` (object, required). Numbers only. Never message content, a message identifier, or a recipient identifier.
    - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
    - `session` (string, required). Identifier of the connected Polymorfa session.
    - `phoneNumber` (string, required). Phone number in international format.
    - `firstSeenAt` (string (date-time), required, nullable, format date-time). Timestamp for first seen at.
    - `lastSeenAt` (string (date-time), required, nullable, format date-time). Timestamp for last seen at.
    - `acknowledgedAt` (string (date-time), required, nullable, format date-time). Timestamp for acknowledged at.
    - `acknowledgedBy` (string, required, nullable). Specifies acknowledged by for this management ban safe finding.
    - `acknowledgementNote` (string, required, nullable, max length 500). Specifies acknowledgement note for this management ban safe finding.
    - `snoozedUntil` (string (date-time), required, nullable, format date-time). Specifies snoozed until for this management ban safe finding.
    - `resolvedAt` (string (date-time), required, nullable, format date-time). Timestamp for resolved at.
    - `resolveReason` (string, required, nullable). Specifies resolve reason for this management ban safe finding. Values: `clean`, `key_retired`, `number_removed`, `stale`.
  - `liftRequires` (string, required, nullable). The exact remaining condition for the restriction to lift.
  - `appealState` (string, required). Specifies appeal state for this management ban safe number detail. Values: `none`, `requested`, `granted`, `denied`.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get ban safe telemetry

`GET https://api.polymorfa.com/platform/bansafe/telemetry/{session}` (Platform API)

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

- `session` (string, required). Identifier of the connected Polymorfa session.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/telemetry/<session>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `collection` (object, required). Specifies collection for this management ban safe telemetry detail.
    - `state` (string, required). Current lifecycle state of this resource. Values: `fresh`, `stale`, `not_collected`, `unsupported`.
    - `latestFlushedAt` (string (date-time), required, nullable, format date-time). Timestamp for latest flushed at.
    - `latestReceivedAt` (string (date-time), required, nullable, format date-time). Timestamp for latest received at.
    - `freshUntil` (string (date-time), required, nullable, format date-time). Specifies fresh until for this management ban safe collection status.
    - `recordVersion` (integer, required, nullable, min 0). Specifies record version for this management ban safe collection status.
    - `collectorVersion` (integer, required, nullable, min 0). Specifies collector version for this management ban safe collection status.
    - `partial` (boolean, required, nullable). Whether partial.
    - `droppedRecords` (integer, required, nullable, min 0). Specifies dropped records for this management ban safe collection status.
  - `snapshot` (object, required, nullable). Specifies snapshot for this management ban safe telemetry detail.
    - `bucketStart` (string (date-time), required, format date-time). Specifies bucket start for this management ban safe telemetry snapshot.
    - `flushedAt` (string (date-time), required, format date-time). Timestamp for flushed at.
    - `receivedAt` (string (date-time), required, format date-time). Timestamp for received at.
    - `partial` (boolean, required). Whether partial.
    - `recordVersion` (integer, required, nullable, min 0). Specifies record version for this management ban safe telemetry snapshot.
    - `signals` (array of object, required). Signals associated with this management ban safe telemetry snapshot.
      - `key` (string, required). Specifies key for this management ban safe signal.
      - `label` (string, required). Specifies label for this management ban safe signal.
      - `group` (string, required). Specifies group for this management ban safe signal.
      - `kind` (string, required). Kind discriminator for this object. Values: `number`, `boolean`, `enum`, `histogram`, `code_counts`.
      - `unit` (string, required). Specifies unit for this management ban safe signal. Values: `count`, `milliseconds`, `unix_milliseconds`, `ratio`, `none`.
      - `description` (string, required). Human-readable description of this resource.
      - `measured` (boolean, required). Whether measured.
      - `value` (number or boolean or string or array, required, nullable). Value assigned to this field.
        - Accepts one of:
          - number
          - boolean
          - string
          - array
      - `sampleSize` (integer, required, nullable, min 0). Specifies sample size for this management ban safe signal.
      - `codes` (array of object, required, nullable). Codes associated with this management ban safe signal.
        - `code` (integer, required, min 0). Stable machine-readable code for this result.
        - `count` (integer, required, min 0). Number of matching resources.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
            }
          ]
        }
      ]
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get ban safe claim

`GET https://api.polymorfa.com/platform/bansafe/claims/{claimId}` (Platform API)

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

- `claimId` (string, required). Identifier for the claim.

### Request

```bash
curl "https://api.polymorfa.com/platform/bansafe/claims/<claimId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `incidentId` (string (uuid), required, format uuid). Identifier for the incident.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `filed`, `under_review`, `approved`, `denied`, `paid`, `reversed`.
  - `verdict` (string, required). Specifies verdict for this management ban safe claim. Values: `other_device`, `customer_conduct`, `shared_network`, `ours`, `inconclusive`, `simultaneous_calls`, `linked_device_interactive`.
  - `windowStart` (string (date-time), required, format date-time). Specifies window start for this management ban safe claim.
  - `windowEnd` (string (date-time), required, format date-time). Specifies window end for this management ban safe claim.
  - `measuredCents` (number, required, min 0, multiple of 0.000001). Credit quantity this number consumed inside the window, with up to six decimal places.
  - `capCents` (number, required, min 0, multiple of 0.000001). Maximum credit quantity this claim can return, with up to six decimal places.
  - `amountCents` (number, required, min 0, multiple of 0.000001). Credit quantity this claim returns, with up to six decimal places.
  - `evidence` (object, required). Specifies evidence for this management ban safe claim.
    - `attributionRuleVersion` (integer, required, nullable, min 1). Attribution rules used when the claim was filed. Null for claims filed before rule versioning.
    - `windowDays` (integer, required, min 1). Specifies window days for this management ban safe claim evidence.
    - `deviceEvidence` (boolean, required). Whether Ban Credit evidence collection is on for the project.
    - `otherDevices` (integer, required, min 0). Specifies other devices for this management ban safe claim evidence.
    - `restrictedInWindow` (boolean, required). Whether Polymorfa was restricting this number's sending inside the window.
    - `criticalFindingDays` (integer, required, min 0). Days one safety check stayed at its most serious level inside the window.
    - `sharedConnection` (boolean, required). Whether this number shared its connection with numbers that were being restricted.
    - `measuredHours` (integer, required, min 0). Hours of measured activity Polymorfa holds for the window.
    - `simultaneousCalls` (boolean, required). Whether simultaneous calls were on for this number inside the window. When true, Ban Credit does not cover the ban and the claim is denied when filed.
    - `linkedDeviceInteractive` (boolean, required). Whether this number sent an interactive message (buttons, lists, product messages, Flows and similar) from a linked device inside the window. When true, Ban Credit does not cover the ban and the claim is denied when filed. False can also mean not recorded: earlier claims report false, and sends before recording began are not backfilled.
  - `summary` (string, required). Specifies summary for this management ban safe claim.
  - `reason` (string, required). Reason for the reported state or outcome.
  - `decidedAt` (string (date-time), required, nullable, format date-time). Timestamp for decided at.
  - `paidAt` (string (date-time), required, nullable, format date-time). Timestamp for paid at.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get project safe mode ceiling

`GET https://api.polymorfa.com/platform/projects/{projectId}/safe-mode` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `ceiling` (object, required). Specifies ceiling for this management project safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode setting. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode setting. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode setting. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode setting. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this management safe mode setting.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this management safe mode setting.
  - `entitled` (boolean, required). Whether this project's plan includes BanSafe Lite, which Safe Mode is part of. When false, a request that raises a setting is refused.
  - `entitlementReason` (string, required, nullable). Why a raise would be refused. Null when the plan includes BanSafe Lite.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "ceiling": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "entitled": true,
    "entitlementReason": "string"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get number safe mode

`GET https://api.polymorfa.com/platform/sessions/{sessionId}/safe-mode` (Platform API)

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

- `sessionId` (string, required, length 1–64). Database session UUID or stable session slug.

### Request

```bash
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `project` (object, required). Specifies project for this management session safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode setting. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode setting. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode setting. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode setting. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this management safe mode setting.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this management safe mode setting.
  - `override` (object, required). Specifies override for this management session safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode override. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode override. Values: `inherit`, `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode override. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode override. Values: `inherit`, `off`, `jittered`, `conversation`.
  - `effective` (object, required). Specifies effective for this management session safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode setting. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode setting. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode setting. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode setting. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this management safe mode setting.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this management safe mode setting.
  - `applied` (object, required, nullable). Structured applied values for this management session safe mode.
    - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
    - `presence` (string, required, nullable). Specifies presence for this management safe mode applied.
    - `typing` (string, required, nullable). Specifies typing for this management safe mode applied.
    - `reads` (string, required, nullable). Specifies reads for this management safe mode applied.
    - `pacing` (string, required, nullable). Specifies pacing for this management safe mode applied.
  - `mismatch` (boolean, required). True when the number reports something other than the policy in force.
  - `entitled` (boolean, required). Whether this number's plan includes BanSafe Lite, which Safe Mode is part of. When false, a request that raises a setting is refused.
  - `entitlementReason` (string, required, nullable). Why a raise would be refused. Null when the plan includes BanSafe Lite.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get project warmup plan settings

`GET https://api.polymorfa.com/platform/projects/{projectId}/warmup-plan` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/warmup-plan" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `plan` (object, required). Specifies plan for this management project warmup plan.
    - `enabled` (boolean, required). Whether every number in this project has a daily allowance.
    - `warmupDays` (integer, required, range 1–90). Days the ramp takes to reach the per-number daily cap.
    - `dailyStart` (integer, required, range 1–2000). Messages a number may send on its first day.
  - `ceiling` (integer, required, min 1). The per-number daily cap the ramp climbs to.
  - `curve` (array of object, required, max items 91). The projected allowance day by day for a number whose health is good. A number in a lower health band gets less.
    - `day` (integer, required, min 0). Days since the number's first proven activity.
    - `allowance` (integer, required, min 0). Messages allowed on that day.
  - `entitled` (boolean, required). Whether this project's plan includes BanSafe Lite, which the warm-up plan is part of. When false, turning the warm-up plan on is refused.
  - `entitlementReason` (string, required, nullable). Why turning the plan on would be refused. Null when the plan includes BanSafe Lite.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get project health policy settings

`GET https://api.polymorfa.com/platform/projects/{projectId}/health-policy` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/health-policy" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `version` (integer, required, min 0). Revision required by the next update.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `threshold` (integer, required, range 0–100). Actions trigger only when an available health estimate is below this value.
  - `sessionAction` (string, required). Specifies session action for this management project health policy. Values: `none`, `stop`, `slow_down`, `log_out`.
  - `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this management project health policy.
  - `emailNotification` (boolean, required). Whether email notification.
  - `webhookNotification` (boolean, required). Whether webhook notification.
  - `integrations` (object, required). Specifies integrations for this management project health policy.
    - `emailConfigured` (boolean, required). Whether notification email delivery is configured.
    - `webhookConfigured` (boolean, required). Whether an enabled webhook exists for this team or project.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Get insurance evidence settings

`GET https://api.polymorfa.com/platform/projects/{projectId}/insurance-evidence` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/insurance-evidence" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `banInsuranceIncluded` (boolean, required). Whether ban insurance included.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "banInsuranceIncluded": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

## Update project health policy

`PUT https://api.polymorfa.com/messaging/projects/{projectId}/health-policy` (Messaging API)

Required permission: `sessions:manage`

**Required scope:** `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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Body

- `version` (integer, required, min 0). Specifies version for this native update project health policy input.
- `enabled` (boolean, required). Whether this feature is enabled.
- `threshold` (integer, required, range 0–100). Specifies threshold for this native update project health policy input.
- `sessionAction` (string, required). Specifies session action for this native update project health policy input. Values: `none`, `stop`, `slow_down`, `log_out`.
- `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this native update project health policy input.
- `emailNotification` (boolean, required). Whether email notification.
- `webhookNotification` (boolean, required). Whether webhook notification.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/messaging/projects/<projectId>/health-policy" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Project health policy updated
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `version` (integer, required, min 0). Specifies version for this native project health policy.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `threshold` (integer, required, range 0–100). Specifies threshold for this native project health policy.
  - `sessionAction` (string, required). Specifies session action for this native project health policy. Values: `none`, `stop`, `slow_down`, `log_out`.
  - `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this native project health policy.
  - `emailNotification` (boolean, required). Whether email notification.
  - `webhookNotification` (boolean, required). Whether webhook notification.
  - `integrations` (object, required). Structured integrations values for this native project health policy.
    - `emailConfigured` (boolean, required). Whether email configured.
    - `webhookConfigured` (boolean, required). Whether webhook configured.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "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
    }
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

Version conflict or selected notification integration unavailable
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Update project safe mode ceiling

`PUT https://api.polymorfa.com/platform/projects/{projectId}/safe-mode` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Body

- `presence` (string). Specifies presence for this management update project safe mode input. Values: `dark`, `online_while_sending`, `online_hours`.
- `typing` (string). Specifies typing for this management update project safe mode input. Values: `off`, `before_text`, `before_all`.
- `reads` (string). Specifies reads for this management update project safe mode input. Values: `off`, `replied_chats`, `all_inbound`.
- `pacing` (string). Specifies pacing for this management update project safe mode input. Values: `off`, `jittered`, `conversation`.
- `onlineStart` (integer, range 0–23). Specifies online start for this management update project safe mode input.
- `onlineEnd` (integer, range 0–23). Specifies online end for this management update project safe mode input.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `ceiling` (object, required). Specifies ceiling for this management project safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode setting. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode setting. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode setting. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode setting. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this management safe mode setting.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this management safe mode setting.
  - `entitled` (boolean, required). Whether this project's plan includes BanSafe Lite, which Safe Mode is part of. When false, a request that raises a setting is refused.
  - `entitlementReason` (string, required, nullable). Why a raise would be refused. Null when the plan includes BanSafe Lite.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "ceiling": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "entitled": true,
    "entitlementReason": "string"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 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.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "billing_error",
    "code": "safe_mode_not_entitled",
    "message": "Safe Mode is not included on this number’s plan.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#safe-mode-not-entitled"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Update number safe mode

`PUT https://api.polymorfa.com/platform/sessions/{sessionId}/safe-mode` (Platform API)

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

- `sessionId` (string, required, length 1–64). Database session UUID or stable session slug.

### Body

- `presence` (string). Specifies presence for this management update session safe mode input. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
- `typing` (string). Specifies typing for this management update session safe mode input. Values: `inherit`, `off`, `before_text`, `before_all`.
- `reads` (string). Specifies reads for this management update session safe mode input. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
- `pacing` (string). Specifies pacing for this management update session safe mode input. Values: `inherit`, `off`, `jittered`, `conversation`.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/sessions/<sessionId>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "presence": "inherit",
  "typing": "inherit",
  "reads": "inherit",
  "pacing": "inherit"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `project` (object, required). Specifies project for this management session safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode setting. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode setting. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode setting. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode setting. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this management safe mode setting.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this management safe mode setting.
  - `override` (object, required). Specifies override for this management session safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode override. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode override. Values: `inherit`, `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode override. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode override. Values: `inherit`, `off`, `jittered`, `conversation`.
  - `effective` (object, required). Specifies effective for this management session safe mode.
    - `presence` (string, required). Specifies presence for this management safe mode setting. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this management safe mode setting. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this management safe mode setting. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this management safe mode setting. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this management safe mode setting.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this management safe mode setting.
  - `applied` (object, required, nullable). Structured applied values for this management session safe mode.
    - `observedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when Polymorfa observed this state.
    - `presence` (string, required, nullable). Specifies presence for this management safe mode applied.
    - `typing` (string, required, nullable). Specifies typing for this management safe mode applied.
    - `reads` (string, required, nullable). Specifies reads for this management safe mode applied.
    - `pacing` (string, required, nullable). Specifies pacing for this management safe mode applied.
  - `mismatch` (boolean, required). True when the number reports something other than the policy in force.
  - `entitled` (boolean, required). Whether this number's plan includes BanSafe Lite, which Safe Mode is part of. When false, a request that raises a setting is refused.
  - `entitlementReason` (string, required, nullable). Why a raise would be refused. Null when the plan includes BanSafe Lite.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 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.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "billing_error",
    "code": "safe_mode_not_entitled",
    "message": "Safe Mode is not included on this number’s plan.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#safe-mode-not-entitled"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Update project warmup plan settings

`PUT https://api.polymorfa.com/platform/projects/{projectId}/warmup-plan` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Body

- `enabled` (boolean). Whether this feature is enabled.
- `warmupDays` (integer, range 1–90). Specifies warmup days for this management update project warmup plan input.
- `dailyStart` (integer, range 1–2000). Specifies daily start for this management update project warmup plan input.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/warmup-plan" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "warmupDays": 1,
  "dailyStart": 1
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `plan` (object, required). Specifies plan for this management project warmup plan.
    - `enabled` (boolean, required). Whether every number in this project has a daily allowance.
    - `warmupDays` (integer, required, range 1–90). Days the ramp takes to reach the per-number daily cap.
    - `dailyStart` (integer, required, range 1–2000). Messages a number may send on its first day.
  - `ceiling` (integer, required, min 1). The per-number daily cap the ramp climbs to.
  - `curve` (array of object, required, max items 91). The projected allowance day by day for a number whose health is good. A number in a lower health band gets less.
    - `day` (integer, required, min 0). Days since the number's first proven activity.
    - `allowance` (integer, required, min 0). Messages allowed on that day.
  - `entitled` (boolean, required). Whether this project's plan includes BanSafe Lite, which the warm-up plan is part of. When false, turning the warm-up plan on is refused.
  - `entitlementReason` (string, required, nullable). Why turning the plan on would be refused. Null when the plan includes BanSafe Lite.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 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.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "billing_error",
    "code": "warmup_plan_not_entitled",
    "message": "The warm-up plan is not included on this project’s plan.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#warmup-plan-not-entitled"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Update project health policy settings

`PUT https://api.polymorfa.com/platform/projects/{projectId}/health-policy` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Body

- `version` (integer, required, min 0). Specifies version for this management update project health policy input.
- `enabled` (boolean, required). Whether this feature is enabled.
- `threshold` (integer, required, range 0–100). Specifies threshold for this management update project health policy input.
- `sessionAction` (string, required). Specifies session action for this management update project health policy input. Values: `none`, `stop`, `slow_down`, `log_out`.
- `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this management update project health policy input.
- `emailNotification` (boolean, required). Whether email notification.
- `webhookNotification` (boolean, required). Whether webhook notification.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/health-policy" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `version` (integer, required, min 0). Revision required by the next update.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `threshold` (integer, required, range 0–100). Actions trigger only when an available health estimate is below this value.
  - `sessionAction` (string, required). Specifies session action for this management project health policy. Values: `none`, `stop`, `slow_down`, `log_out`.
  - `slowDownMps` (number, required, nullable, greater than 0). Specifies slow down mps for this management project health policy.
  - `emailNotification` (boolean, required). Whether email notification.
  - `webhookNotification` (boolean, required). Whether webhook notification.
  - `integrations` (object, required). Specifies integrations for this management project health policy.
    - `emailConfigured` (boolean, required). Whether notification email delivery is configured.
    - `webhookConfigured` (boolean, required). Whether an enabled webhook exists for this team or project.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## Update insurance evidence settings

`PUT https://api.polymorfa.com/platform/projects/{projectId}/insurance-evidence` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Body

- `enabled` (boolean, required). Whether this feature is enabled.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/projects/<projectId>/insurance-evidence" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `banInsuranceIncluded` (boolean, required). Whether ban insurance included.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "banInsuranceIncluded": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Retract ban safe incident

`POST https://api.polymorfa.com/platform/bansafe/incidents/{incidentId}/retract` (Platform API)

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

- `incidentId` (string, required). Identifier for the incident.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/bansafe/incidents/<incidentId>/retract" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `phoneNumber` (string, required). Phone number in international format.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `kind` (string, required). Kind discriminator for this object. Values: `cap_warning`, `cap_reached`, `timelock`, `temporary_ban`, `permanent_ban`, `connect_blocked`, `customer_report`.
  - `source` (string, required). Specifies source for this management ban safe incident. Values: `runtime`, `customer`.
  - `resolution` (string, required). Specifies resolution for this management ban safe incident.
  - `ambiguous` (boolean, required). Whether ambiguous.
  - `startedAt` (string (date-time), required, format date-time). Timestamp for started at.
  - `endsAt` (string (date-time), required, nullable, format date-time). Timestamp for ends at.
  - `closedAt` (string (date-time), required, nullable, format date-time). Timestamp for closed at.
  - `closedBy` (string, required, nullable). Specifies closed by for this management ban safe incident.
  - `claimId` (string (uuid), required, nullable, format uuid). Identifier for the claim.
  - `note` (string, required, nullable, max length 500). Specifies note for this management ban safe incident.
  - `reportedBy` (string, required, nullable). Specifies reported by for this management ban safe incident.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```
