# Numbers

## Endpoints

- `POST /platform/sessions/{sessionId}/start`: [Start session](https://docs.polymorfa.com/api/numbers/start-session) (Platform API)
- `GET /platform/sessions`: [List sessions](https://docs.polymorfa.com/api/numbers/list-sessions) (Platform API)
- `GET /messaging/{session}/cloud-credentials`: [Get cloud credential health](https://docs.polymorfa.com/api/numbers/get-cloud-credential-health) (Messaging API)
- `GET /platform/sessions/{sessionId}`: [Get session](https://docs.polymorfa.com/api/numbers/get-session) (Platform API)
- `GET /platform/sessions/{sessionId}/me`: [Get session account](https://docs.polymorfa.com/api/numbers/get-session-account) (Platform API)
- `POST /platform/sessions/{sessionId}/handoff-keys`: [Get handoff keys](https://docs.polymorfa.com/api/numbers/get-handoff-keys) (Platform API)
- `GET /platform/sessions/{sessionId}/tier-quotes/{quoteId}`: [Get session tier change](https://docs.polymorfa.com/api/numbers/get-session-tier-change) (Platform API)
- `GET /platform/sessions/{sessionId}/capabilities`: [Get session capabilities](https://docs.polymorfa.com/api/numbers/get-session-capabilities) (Platform API)
- `PUT /platform/sessions/{sessionId}`: [Update session](https://docs.polymorfa.com/api/numbers/update-session) (Platform API)
- `POST /messaging/{session}/cloud-credentials/reauthorize`: [Reauthorize cloud credentials](https://docs.polymorfa.com/api/numbers/reauthorize-cloud-credentials) (Messaging API)
- `PATCH /platform/sessions/{sessionId}`: [Set session tier override](https://docs.polymorfa.com/api/numbers/set-session-tier-override) (Platform API)
- `POST /platform/sessions/{sessionId}/restart`: [Restart session](https://docs.polymorfa.com/api/numbers/restart-session) (Platform API)
- `POST /platform/sessions/{sessionId}/logout`: [Logout session](https://docs.polymorfa.com/api/numbers/logout-session) (Platform API)
- `POST /platform/sessions/{sessionId}/handoff-import`: [Import handoff state](https://docs.polymorfa.com/api/numbers/import-handoff-state) (Platform API)
- `POST /platform/sessions/{sessionId}/upload-appstate-keys`: [Upload app-state keys](https://docs.polymorfa.com/api/numbers/upload-app-state-keys) (Platform API)
- `POST /platform/sessions/{sessionId}/handoff-ack`: [Confirm handoff](https://docs.polymorfa.com/api/numbers/confirm-handoff) (Platform API)
- `POST /platform/sessions/{sessionId}/tier-quotes`: [Quote session tier change](https://docs.polymorfa.com/api/numbers/quote-session-tier-change) (Platform API)
- `POST /platform/sessions/{sessionId}/inspector/claim/release`: [Release Inspector claim](https://docs.polymorfa.com/api/numbers/release-inspector-claim) (Platform API)
- `POST /platform/sessions/{sessionId}/stop`: [Stop session](https://docs.polymorfa.com/api/numbers/stop-session) (Platform API)
- `POST /platform/sessions/stop`: [Stop sessions](https://docs.polymorfa.com/api/numbers/stop-sessions) (Platform API)
- `DELETE /platform/sessions/{sessionId}`: [Delete session](https://docs.polymorfa.com/api/numbers/delete-session) (Platform API)
- `POST /platform/sessions/delete`: [Delete sessions](https://docs.polymorfa.com/api/numbers/delete-sessions) (Platform API)

## The session object

### Attributes

- `signalMode` (string). Immutable Signal key custody selected before pairing. Customer-owned custody is a gated beta for real Linked Devices. Values: `standard`, `zero_knowledge`.
- `sessionId` (string, required). Session ID. Use it to address this session in Platform and Messaging requests.
- `name` (string, required). Display label, or the session identifier when no label is set.
- `externalId` (string). Integrator correlation supplied when creating the QuickLink for this session.
- `tenantId` (string, required). Identifier of the team that owns this resource.
- `type` (string, required). How the session connects to WhatsApp. 'linked_device' pairs as a WhatsApp linked device; 'cloud_api' uses the Meta Cloud API. Immutable after create. Values: `linked_device`, `cloud_api`.
- `testMode` (boolean, required). Whether this session was created as a simulated testing number.
- `status` (string, required). Current status: CONNECTING, CONNECTED, or DISCONNECTED
- `statusReason` (string). Reason for the current status.
- `configuration` (object). Specifies configuration for this management platform access session.
  - `requestedHistory` (object, required). Structured requested history values for this management platform access session configuration view.
    - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
    - `requestFull` (boolean, required). Whether request full.
    - `delivery` (string). Polymorfa-Version 2026-10-14 and later; omitted for earlier versions. `descriptor` is direct history; `archive` is the earlier downloaded-archive delivery. Values: `archive`, `descriptor`.
  - `historyConsent` (string). Specifies history consent for this management platform access session configuration view. Values: `pending`, `accepted`, `declined`.
  - `effective` (object, required). Structured effective values for this management platform access session configuration view.
    - `observation` (object, required). Structured observation values for this effective.
      - `presenceMode` (string, required). Behavior selected for presence. Values: `off`, `events`, `cache`.
      - `typingMode` (string, required). Behavior selected for typing. Values: `off`, `events`, `cache`.
      - `labelMode` (string, required). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
      - `quickReplyMode` (string, required). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
    - `historySync` (object, required). History synchronization behavior for newly connected sessions.
      - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
      - `requestFull` (boolean, required). Whether request full.
      - `delivery` (string). Polymorfa-Version 2026-10-14 and later; omitted for earlier versions. `descriptor` is direct history; `archive` is the earlier downloaded-archive delivery. Values: `archive`, `descriptor`.
    - `hms` (object, required). Specifies hms for this effective.
      - One of:
        - `false` (object).
          - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
        - `true` (object).
          - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
          - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
          - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
          - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
          - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
          - `legalHold` (boolean). Whether legal hold.
  - `overrides` (object, required). Structured overrides values for this management platform access session configuration view.
    - `historySync` (object). History synchronization behavior for newly connected sessions.
      - `mode` (string). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
      - `requestFull` (boolean). Whether request full.
      - `delivery` (string). Polymorfa-Version 2026-10-14 and later. `descriptor` makes history.sync carry the chunk descriptor or inline payload; Polymorfa never downloads the chunk. Reset it to inherit the project or team delivery setting. Without an inherited choice, delivery is archive. Existing Numbers require confirmed cleanup before switching to descriptor delivery. Values: `descriptor`.
    - `hms` (object). Specifies hms for this override.
      - One of:
        - `false` (object).
          - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
        - `true` (object).
          - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
          - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
          - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
          - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
          - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
          - `legalHold` (boolean). Whether legal hold.
    - `observation` (object). Structured observation values for this override.
      - `presenceMode` (string). Behavior selected for presence. Values: `off`, `events`, `cache`.
      - `typingMode` (string). Behavior selected for typing. Values: `off`, `events`, `cache`.
      - `labelMode` (string). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
      - `quickReplyMode` (string). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
  - `sources` (object, required). Structured sources values for this management platform access session configuration view.
    - `observation.presenceMode` (string, required). Behavior selected for observation.presence. Values: `platform`, `team`, `project`, `session`.
    - `observation.typingMode` (string, required). Behavior selected for observation.typing. Values: `platform`, `team`, `project`, `session`.
    - `observation.labelMode` (string, required). Behavior selected for observation.label. Values: `platform`, `team`, `project`, `session`.
    - `observation.quickReplyMode` (string, required). Behavior selected for observation.quick reply. Values: `platform`, `team`, `project`, `session`.
    - `historySync.mode` (string, required). Behavior selected for history sync.mode. Values: `platform`, `team`, `project`, `session`, `consent`.
    - `historySync.requestFull` (string, required). Specifies history sync.request full for this source. Values: `platform`, `team`, `project`, `session`, `consent`.
    - `historySync.delivery` (string). Specifies history sync.delivery for this source. Values: `platform`, `team`, `project`, `session`.
    - `hms` (string, required). Specifies hms for this source. Values: `platform`, `team`, `project`, `session`.
  - `revisions` (object, required). Structured revisions values for this management platform access session configuration view.
    - `team` (integer, required, min 0). Specifies team for this revision.
    - `project` (integer, required, min 0). Specifies project for this revision.
    - `session` (integer, required, min 0). Identifier of the connected Polymorfa session.
  - `application` (object). Structured application values for this management platform access session configuration view.
    - `desiredGeneration` (integer, required, min 0). Specifies desired generation for this application.
    - `appliedGeneration` (integer, required, min 0). Specifies applied generation for this application.
    - `status` (string, required). Current status of this resource or operation. Values: `pending`, `applied`.
- `newChatCapping` (object, nullable). Specifies new chat capping for this management platform access session.
  - `enabled` (boolean, required, nullable). Whether WhatsApp enabled its new-chat cap for this number. WhatsApp decides this per number; `false` means no cap applies. `null` means WhatsApp's configuration for this number could not be read to a decision, and Polymorfa does not pace to a cap.
  - `pacing` (boolean, required). Whether Polymorfa is holding back sends that would start a new chat while the number is capped. True only when `enabled` is true.
  - `status` (string, required, nullable). The number's cap status as WhatsApp last reported it: `none`, `first_warning`, `second_warning` or `capped`. `null` until WhatsApp reported one. Reads `none` once the reported cycle has ended. Values: `none`, `first_warning`, `second_warning`, `capped`.
  - `capped` (boolean, required). True while WhatsApp reports the number capped and Polymorfa paces it (`pacing` is true), until `resetsAt`. New-chat sends are then held back; messages to existing chats still send.
  - `limit` (integer, required, nullable, min 0). New chats the number may start in the current cycle, as WhatsApp reported it.
  - `used` (integer, required, nullable, min 0). New chats started in the current cycle, as WhatsApp reported it.
  - `remaining` (integer, required, nullable, min 0). `limit` minus `used`.
  - `cycleStartsAt` (string, required, nullable). ISO 8601 start of the current cycle, when WhatsApp reported it.
  - `resetsAt` (string, required, nullable). ISO 8601 end of the current cycle as WhatsApp reported it. While Polymorfa holds a number that WhatsApp rejected for a new chat without reporting a cycle, the end of that one-hour hold.
  - `observedAt` (string, required). ISO 8601 time Polymorfa last observed this state.
- `inspector` (object). Inspector state for this Number. Returned by Get session only.
  - `claim` (object, required). Specifies claim for this inspector.
    - `claimed` (boolean, required). Whether a team member has claimed this Number in Inspector.
    - `claimedAt` (string (date-time), required, nullable, format date-time). ISO 8601 time of the current claim. Null when unclaimed.
- `createdAt` (string, required). ISO 8601 timestamp when this resource was created.
- `updatedAt` (string, required). ISO 8601 timestamp when this resource was last updated.
```json
{
  "signalMode": "standard",
  "sessionId": "string",
  "name": "string",
  "externalId": "string",
  "tenantId": "string",
  "type": "linked_device",
  "testMode": true,
  "status": "string",
  "statusReason": "string",
  "configuration": {
    "requestedHistory": {
      "mode": "metadata_only",
      "requestFull": true,
      "delivery": "archive"
    },
    "historyConsent": "pending",
    "effective": {
      "observation": {
        "presenceMode": "off",
        "typingMode": "off",
        "labelMode": "off",
        "quickReplyMode": "off"
      },
      "historySync": {
        "mode": "metadata_only",
        "requestFull": true,
        "delivery": "archive"
      },
      "hms": {
        "enabled": false
      }
    },
    "overrides": {
      "historySync": {
        "mode": "metadata_only",
        "requestFull": true,
        "delivery": "descriptor"
      },
      "hms": {
        "enabled": false
      },
      "observation": {
        "presenceMode": "off",
        "typingMode": "off",
        "labelMode": "off",
        "quickReplyMode": "off"
      }
    },
    "sources": {
      "observation.presenceMode": "platform",
      "observation.typingMode": "platform",
      "observation.labelMode": "platform",
      "observation.quickReplyMode": "platform",
      "historySync.mode": "platform",
      "historySync.requestFull": "platform",
      "historySync.delivery": "platform",
      "hms": "platform"
    },
    "revisions": {
      "team": 0,
      "project": 0,
      "session": 0
    },
    "application": {
      "desiredGeneration": 0,
      "appliedGeneration": 0,
      "status": "pending"
    }
  },
  "newChatCapping": {
    "enabled": true,
    "pacing": true,
    "status": "first_warning",
    "capped": true,
    "limit": 50,
    "used": 26,
    "remaining": 24,
    "cycleStartsAt": "string",
    "resetsAt": "string",
    "observedAt": "string"
  },
  "inspector": {
    "claim": {
      "claimed": true,
      "claimedAt": "2026-09-22T12:00:00Z"
    }
  },
  "createdAt": "string",
  "updatedAt": "string"
}
```

## Start session

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/start` (Platform API)

Required permission: `sessions:manage`

Requests an asynchronous start. Testing Numbers retain the original attempt: a ready Number resumes the same runtime, while a stopped Number requires confirmed cleanup before a successor starts. Acceptance does not mean the Number is connected. An unfinished testing invitation must resume through its original link. A hosted paid number must reserve credit before connecting; insufficient available credit returns 402. A new paid window is charged only after the messaging connection succeeds. Monthly project and number credit limits also apply: a new charge that would exceed either limit returns 409 state_conflict. Already-paid service remains available until its paid window ends. The identifier may be the session UUID or stable session slug.

Requires `sessions:manage`. Project tokens only access resources in their own project.

A start request creates an operation. Keep its operation ID and
[check the operation](https://docs.polymorfa.com/api/operations/get-account-operation) until it reaches
a terminal status. A pending or running operation does not mean the number is
connected.

If a start takes longer than expected, check the existing operation and the
number's connection status before submitting another start. Include the operation
ID when contacting support so they can inspect the same request.

### Path parameters

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

### Body

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

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/start" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "00000000-0000-4000-8000-000000000000"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `starting` (boolean, required). Whether starting. Values: `true`.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.

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": {
    "starting": true,
    "sessionId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 401

Missing/invalid credential for this audience.
- `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": "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

`billing_credit_required`: the paid number could not reserve enough available credit. Add credit to your team before starting it.
Same fields as 401.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "billing_credit_required",
    "message": "Credit is unavailable for this number. Add credit or review team billing.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#billing-credit-required"
}
```

#### 403

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

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

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

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

#### 500

The session-control publisher or testing-number persistence path is temporarily unavailable.
Same fields as 401.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: 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"
}
```

## List sessions

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

Required permission: `sessions:read`

Lists sessions in the authenticated team or selected project, including disconnected sessions and their latest status reason. A Test key returns only test numbers in its project, or an empty list when there are none. Other project tokens return all sessions in their own project.

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.

### Request

```bash
curl "https://api.polymorfa.com/platform/sessions" \
  -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 the resource.
  - `_creationTime` (number, required). Creation time as Unix epoch milliseconds.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `sessionId` (string, required, length 1–64). Identifier of the connected Polymorfa session.
  - `name` (string, required, nullable). Session identifier used to address this linked-device session.
  - `phone` (string, required, nullable). Phone number in international format.
  - `platform` (string, required, nullable). Specifies platform for this management platform session.
  - `isBusiness` (boolean, required). Whether business.
  - `testMode` (boolean, required). Behavior selected for test.
  - `tierOverride` (string, required, nullable). Specifies tier override for this management platform session. Values: `free`, `standard`, `pro`, `scale`.
  - `status` (string, required). Latest runtime connection status.
  - `statusReason` (string, required, nullable). Machine-readable reason for the latest connection status, when available.
  - `messageCount` (integer, required, min 0). Number of messages.
  - `lastActiveAt` (number, required, nullable). Last activity time as Unix epoch milliseconds.
  - `paidUntil` (number, required, nullable). End of the charged rolling 24-hour window as Unix epoch milliseconds. Null when no charged window exists; expired windows retain their expiry.
  - `customer` (object, required, nullable). Structured customer values for this management platform session.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `name` (string, required, nullable). Human-readable name for this resource.
    - `isDefault` (boolean, required). Whether default.
  - `claim` (object, required). Specifies claim for this management platform session.
    - One of:
      - `unclaimed` (object).
        - `kind` (string, required). Kind discriminator for this object. Values: `unclaimed`.
      - `claimed-elsewhere` (object).
        - `kind` (string, required). Kind discriminator for this object. Values: `claimed-elsewhere`.
        - `displayName` (string, required). Human-readable display name.
        - `avatarUrl` (string, required, nullable). URL for the avatar.
        - `avatarSeed` (string, required). Specifies avatar seed for this one of.
        - `claimedAt` (number, required). Timestamp for claimed at.
  - `inspector` (object, required). Structured inspector values for this management platform session.
    - `claim` (object, required). Specifies claim for this inspector.
      - `claimed` (boolean, required). Whether claimed.
      - `claimedAt` (string (date-time), required, nullable, format date-time). When the current claim was made. Null when unclaimed.

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",
      "_creationTime": 0,
      "projectId": "00000000-0000-4000-8000-000000000000",
      "sessionId": "string",
      "name": "string",
      "phone": "string",
      "platform": "string",
      "isBusiness": true,
      "testMode": true,
      "tierOverride": "free",
      "status": "string",
      "statusReason": "string",
      "messageCount": 0,
      "lastActiveAt": 0,
      "paidUntil": 0,
      "customer": {
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "isDefault": true
      },
      "claim": {
        "kind": "unclaimed"
      },
      "inspector": {
        "claim": {
          "claimed": true,
          "claimedAt": "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"
}
```

## Get cloud credential health

`GET https://api.polymorfa.com/messaging/{session}/cloud-credentials` (Messaging API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

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

Returns the latest recurring validation of the Number's Meta Cloud API credentials: token validity, required permissions, phone registration and webhook subscription.

### Path parameters

- `session` (string, required, length 1–128). Identifier of the connected Polymorfa session.

### Request

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

### Responses

#### 200

Credential health
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). `healthy`: every check passed. `action_required`: a check failed and the Number needs reauthorization or a change in Meta. `unknown`: Meta could not be reached or returned an incomplete answer; the check is retried. `pending`: not checked since the credentials were saved. Values: `pending`, `healthy`, `action_required`, `unknown`.
  - `checkedAt` (string (date-time), required, nullable, format date-time). When the last validation completed, or null before the first one.
  - `nextCheckAt` (string (date-time), required, nullable, format date-time). When the next scheduled validation becomes due.
  - `token` (object, required). Opaque token required by the target operation.
    - `status` (string, required). Current status of this resource or operation. Values: `valid`, `expired`, `invalid`, `unknown`.
    - `expiresAt` (string (date-time), required, nullable, format date-time). Expiry reported by Meta; null for a token without an expiry or when unknown.
  - `missingPermissions` (array of string, required). Required permissions the saved token lacks for this WhatsApp Business Account. Values: `whatsapp_business_messaging`, `whatsapp_business_management`.
  - `phoneRegistration` (string, required). Whether Meta reports the phone number as connected to the Cloud API. Values: `registered`, `not_registered`, `unknown`.
  - `webhookSubscription` (string, required). Whether the app that issued the token is subscribed to the WhatsApp Business Account's webhooks. Values: `subscribed`, `not_subscribed`, `unknown`.
  - `failureCode` (string, required, nullable). The first failed or inconclusive check, or null when healthy. Values: `app_credentials_rejected`, `token_expired`, `token_invalid`, `token_app_mismatch`, `permission_missing`, `phone_not_registered`, `webhook_not_subscribed`, `credentials_unreadable`, `meta_unavailable`, `meta_response_invalid`.

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": {
    "status": "pending",
    "checkedAt": "2026-09-22T12:00:00Z",
    "nextCheckAt": "2026-09-22T12:00:00Z",
    "token": {
      "status": "valid",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "missingPermissions": [
      "whatsapp_business_messaging"
    ],
    "phoneRegistration": "registered",
    "webhookSubscription": "subscribed",
    "failureCode": "app_credentials_rejected"
  }
}
```

#### 400

Request failed
- `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

Request failed
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

Request failed
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

Request failed
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

Request failed
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

Request failed
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"
}
```

#### 503

Request failed
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: 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"
}
```

## Get session

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

Required permission: `sessions:read`

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

### Path parameters

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

### Request

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

### Responses

#### 200

Session details
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `signalMode` (string). Immutable Signal key custody selected before pairing. Customer-owned custody is a gated beta for real Linked Devices. Values: `standard`, `zero_knowledge`.
  - `sessionId` (string, required). Session ID. Use it to address this session in Platform and Messaging requests.
  - `name` (string, required). Display label, or the session identifier when no label is set.
  - `externalId` (string). Integrator correlation supplied when creating the QuickLink for this session.
  - `tenantId` (string, required). Identifier of the team that owns this resource.
  - `type` (string, required). How the session connects to WhatsApp. 'linked_device' pairs as a WhatsApp linked device; 'cloud_api' uses the Meta Cloud API. Immutable after create. Values: `linked_device`, `cloud_api`.
  - `testMode` (boolean, required). Whether this session was created as a simulated testing number.
  - `status` (string, required). Current status: CONNECTING, CONNECTED, or DISCONNECTED
  - `statusReason` (string). Reason for the current status.
  - `configuration` (object). Specifies configuration for this management platform access session.
    - `requestedHistory` (object, required). Structured requested history values for this management platform access session configuration view.
      - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
      - `requestFull` (boolean, required). Whether request full.
      - `delivery` (string). Polymorfa-Version 2026-10-14 and later; omitted for earlier versions. `descriptor` is direct history; `archive` is the earlier downloaded-archive delivery. Values: `archive`, `descriptor`.
    - `historyConsent` (string). Specifies history consent for this management platform access session configuration view. Values: `pending`, `accepted`, `declined`.
    - `effective` (object, required). Structured effective values for this management platform access session configuration view.
      - `observation` (object, required). Structured observation values for this effective.
        - `presenceMode` (string, required). Behavior selected for presence. Values: `off`, `events`, `cache`.
        - `typingMode` (string, required). Behavior selected for typing. Values: `off`, `events`, `cache`.
        - `labelMode` (string, required). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
        - `quickReplyMode` (string, required). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
      - `historySync` (object, required). History synchronization behavior for newly connected sessions.
        - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
        - `requestFull` (boolean, required). Whether request full.
        - `delivery` (string). Polymorfa-Version 2026-10-14 and later; omitted for earlier versions. `descriptor` is direct history; `archive` is the earlier downloaded-archive delivery. Values: `archive`, `descriptor`.
      - `hms` (object, required). Specifies hms for this effective.
        - One of:
          - `false` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
          - `true` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
            - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
            - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
            - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
            - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
            - `legalHold` (boolean). Whether legal hold.
    - `overrides` (object, required). Structured overrides values for this management platform access session configuration view.
      - `historySync` (object). History synchronization behavior for newly connected sessions.
        - `mode` (string). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
        - `requestFull` (boolean). Whether request full.
        - `delivery` (string). Polymorfa-Version 2026-10-14 and later. `descriptor` makes history.sync carry the chunk descriptor or inline payload; Polymorfa never downloads the chunk. Reset it to inherit the project or team delivery setting. Without an inherited choice, delivery is archive. Existing Numbers require confirmed cleanup before switching to descriptor delivery. Values: `descriptor`.
      - `hms` (object). Specifies hms for this override.
        - One of:
          - `false` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
          - `true` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
            - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
            - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
            - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
            - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
            - `legalHold` (boolean). Whether legal hold.
      - `observation` (object). Structured observation values for this override.
        - `presenceMode` (string). Behavior selected for presence. Values: `off`, `events`, `cache`.
        - `typingMode` (string). Behavior selected for typing. Values: `off`, `events`, `cache`.
        - `labelMode` (string). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
        - `quickReplyMode` (string). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
    - `sources` (object, required). Structured sources values for this management platform access session configuration view.
      - `observation.presenceMode` (string, required). Behavior selected for observation.presence. Values: `platform`, `team`, `project`, `session`.
      - `observation.typingMode` (string, required). Behavior selected for observation.typing. Values: `platform`, `team`, `project`, `session`.
      - `observation.labelMode` (string, required). Behavior selected for observation.label. Values: `platform`, `team`, `project`, `session`.
      - `observation.quickReplyMode` (string, required). Behavior selected for observation.quick reply. Values: `platform`, `team`, `project`, `session`.
      - `historySync.mode` (string, required). Behavior selected for history sync.mode. Values: `platform`, `team`, `project`, `session`, `consent`.
      - `historySync.requestFull` (string, required). Specifies history sync.request full for this source. Values: `platform`, `team`, `project`, `session`, `consent`.
      - `historySync.delivery` (string). Specifies history sync.delivery for this source. Values: `platform`, `team`, `project`, `session`.
      - `hms` (string, required). Specifies hms for this source. Values: `platform`, `team`, `project`, `session`.
    - `revisions` (object, required). Structured revisions values for this management platform access session configuration view.
      - `team` (integer, required, min 0). Specifies team for this revision.
      - `project` (integer, required, min 0). Specifies project for this revision.
      - `session` (integer, required, min 0). Identifier of the connected Polymorfa session.
    - `application` (object). Structured application values for this management platform access session configuration view.
      - `desiredGeneration` (integer, required, min 0). Specifies desired generation for this application.
      - `appliedGeneration` (integer, required, min 0). Specifies applied generation for this application.
      - `status` (string, required). Current status of this resource or operation. Values: `pending`, `applied`.
  - `newChatCapping` (object, nullable). Specifies new chat capping for this management platform access session.
    - `enabled` (boolean, required, nullable). Whether WhatsApp enabled its new-chat cap for this number. WhatsApp decides this per number; `false` means no cap applies. `null` means WhatsApp's configuration for this number could not be read to a decision, and Polymorfa does not pace to a cap.
    - `pacing` (boolean, required). Whether Polymorfa is holding back sends that would start a new chat while the number is capped. True only when `enabled` is true.
    - `status` (string, required, nullable). The number's cap status as WhatsApp last reported it: `none`, `first_warning`, `second_warning` or `capped`. `null` until WhatsApp reported one. Reads `none` once the reported cycle has ended. Values: `none`, `first_warning`, `second_warning`, `capped`.
    - `capped` (boolean, required). True while WhatsApp reports the number capped and Polymorfa paces it (`pacing` is true), until `resetsAt`. New-chat sends are then held back; messages to existing chats still send.
    - `limit` (integer, required, nullable, min 0). New chats the number may start in the current cycle, as WhatsApp reported it.
    - `used` (integer, required, nullable, min 0). New chats started in the current cycle, as WhatsApp reported it.
    - `remaining` (integer, required, nullable, min 0). `limit` minus `used`.
    - `cycleStartsAt` (string, required, nullable). ISO 8601 start of the current cycle, when WhatsApp reported it.
    - `resetsAt` (string, required, nullable). ISO 8601 end of the current cycle as WhatsApp reported it. While Polymorfa holds a number that WhatsApp rejected for a new chat without reporting a cycle, the end of that one-hour hold.
    - `observedAt` (string, required). ISO 8601 time Polymorfa last observed this state.
  - `inspector` (object). Inspector state for this Number. Returned by Get session only.
    - `claim` (object, required). Specifies claim for this inspector.
      - `claimed` (boolean, required). Whether a team member has claimed this Number in Inspector.
      - `claimedAt` (string (date-time), required, nullable, format date-time). ISO 8601 time of the current claim. Null when unclaimed.
  - `createdAt` (string, required). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string, required). ISO 8601 timestamp when this resource was last updated.

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": {
    "sessionId": "string",
    "name": "string",
    "tenantId": "string",
    "type": "linked_device",
    "testMode": true,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

#### 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 management platform access 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 session account

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

Required permission: `sessions:read`

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

### Path parameters

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

### Request

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

### Responses

#### 200

Account info
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, pattern ^[1-9][0-9]{0,18}$). Polymorfa ID of the connected account.
  - `phoneNumber` (string). Phone number in international format.
  - `bsuid` (string). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
  - `username` (string). WhatsApp username when one is available.
  - `pushName` (string, required). WhatsApp display name reported by the sender's client.
  - `businessName` (string). Business name shown to the customer.
  - `phonePlatform` (string). Where the account's primary WhatsApp client runs. Values: `android` (WhatsApp or WhatsApp Business on an Android phone.), `ios` (WhatsApp or WhatsApp Business on an iPhone.), `meta_cloud` (Meta hosts the number through Cloud API.), `unknown` (The phone has not reported a recognized platform.).
  - `accountType` (string). How the account uses WhatsApp. Values: `whatsapp_app` (WhatsApp app, connected as a linked device.), `business_app` (WhatsApp Business app, connected as a linked device.), `meta_cloud` (Meta Cloud API.), `meta_coexistence` (Meta Cloud API, with the WhatsApp Business app still active on the phone.).
  - `profilePicUrl` (string). URL of the account's profile picture.

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": {
    "pushName": "string"
  }
}
```

#### 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 management platform access 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 handoff keys

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/handoff-keys` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

### Path parameters

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

### Request

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

### Responses

#### 200

Destination pubkey + correlation id for the handoff
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `runnerPublicKeyB64` (string, required). Curve25519 public key the customer must seal their snapshot to. Base64 (URL-safe, no padding).
  - `handoffId` (string, required). Identifier of the session handoff operation.

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": {
    "runnerPublicKeyB64": "string",
    "handoffId": "string"
  }
}
```

#### 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 management platform access 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 session tier change

`GET https://api.polymorfa.com/platform/sessions/{sessionId}/tier-quotes/{quoteId}` (Platform API)

Required permission: `sessions:read`

Reads the quote and durable result for a number in the authenticated project scope.

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.
- `quoteId` (string, required). Identifier for the quote.

### Request

```bash
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/tier-quotes/<quoteId>" \
  -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.
  - `status` (string, required). Current status of this resource or operation. Values: `quoted`, `queued`, `applied`, `rejected`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management number tier change.
  - `expiresAtMs` (integer, required). Specifies expires at ms for this management number tier change.
  - `quote` (object, required). Structured quote values for this management number tier change.
    - `tier` (string, required). Specifies tier for this quote.
    - `tierOverride` (string, required, nullable). Specifies tier override for this quote.
    - `amountCents` (number, required, min 0, multiple of 0.000001). Credits charged on application, with up to six decimal places.
    - `priceVersion` (string, required). Specifies price version for this quote.
    - `action` (string, required). Action represented by this quote. Values: `upgrade`, `downgrade`, `configure`.
    - `effectiveAtMs` (integer, required). Specifies effective at ms for this quote.
    - `replacesWindowId` (string (uuid), required, nullable, format uuid). Identifier for the replaces window.

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",
    "status": "quoted",
    "failureReason": "string",
    "expiresAtMs": 0,
    "quote": {
      "tier": "string",
      "tierOverride": "string",
      "amountCents": 0,
      "priceVersion": "string",
      "action": "upgrade",
      "effectiveAtMs": 0,
      "replacesWindowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}
```

#### 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 session capabilities

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

Required permission: `sessions:read`

Returns which WhatsApp features WhatsApp has enabled for this number, and the limits it applies, as of the number's last configuration sync. Each value reflects WhatsApp's configuration at `syncedAt`, not a live check. Values describe the WhatsApp account last linked to the number, whether or not it is connected now; read the session for its connection status. Before the first sync, from the first sync attempt of another linked WhatsApp account until its configuration is synced, and when Polymorfa cannot tell whether the stored configuration belongs to the account linked now, `status` is `unknown` and every value is null. Values come from a linked-device connection: a number that has never had one (Official API only) reports `unknown`, and a number whose linked-device connection was removed keeps the values last synced. A capability reports what WhatsApp allows the number; it does not mean the Polymorfa API offers an operation for that feature. This is a beta: teams that are not enrolled receive 403.

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>/capabilities" \
  -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). The session name.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `status` (string, required). `synced` when the values reflect WhatsApp's configuration for the account last linked to the number. `unknown` before the first sync, from the first sync attempt of another linked WhatsApp account until its configuration is synced, and when Polymorfa cannot tell whether the stored configuration belongs to the account linked now; every capability value is then null. Values: `synced`, `unknown`.
  - `syncedAt` (string (date-time), required, nullable, format date-time). When the configuration the values reflect was last read from WhatsApp. Null while `status` is `unknown`.
  - `checkedAt` (string (date-time), required, nullable, format date-time). When Polymorfa last asked WhatsApp for the number's configuration, whether or not anything changed. Null before the first request.
  - `accountType` (string, required, nullable). The WhatsApp account type the values were evaluated for. Null when not known. Values: `business`, `personal`.
  - `capabilities` (array of object, required, max items 100). Every capability, always in the same order. Ignore keys your app does not recognize; new keys can be added.
    - `key` (string, required, max length 64, pattern ^[a-z][A-Za-z]*(\.[a-z][A-Za-z]*)*$). Stable capability identifier, for example `channels` or `messageEdit.windowSeconds`. A key never changes meaning; new keys can be added.
    - `kind` (string, required). `feature`: `value` is a boolean. `limit`: `value` is an integer in `unit`. Values: `feature`, `limit`.
    - `unit` (string, required, nullable). Unit of a limit. Null for a feature. Values: `seconds`, `count`, `characters`, `members`.
    - `value` (boolean or integer, required). Boolean for a feature, integer for a limit. Null whenever `status` is `unknown`, for a capability that depends on an account type that is not known, for a limit whose WhatsApp setting is not a usable number, and for a capability Polymorfa can no longer evaluate.
      - Accepts one of:
        - boolean
        - integer
    - `source` (string, required, nullable). `server`: every WhatsApp setting the value was evaluated from was sent by WhatsApp and used as sent. `client_default`: WhatsApp's own default or limit took part, because a setting was not sent or not usable, or WhatsApp caps or replaces the value it sent. `account_type`: the capability does not apply to this account type. Null when `value` is null. Values: `server`, `client_default`, `account_type`.

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",
    "status": "synced",
    "syncedAt": "2026-09-22T12:00:00Z",
    "checkedAt": "2026-09-22T12:00:00Z",
    "accountType": "business",
    "capabilities": [
      {
        "key": "string",
        "kind": "feature",
        "unit": "seconds",
        "value": true,
        "source": "server"
      }
    ]
  }
}
```

#### 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 session

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

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

### Path parameters

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

### Body

- `configuration` (object, required). Structured configuration values for this management platform access update session request.
  - `set` (object). Structured set values for this configuration.
    - `historySync` (object). History synchronization behavior for newly connected sessions.
      - `mode` (string). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
      - `requestFull` (boolean). Whether request full.
      - `delivery` (string). Polymorfa-Version 2026-10-14 and later. `descriptor` makes history.sync carry the chunk descriptor or inline payload; Polymorfa never downloads the chunk. Reset it to inherit the project or team delivery setting. Without an inherited choice, delivery is archive. Existing Numbers require confirmed cleanup before switching to descriptor delivery. Values: `descriptor`.
    - `hms` (object). Specifies hms for this set.
      - One of:
        - `false` (object).
          - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
        - `true` (object).
          - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
          - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
          - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
          - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
          - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
          - `legalHold` (boolean). Whether legal hold.
    - `observation` (object). Structured observation values for this set.
      - `presenceMode` (string). Behavior selected for presence. Values: `off`, `events`, `cache`.
      - `typingMode` (string). Behavior selected for typing. Values: `off`, `events`, `cache`.
      - `labelMode` (string). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
      - `quickReplyMode` (string). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
  - `reset` (array of string, max items 1000). Reset associated with this configuration. Values: `historySync`, `historySync.mode`, `historySync.requestFull`, `historySync.delivery`, `hms`, `observation`, `observation.presenceMode`, `observation.typingMode`, `observation.labelMode`, `observation.quickReplyMode`.
- `revision` (integer, required, min 0). Specifies revision for this management platform access update session request.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/sessions/<sessionId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "configuration": {
    "set": {
      "historySync": {
        "mode": "metadata_only",
        "requestFull": true,
        "delivery": "descriptor"
      },
      "hms": {
        "enabled": false
      },
      "observation": {
        "presenceMode": "off",
        "typingMode": "off",
        "labelMode": "off",
        "quickReplyMode": "off"
      }
    },
    "reset": [
      "historySync"
    ]
  },
  "revision": 0
}'
```

### Responses

#### 200

Desired configuration stored; application reports pending until the runtime acknowledges
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `signalMode` (string). Immutable Signal key custody selected before pairing. Customer-owned custody is a gated beta for real Linked Devices. Values: `standard`, `zero_knowledge`.
  - `sessionId` (string, required). Session ID. Use it to address this session in Platform and Messaging requests.
  - `name` (string, required). Display label, or the session identifier when no label is set.
  - `externalId` (string). Integrator correlation supplied when creating the QuickLink for this session.
  - `tenantId` (string, required). Identifier of the team that owns this resource.
  - `type` (string, required). How the session connects to WhatsApp. 'linked_device' pairs as a WhatsApp linked device; 'cloud_api' uses the Meta Cloud API. Immutable after create. Values: `linked_device`, `cloud_api`.
  - `testMode` (boolean, required). Whether this session was created as a simulated testing number.
  - `status` (string, required). Current status: CONNECTING, CONNECTED, or DISCONNECTED
  - `statusReason` (string). Reason for the current status.
  - `configuration` (object). Specifies configuration for this management platform access session.
    - `requestedHistory` (object, required). Structured requested history values for this management platform access session configuration view.
      - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
      - `requestFull` (boolean, required). Whether request full.
      - `delivery` (string). Polymorfa-Version 2026-10-14 and later; omitted for earlier versions. `descriptor` is direct history; `archive` is the earlier downloaded-archive delivery. Values: `archive`, `descriptor`.
    - `historyConsent` (string). Specifies history consent for this management platform access session configuration view. Values: `pending`, `accepted`, `declined`.
    - `effective` (object, required). Structured effective values for this management platform access session configuration view.
      - `observation` (object, required). Structured observation values for this effective.
        - `presenceMode` (string, required). Behavior selected for presence. Values: `off`, `events`, `cache`.
        - `typingMode` (string, required). Behavior selected for typing. Values: `off`, `events`, `cache`.
        - `labelMode` (string, required). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
        - `quickReplyMode` (string, required). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
      - `historySync` (object, required). History synchronization behavior for newly connected sessions.
        - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
        - `requestFull` (boolean, required). Whether request full.
        - `delivery` (string). Polymorfa-Version 2026-10-14 and later; omitted for earlier versions. `descriptor` is direct history; `archive` is the earlier downloaded-archive delivery. Values: `archive`, `descriptor`.
      - `hms` (object, required). Specifies hms for this effective.
        - One of:
          - `false` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
          - `true` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
            - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
            - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
            - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
            - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
            - `legalHold` (boolean). Whether legal hold.
    - `overrides` (object, required). Structured overrides values for this management platform access session configuration view.
      - `historySync` (object). History synchronization behavior for newly connected sessions.
        - `mode` (string). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
        - `requestFull` (boolean). Whether request full.
        - `delivery` (string). Polymorfa-Version 2026-10-14 and later. `descriptor` makes history.sync carry the chunk descriptor or inline payload; Polymorfa never downloads the chunk. Reset it to inherit the project or team delivery setting. Without an inherited choice, delivery is archive. Existing Numbers require confirmed cleanup before switching to descriptor delivery. Values: `descriptor`.
      - `hms` (object). Specifies hms for this override.
        - One of:
          - `false` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `false`.
          - `true` (object).
            - `enabled` (boolean, required). Whether this feature is enabled. Values: `true`.
            - `region` (string, required, pattern ^[a-z0-9][a-z0-9-]{0,31}$). Specifies region for this any of.
            - `policy` (string, required). Specifies policy for this any of. Values: `short`, `standard`, `extended`, `compliance`, `enterprise_archive`.
            - `retentionDays` (integer, range 1–2555). Specifies retention days for this any of.
            - `policyVersion` (string, length 1–128). Specifies policy version for this any of.
            - `legalHold` (boolean). Whether legal hold.
      - `observation` (object). Structured observation values for this override.
        - `presenceMode` (string). Behavior selected for presence. Values: `off`, `events`, `cache`.
        - `typingMode` (string). Behavior selected for typing. Values: `off`, `events`, `cache`.
        - `labelMode` (string). Behavior selected for label. Values: `off`, `events`, `cache`, `project`.
        - `quickReplyMode` (string). Behavior selected for quick reply. Values: `off`, `events`, `cache`.
    - `sources` (object, required). Structured sources values for this management platform access session configuration view.
      - `observation.presenceMode` (string, required). Behavior selected for observation.presence. Values: `platform`, `team`, `project`, `session`.
      - `observation.typingMode` (string, required). Behavior selected for observation.typing. Values: `platform`, `team`, `project`, `session`.
      - `observation.labelMode` (string, required). Behavior selected for observation.label. Values: `platform`, `team`, `project`, `session`.
      - `observation.quickReplyMode` (string, required). Behavior selected for observation.quick reply. Values: `platform`, `team`, `project`, `session`.
      - `historySync.mode` (string, required). Behavior selected for history sync.mode. Values: `platform`, `team`, `project`, `session`, `consent`.
      - `historySync.requestFull` (string, required). Specifies history sync.request full for this source. Values: `platform`, `team`, `project`, `session`, `consent`.
      - `historySync.delivery` (string). Specifies history sync.delivery for this source. Values: `platform`, `team`, `project`, `session`.
      - `hms` (string, required). Specifies hms for this source. Values: `platform`, `team`, `project`, `session`.
    - `revisions` (object, required). Structured revisions values for this management platform access session configuration view.
      - `team` (integer, required, min 0). Specifies team for this revision.
      - `project` (integer, required, min 0). Specifies project for this revision.
      - `session` (integer, required, min 0). Identifier of the connected Polymorfa session.
    - `application` (object). Structured application values for this management platform access session configuration view.
      - `desiredGeneration` (integer, required, min 0). Specifies desired generation for this application.
      - `appliedGeneration` (integer, required, min 0). Specifies applied generation for this application.
      - `status` (string, required). Current status of this resource or operation. Values: `pending`, `applied`.
  - `newChatCapping` (object, nullable). Specifies new chat capping for this management platform access session.
    - `enabled` (boolean, required, nullable). Whether WhatsApp enabled its new-chat cap for this number. WhatsApp decides this per number; `false` means no cap applies. `null` means WhatsApp's configuration for this number could not be read to a decision, and Polymorfa does not pace to a cap.
    - `pacing` (boolean, required). Whether Polymorfa is holding back sends that would start a new chat while the number is capped. True only when `enabled` is true.
    - `status` (string, required, nullable). The number's cap status as WhatsApp last reported it: `none`, `first_warning`, `second_warning` or `capped`. `null` until WhatsApp reported one. Reads `none` once the reported cycle has ended. Values: `none`, `first_warning`, `second_warning`, `capped`.
    - `capped` (boolean, required). True while WhatsApp reports the number capped and Polymorfa paces it (`pacing` is true), until `resetsAt`. New-chat sends are then held back; messages to existing chats still send.
    - `limit` (integer, required, nullable, min 0). New chats the number may start in the current cycle, as WhatsApp reported it.
    - `used` (integer, required, nullable, min 0). New chats started in the current cycle, as WhatsApp reported it.
    - `remaining` (integer, required, nullable, min 0). `limit` minus `used`.
    - `cycleStartsAt` (string, required, nullable). ISO 8601 start of the current cycle, when WhatsApp reported it.
    - `resetsAt` (string, required, nullable). ISO 8601 end of the current cycle as WhatsApp reported it. While Polymorfa holds a number that WhatsApp rejected for a new chat without reporting a cycle, the end of that one-hour hold.
    - `observedAt` (string, required). ISO 8601 time Polymorfa last observed this state.
  - `inspector` (object). Inspector state for this Number. Returned by Get session only.
    - `claim` (object, required). Specifies claim for this inspector.
      - `claimed` (boolean, required). Whether a team member has claimed this Number in Inspector.
      - `claimedAt` (string (date-time), required, nullable, format date-time). ISO 8601 time of the current claim. Null when unclaimed.
  - `createdAt` (string, required). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string, required). ISO 8601 timestamp when this resource was last updated.

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": {
    "sessionId": "string",
    "name": "string",
    "tenantId": "string",
    "type": "linked_device",
    "testMode": true,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

#### 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 management platform access 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

Configuration revision changed or previous runtime cleanup is required before changing history delivery
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"
}
```

#### 503

Session configuration persistence is unavailable
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: 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"
}
```

## Reauthorize cloud credentials

`POST https://api.polymorfa.com/messaging/{session}/cloud-credentials/reauthorize` (Messaging API)

Required permission: `quicklink:manage`

**Protocols:** Meta Cloud API

**Required scope:** `quicklink:manage`

Requires a project token with `quicklink:manage`. Creates a QuickLink with purpose `reauthorization` that renews the Number's Meta authorization through Embedded Signup. The link is bound to the same Number and phone number and always uses the Meta Cloud API. The Number must be stopped or disconnected; this request never stops it. Cancelling the link before Meta work starts keeps the Number.

### Path parameters

- `session` (string, required, length 1–128). Identifier of the connected Polymorfa session.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/cloud-credentials/reauthorize" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 201

Reauthorization link created
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `quicklinkId` (string, required). QuickLink identifier, prefixed `ql_`. Read its progress with `GET /messaging/quicklinks/{id}`.
  - `url` (string, required). Hosted link. Share it only with the person who manages the Number's Meta assets.
  - `session` (string, required). Identifier of the connected Polymorfa session.

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": {
    "quicklinkId": "string",
    "url": "string",
    "session": "string"
  }
}
```

#### 400

Request failed
- `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 201.

```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

Request failed
Same fields as 400.

Headers:

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

```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

`entitlement_required`: the team must upgrade to Pay-As-You-Go to issue this real-number QuickLink
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "entitlement_required",
    "message": "Your team’s plan or billing mode does not include this action.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#entitlement-required"
}
```

#### 403

Request failed
Same fields as 400.

Headers:

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

```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

Request failed
Same fields as 400.

Headers:

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

```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

Request failed
Same fields as 400.

Headers:

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

```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

Request failed
Same fields as 400.

Headers:

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

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

#### 501

Request failed
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "operation_not_supported",
    "message": "This operation is not supported.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#operation-not-supported"
}
```

#### 503

Request failed
Same fields as 400.

Headers:

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

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

## Set session tier override

`PATCH https://api.polymorfa.com/platform/sessions/{sessionId}` (Platform API)

Required permission: `sessions:manage`

Confirms a previously reviewed tier quote. An upgrade purchases a full fresh 24-hour window without refunding remaining time. A downgrade applies at the paid-window end. Poll the tier quote until applied or rejected; accepting the request does not grant the new tier.

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

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

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/sessions/<sessionId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": "00000000-0000-4000-8000-000000000000"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `quoted`, `queued`, `applied`, `rejected`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management number tier change.
  - `expiresAtMs` (integer, required). Specifies expires at ms for this management number tier change.
  - `quote` (object, required). Structured quote values for this management number tier change.
    - `tier` (string, required). Specifies tier for this quote.
    - `tierOverride` (string, required, nullable). Specifies tier override for this quote.
    - `amountCents` (number, required, min 0, multiple of 0.000001). Credits charged on application, with up to six decimal places.
    - `priceVersion` (string, required). Specifies price version for this quote.
    - `action` (string, required). Action represented by this quote. Values: `upgrade`, `downgrade`, `configure`.
    - `effectiveAtMs` (integer, required). Specifies effective at ms for this quote.
    - `replacesWindowId` (string (uuid), required, nullable, format uuid). Identifier for the replaces window.

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",
    "status": "quoted",
    "failureReason": "string",
    "expiresAtMs": 0,
    "quote": {
      "tier": "string",
      "tierOverride": "string",
      "amountCents": 0,
      "priceVersion": "string",
      "action": "upgrade",
      "effectiveAtMs": 0,
      "replacesWindowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}
```

#### 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"
}
```

## Restart session

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/restart` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

Testing Numbers wait for confirmed stop before starting the same Number again. An accepted request remains pending until the Number connects. Repeating a pending request retains the same attempt; unconfirmed cleanup must be resolved before another attempt.

### Path parameters

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

### Request

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

### Responses

#### 202

Restart requested; completion is asynchronous
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `message` (string, required). Human-readable message associated with this result.
- `immediate` (boolean). Whether immediate.

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,
  "message": "string"
}
```

#### 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 management platform access public error.

Headers:

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

```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 202.

```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 202.

```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 202.

```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 202.

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

## Logout session

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/logout` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

### Path parameters

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

### Request

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

### Responses

#### 202

Session logout scheduled
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `message` (string, required). Human-readable message associated with this result.
- `immediate` (boolean). Whether immediate.

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,
  "message": "string"
}
```

#### 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 management platform access public error.

Headers:

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

```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 202.

```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 202.

```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 202.

```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 202.

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

## Import handoff state

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/handoff-import` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

### Path parameters

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

### Body

- `handoffId` (string, required). Round-trip id returned by POST /handoff-keys.
- `sealedEnvelopeB64` (string, required). Sealed-box envelope (ephemeral_pub(32) || ciphertext) wrapping the customer's SignalStoreSnapshot. Base64.
- `snapshotHashHex` (string, required). SHA-256 of the unsealed snapshot JSON, hex-encoded. The runner verifies after decrypt before flipping bartenderMode.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/handoff-import" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "handoffId": "string",
  "sealedEnvelopeB64": "string",
  "snapshotHashHex": "string"
}'
```

### Responses

#### 200

Import accepted; bartenderMode will flip after the runner acks
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `success` (boolean, required). Whether the request succeeded.
  - `message` (string). Human-readable message associated with this result.

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": {
    "success": 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 management platform access 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"
}
```

## Upload app-state keys

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/upload-appstate-keys` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

### Path parameters

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

### Body

- `keys` (array of object, required, max items 1000). Keys associated with this management platform access upload app state keys request.
  - `keyId` (string, required). Base64-encoded AppStateSyncKey id (URL-safe-no-pad).
  - `keyB64` (string, required). Base64-encoded 32-byte symmetric key bytes.
  - `fingerprintB64` (string). Base64-encoded WA fingerprint blob (optional).
  - `timestamp` (number, required). Unix-seconds timestamp WA stamped on the key.
- `upgradeTo` (string). When set, atomically flips sessions.config.bartenderMode → passthrough_plus after the keys persist. Eliminates the window where mode is set but no keys are staged. Values: `passthrough_plus`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/upload-appstate-keys" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "keys": [
    {
      "keyId": "string",
      "keyB64": "string",
      "timestamp": 0
    }
  ]
}'
```

### Responses

#### 200

Keys persisted; mode may have been flipped per upgradeTo
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `success` (boolean, required). Whether the request succeeded.
  - `message` (string). Human-readable message associated with this result.

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": {
    "success": 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 management platform access 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"
}
```

## Confirm handoff

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/handoff-ack` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

### Path parameters

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

### Body

- `handoffId` (string, required). Identifier of the session handoff operation.
- `snapshotHashHex` (string, required). SHA-256 of the snapshot the customer received via mode.handoff_export. API verifies this matches what the runner exported before flipping bartenderMode.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/handoff-ack" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "handoffId": "string",
  "snapshotHashHex": "string"
}'
```

### Responses

#### 200

Ack accepted; bartenderMode flipped from magic → passthrough
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `success` (boolean, required). Whether the request succeeded.
  - `message` (string). Human-readable message associated with this result.

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": {
    "success": 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 management platform access 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"
}
```

## Quote session tier change

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/tier-quotes` (Platform API)

Required permission: `sessions:manage`

Returns the full credit charge and effective time before confirmation. Null tierOverride restores project inheritance. Creating a quote does not change the number or consume credit. Quotes expire after ten minutes and are invalidated when the number or price changes.

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

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `tierOverride` (string, required, nullable). Specifies tier override for this management number tier quote request. Values: `free`, `standard`, `pro`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/tier-quotes" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "tierOverride": "free"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `quoted`, `queued`, `applied`, `rejected`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management number tier change.
  - `expiresAtMs` (integer, required). Specifies expires at ms for this management number tier change.
  - `quote` (object, required). Structured quote values for this management number tier change.
    - `tier` (string, required). Specifies tier for this quote.
    - `tierOverride` (string, required, nullable). Specifies tier override for this quote.
    - `amountCents` (number, required, min 0, multiple of 0.000001). Credits charged on application, with up to six decimal places.
    - `priceVersion` (string, required). Specifies price version for this quote.
    - `action` (string, required). Action represented by this quote. Values: `upgrade`, `downgrade`, `configure`.
    - `effectiveAtMs` (integer, required). Specifies effective at ms for this quote.
    - `replacesWindowId` (string (uuid), required, nullable, format uuid). Identifier for the replaces window.

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",
    "status": "quoted",
    "failureReason": "string",
    "expiresAtMs": 0,
    "quote": {
      "tier": "string",
      "tierOverride": "string",
      "amountCents": 0,
      "priceVersion": "string",
      "action": "upgrade",
      "effectiveAtMs": 0,
      "replacesWindowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}
```

#### 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"
}
```

## Release Inspector claim

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/inspector/claim/release` (Platform API)

Releases the Number's Inspector claim. Polymorfa first removes the claimant's Inspector device from the Number; the claim is released only after that succeeds. On a real Number, only the Inspector device is removed: your phone and Polymorfa's own linked device stay connected. Any team member can then claim the Number by pairing it in Inspector. A Number that is already unclaimed returns `released: false`. Pass `expectedClaimedAt` from your last read to avoid releasing a newer claim; a different current claim returns `409`. When the device cannot be removed, the Number stays claimed and the request returns `503` with `Retry-After`; repeating it is safe.

A test Number requires `sandbox:write`; a real Number requires `sessions:manage`. Project tokens only access Numbers in their own project. A signed-in Console member must be the claimant or a team owner or admin.

Releases the Number's Inspector claim after its Inspector devices are revoked.
The next claimant must pair it again. It does not transfer the claim to a
specified member.

A test Number requires `sandbox:write`; a real Number requires `sessions:manage`.
Project tokens are limited to their own project. A signed-in member must hold
the claim or be a team owner or admin. Number-restricted credentials are refused.

Send `expectedClaimedAt` from `inspector.claim.claimedAt` in your last Number
read to guard against a changed claim. A changed claim returns `409`; refresh
before deciding whether to retry. A `503` means device removal was not
confirmed. Wait for `Retry-After` and repeat with the same expected claim time.
An already unclaimed Number returns `released: false`.

On a real Number, only the Inspector companion is removed. Your phone and
Polymorfa's linked device stay connected.

### Path parameters

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

### Body

- `expectedClaimedAt` (string (date-time), format date-time). The `inspector.claim.claimedAt` value you last read. A different current claim returns 409.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/inspector/claim/release" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedClaimedAt": "2026-09-22T12:00:00Z"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `released` (boolean, required). False when the Number was already unclaimed.

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

#### 503

`service_unavailable`: the claimant's Inspector device could not be removed, so the Number is still claimed. Nothing changed. Retry after `Retry-After` seconds; repeating the request is safe.
Same fields as 400.

Headers:

- `Retry-After` (integer, min 1). Seconds to wait before retrying.
- `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"
}
```

## Stop session

`POST https://api.polymorfa.com/platform/sessions/{sessionId}/stop` (Platform API)

Required permission: `sessions:manage`

Requests an asynchronous stop for one session. The identifier may be the session UUID or stable session slug.

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

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

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/stop" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "00000000-0000-4000-8000-000000000000"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `stopping` (boolean, required). Whether stopping. Values: `true`.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.

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": {
    "stopping": true,
    "sessionId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 401

Missing/invalid credential for this audience.
- `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": "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 401.

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

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

#### 500

The session-control publisher or testing-number persistence path is temporarily unavailable.
Same fields as 401.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: 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"
}
```

## Stop sessions

`POST https://api.polymorfa.com/platform/sessions/stop` (Platform API)

Required permission: `sessions:manage`

Requests asynchronous stops for up to 100 session UUIDs or slugs in the authenticated project scope.

Requires `sessions:manage`. Project tokens only access resources in their own project.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `sessionIds` (array of string, required, items 1–100, unique items, item length 1–64). Session ids associated with this management session batch request.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/stop" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionIds": [
    "string"
  ]
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `stopping` (integer, required, range 0–100). Specifies stopping for this management session batch stop result.

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": {
    "stopping": 0
  }
}
```

#### 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"
}
```

#### 500

The session-control publisher or testing-number persistence path is temporarily unavailable.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: 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"
}
```

## Delete session

`DELETE https://api.polymorfa.com/platform/sessions/{sessionId}` (Platform API)

Required permission: `sessions:manage`

Permanently removes a testing number. Production-number deletion requires support and returns 409 without removing the number.

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.

### Request

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

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `removed` (boolean, required). Whether removed. Values: `true`.
  - `sessionId` (string (uuid), required, format uuid). Identifier of the connected Polymorfa session.

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": {
    "removed": true,
    "sessionId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 401

Missing/invalid credential for this audience.
- `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": "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 401.

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

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

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

## Delete sessions

`POST https://api.polymorfa.com/platform/sessions/delete` (Platform API)

Required permission: `sessions:manage`

Permanently removes up to 100 testing numbers. A batch containing a production number returns 409 without removing any number.

Requires `sessions:manage`. Project tokens only access resources in their own project.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `sessionIds` (array of string, required, items 1–100, unique items, item length 1–64). Session ids associated with this management session batch request.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sessions/delete" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionIds": [
    "string"
  ]
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `removed` (integer, required, range 0–100). Specifies removed for this management session batch remove result.

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": {
    "removed": 0
  }
}
```

#### 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"
}
```

#### 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"
}
```
