# QuickLinks

Saved QuickLink settings for one scope. `logoUrl` is a short-lived read URL for the saved logo.

## Endpoints

- `POST /messaging/quicklinks`: [Create quick link](https://docs.polymorfa.com/api/quicklinks/create-quick-link) (Messaging API)
- `POST /quicklink/{token}/testing/start`: [Start quick link testing](https://docs.polymorfa.com/api/quicklinks/start-quick-link-testing) (Messaging API)
- `GET /messaging/quicklinks/{id}`: [Get quick link](https://docs.polymorfa.com/api/quicklinks/get-quick-link) (Messaging API)
- `GET /quicklink/{token}`: [Get quick link state](https://docs.polymorfa.com/api/quicklinks/get-quick-link-state) (Messaging API)
- `GET /quicklink/{token}/logo`: [Get quick link logo](https://docs.polymorfa.com/api/quicklinks/get-quick-link-logo) (Messaging API)
- `GET /platform/quicklink`: [Get quick link settings](https://docs.polymorfa.com/api/quicklinks/get-quick-link-settings) (Platform API)
- `PUT /platform/quicklink`: [Update quick link settings](https://docs.polymorfa.com/api/quicklinks/update-quick-link-settings) (Platform API)
- `POST /messaging/customer-pairing/exchange`: [Exchange customer pairing link](https://docs.polymorfa.com/api/quicklinks/exchange-customer-pairing-link) (Messaging API)
- `DELETE /messaging/quicklinks/{id}`: [Cancel quick link](https://docs.polymorfa.com/api/quicklinks/cancel-quick-link) (Messaging API)
- `POST /quicklink/{token}/phone`: [Confirm quick link phone](https://docs.polymorfa.com/api/quicklinks/confirm-quick-link-phone) (Messaging API)
- `POST /quicklink/{token}/phone/reset`: [Reset quick link phone](https://docs.polymorfa.com/api/quicklinks/reset-quick-link-phone) (Messaging API)
- `POST /quicklink/{token}/connection`: [Select quick link connection](https://docs.polymorfa.com/api/quicklinks/select-quick-link-connection) (Messaging API)
- `POST /quicklink/{token}/cloud`: [Complete quick link cloud signup](https://docs.polymorfa.com/api/quicklinks/complete-quick-link-cloud-signup) (Messaging API)
- `POST /quicklink/{token}/history`: [Choose quick link history](https://docs.polymorfa.com/api/quicklinks/choose-quick-link-history) (Messaging API)
- `PATCH /quicklink/{token}/testing`: [Customize quick link testing](https://docs.polymorfa.com/api/quicklinks/customize-quick-link-testing) (Messaging API)
- `POST /quicklink/{token}/code`: [Request quick link code](https://docs.polymorfa.com/api/quicklinks/request-quick-link-code) (Messaging API)
- `POST /quicklink/{token}/confirm`: [Confirm quick link](https://docs.polymorfa.com/api/quicklinks/confirm-quick-link) (Messaging API)
- `POST /quicklink/{token}/cancel`: [Cancel quick link by token](https://docs.polymorfa.com/api/quicklinks/cancel-quick-link-by-token) (Messaging API)
- `POST /quicklink/{token}/passkey/confirmation`: [Confirm quick link passkey](https://docs.polymorfa.com/api/quicklinks/confirm-quick-link-passkey) (Messaging API)
- `POST /quicklink/{token}/passkey`: [Submit quick link passkey](https://docs.polymorfa.com/api/quicklinks/submit-quick-link-passkey) (Messaging API)

## The QuickLink object

### Attributes

- `id` (string, required). Stable QuickLink identifier, prefixed `ql_`.
- `url` (string, required). Hosted connection URL. Share it only with the person holding the phone.
- `session` (string, required). Session name that receives the connected number.
- `expiresAt` (string, required, nullable). Null for new persistent QuickLinks. Legacy links retain their ISO-8601 expiry.
```json
{
  "id": "string",
  "url": "string",
  "session": "string",
  "expiresAt": "string"
}
```

## The QuickLink state object

### Attributes

- `testing` (object, required, nullable). Structured testing values for this native quick link state.
  - `country` (string, required). ISO 3166-1 alpha-2 country code.
  - `configuration` (object, required). Structured configuration values for this testing.
    - `profile` (object). Structured profile values for this configuration.
      - `name` (string, length 1–128). Human-readable name for this resource.
      - `status` (string, max length 139). Current status of this resource or operation.
    - `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.).
    - `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
    - `replyBehavior` (string). Specifies reply behavior for this configuration. Values: `off`, `echo`.
    - `failureScenario` (string). Specifies failure scenario for this configuration. Values: `none`, `reject-send`.
    - `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.
  - `editable` (array of string, required). Editable associated with this testing. Values: `profile.name`, `profile.status`, `accountType`, `primaryPlatform`, `replyBehavior`, `failureScenario`, `historyFixtureId`.
  - `state` (string, required). Current lifecycle state of this resource. Values: `pending`, `starting`, `ready`.
  - `phone` (string, required). Phone number in international format.
- `historyConfiguration` (object, required, nullable). Structured history configuration values for this native quick link state.
  - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
  - `requestFull` (boolean, required). Whether request full.
- `historyConsent` (string, required, nullable). Specifies history consent for this native quick link state. Values: `pending`, `accepted`, `declined`.
- `id` (string, required). Identifier for this resource.
- `status` (string, required). Current status of this resource or operation. Values: `pending`, `opened`, `linked`, `connected`, `failed`, `cancelled`.
- `expiresAt` (string, required, nullable). ISO 8601 timestamp when this resource expires.
- `redirectUrl` (string (uri), nullable, format uri). Snapshotted failure callback for a failed link. Omitted for non-failed states.
- `connections` (array of string, required). Connections associated with this native quick link state. Values: `cloud`, `linked`.
- `selectedConnection` (string, required, nullable). Specifies selected connection for this native quick link state. Values: `cloud`, `linked`.
- `connectionPreference` (string, required). Specifies connection preference for this native quick link state. Values: `cloud`, `linked`, `both`.
- `connectionEnforcement` (string, required). Specifies connection enforcement for this native quick link state. Values: `prefer`, `force`.
- `cloud` (object, required, nullable). Structured cloud values for this native quick link state.
  - `appId` (string, required). Identifier of the connected application.
  - `configId` (string, required). Identifier for the config.
- `onboarding` (object, required, nullable). Structured onboarding values for this native quick link state.
  - `stage` (string, required). Specifies stage for this onboarding.
  - `connection` (string, required, nullable). Specifies connection for this onboarding.
  - `coexistence` (boolean, required, nullable). Whether coexistence.
  - `contactsSync` (string, required). Specifies contacts sync for this onboarding.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions.
  - `historyProgress` (integer, required, range 0–100). Specifies history progress for this onboarding.
  - `errorCode` (string, required, nullable). Machine-readable error code for this onboarding.
  - `sync` (object, required). Specifies sync for this onboarding.
    - `contacts` (object, required). Contacts returned or affected by this operation.
      - `request` (string, required). Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
      - `receiptRecorded` (boolean, required). Whether receipt recorded.
    - `history` (object, required). Structured history values for this native cloud sync status.
      - `request` (string, required). Specifies request for this history. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
      - `receiptRecorded` (boolean, required). Whether receipt recorded.
      - `delivery` (string, required). Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists. Values: `not_applicable`, `not_requested`, `unconfirmed`, `partial`, `complete`, `declined`.
- `methods` (array of string, required). Connection methods enabled for the widget. Values: `qr`, `pairing`.
- `defaultMethod` (string, required, nullable). Specifies default method for this native quick link state. Values: `qr`, `pairing`.
- `businessName` (string, required). Business name shown to the customer.
- `headline` (string, required, nullable). Specifies headline for this native quick link state.
- `description` (string, required, nullable). Human-readable description of this resource.
- `successMessage` (string, required, nullable). Specifies success message for this native quick link state.
- `supportUrl` (string, required, nullable). URL for the support.
- `privacyUrl` (string, required, nullable). URL for the privacy.
- `termsUrl` (string, required, nullable). URL for the terms.
- `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
- `accent` (string, required, nullable). Specifies accent for this native quick link state.
- `shape` (string, required, nullable). Specifies shape for this native quick link state. Values: `square`, `rounded`, `pill`.
- `radiusPx` (number, required, nullable). Specifies radius px for this native quick link state.
- `logoUrl` (string, required, nullable). URL for the logo.
- `hideWatermark` (boolean, required). Whether hide watermark.
- `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
- `phoneStep` (object, required). Structured phone step values for this native quick link state.
  - `confirmed` (boolean, required). Whether confirmed.
  - `allowChange` (boolean, required). Whether allow change.
  - `noNumber` (boolean, required). Whether no number.
  - `allowNoNumber` (boolean, required). Whether allow no number.
- `prefillPhone` (string, required, nullable). Specifies prefill phone for this native quick link state.
- `phoneIdentity` (object, required, nullable). Structured phone identity values for this native quick link state.
  - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
  - `phone` (string, required). Phone number in international format.
  - `whatsappPhone` (string, required, nullable). Specifies whatsapp phone for this phone identity.
  - `accountType` (string, required). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.
  - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
  - `pictureUrl` (string (uri), required, nullable, format uri). URL for the picture.
- `customer` (boolean, required). True when the link assigns the number to a Customer.
- `session` (object, required). Identifier of the connected Polymorfa session.
  - `status` (string, required). Current status of this resource or operation.
  - `phone` (string, required, nullable). Phone number in international format.
- `qrSvg` (string, required, nullable). Inline SVG of the current WhatsApp QR code, when the QR method is offered and the number is not linked yet.
- `passkeyAvailable` (boolean). Whether passkey pairing is available. State reads and cancellation remain available when false.
- `passkeyConfirmation` (object, nullable). Structured passkey confirmation values for this native quick link state.
  - `status` (string, required). Current status of this resource or operation. Values: `none`, `challenge_pending`, `assertion_sending`, `assertion_submitted`, `code_available`, `confirmation_sending`, `waiting_for_pairing`, `completed`, `failed`.
  - `ticketId` (string). Identifier for the ticket.
  - `code` (string). Stable machine-readable code for this result.
  - `skipHandoffUX` (boolean). Whether skip handoff ux.
  - `error` (string). Error details returned when the operation fails.
- `passkey` (object, nullable). Pending passkey challenge ticket for WebAuthn authentication.
  - `ticket` (string, required). Specifies ticket for this passkey.
  - `challengeB64Url` (string, required). URL for the challenge b64.
  - `rpId` (string, required). Identifier for the rp.
  - `userVerification` (string, required). Specifies user verification for this passkey. Values: `preferred`, `required`, `discouraged`.
  - `expiresAt` (string, required). ISO 8601 timestamp when this resource expires.
  - `timeoutMs` (integer). Specifies timeout ms for this passkey.
- `tunnelAvailable` (boolean). Whether a new secure pairing channel may currently be admitted for this link.
- `errorCode` (string, required, nullable). Machine-readable error code for this native quick link state.
```json
{
  "testing": {
    "country": "string",
    "configuration": {
      "profile": {
        "name": "string",
        "status": "string"
      },
      "accountType": "whatsapp_app",
      "primaryPlatform": "android",
      "replyBehavior": "off",
      "failureScenario": "none",
      "historyFixtureId": "00000000-0000-4000-8000-000000000000"
    },
    "editable": [
      "profile.name"
    ],
    "state": "pending",
    "phone": "string"
  },
  "historyConfiguration": {
    "mode": "metadata_only",
    "requestFull": true
  },
  "historyConsent": "pending",
  "id": "string",
  "status": "pending",
  "expiresAt": "string",
  "redirectUrl": "https://example.com",
  "connections": [
    "cloud"
  ],
  "selectedConnection": "cloud",
  "connectionPreference": "cloud",
  "connectionEnforcement": "prefer",
  "cloud": {
    "appId": "string",
    "configId": "string"
  },
  "onboarding": {
    "stage": "string",
    "connection": "string",
    "coexistence": true,
    "contactsSync": "string",
    "historySync": "string",
    "historyProgress": 0,
    "errorCode": "string",
    "sync": {
      "contacts": {
        "request": "not_applicable",
        "receiptRecorded": true
      },
      "history": {
        "request": "not_applicable",
        "receiptRecorded": true,
        "delivery": "not_applicable"
      }
    }
  },
  "methods": [
    "qr"
  ],
  "defaultMethod": "qr",
  "businessName": "string",
  "headline": "string",
  "description": "string",
  "successMessage": "string",
  "supportUrl": "string",
  "privacyUrl": "string",
  "termsUrl": "string",
  "theme": "light",
  "accent": "string",
  "shape": "square",
  "radiusPx": 0,
  "logoUrl": "string",
  "hideWatermark": true,
  "historySync": "ask",
  "phoneStep": {
    "confirmed": true,
    "allowChange": true,
    "noNumber": true,
    "allowNoNumber": true
  },
  "prefillPhone": "string",
  "phoneIdentity": {
    "registered": true,
    "phone": "string",
    "whatsappPhone": "string",
    "accountType": "whatsapp",
    "pushName": "string",
    "pictureUrl": "https://example.com"
  },
  "customer": true,
  "session": {
    "status": "string",
    "phone": "string"
  },
  "qrSvg": "string",
  "passkeyAvailable": true,
  "passkeyConfirmation": {
    "status": "none",
    "ticketId": "string",
    "code": "string",
    "skipHandoffUX": true,
    "error": "string"
  },
  "passkey": {
    "ticket": "string",
    "challengeB64Url": "string",
    "rpId": "string",
    "userVerification": "preferred",
    "expiresAt": "string",
    "timeoutMs": 0
  },
  "tunnelAvailable": true,
  "errorCode": "string"
}
```

## The QuickLink settings object

Saved QuickLink settings for one scope. `logoUrl` is a short-lived read URL for the saved logo.

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `projectId` (string (uuid), required, nullable, format uuid). Identifier of the Polymorfa project that owns this resource.
- `enabled` (boolean, required). Whether this feature is enabled.
- `successCallbackUrl` (string (uri), required, nullable, format uri). Project-owned HTTPS destination after connection confirmation.
- `failureCallbackUrl` (string (uri), required, nullable, format uri). Project-owned HTTPS destination after cancellation.
- `businessName` (string, required, nullable). Business name shown to the customer.
- `headline` (string, required, nullable). Specifies headline for this management quick link setting.
- `description` (string, required, nullable). Human-readable description of this resource.
- `successMessage` (string, required, nullable). Specifies success message for this management quick link setting.
- `supportUrl` (string, required, nullable). URL for the support.
- `privacyUrl` (string, required, nullable). URL for the privacy.
- `termsUrl` (string, required, nullable). URL for the terms.
- `accent` (string, required, nullable). Specifies accent for this management quick link setting.
- `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
- `hideWatermark` (boolean, required). Saved preference to hide Powered by Polymorfa. QuickLink pages hide it only while the team is active and has a Branded QuickLink add-on.
- `allowPhoneChange` (boolean, required). Allow recipients to change a prefilled phone number. Defaults to false.
- `shape` (string, required, nullable). Specifies shape for this management quick link setting. Values: `square`, `rounded`, `pill`.
- `radiusPx` (number, required, nullable). Specifies radius px for this management quick link setting.
- `logoMode` (string, required). Behavior selected for logo. Values: `none`, `custom`, `team`, `project`.
- `logoStorageId` (string, required, nullable). Identifier for the logo storage.
- `logoSourceStorageId` (string, required, nullable). Identifier for the logo source storage.
- `logoUrl` (string, required, nullable). URL for the logo.
- `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
- `methods` (array of string, required, nullable). Connection methods enabled for the widget. Values: `qr`, `pairing`.
- `defaultMethod` (string, required, nullable). Specifies default method for this management quick link setting. Values: `qr`, `pairing`.
- `createdAt` (integer, required). Unix timestamp in milliseconds when this resource was created.
- `updatedAt` (integer, required). Unix timestamp in milliseconds when this resource was last updated.
```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "enabled": true,
  "successCallbackUrl": "https://example.com",
  "failureCallbackUrl": "https://example.com",
  "businessName": "string",
  "headline": "string",
  "description": "string",
  "successMessage": "string",
  "supportUrl": "string",
  "privacyUrl": "string",
  "termsUrl": "string",
  "accent": "string",
  "theme": "light",
  "hideWatermark": true,
  "allowPhoneChange": true,
  "shape": "square",
  "radiusPx": 0,
  "logoMode": "none",
  "logoStorageId": "string",
  "logoSourceStorageId": "string",
  "logoUrl": "string",
  "historySync": "ask",
  "methods": [
    "qr"
  ],
  "defaultMethod": "qr",
  "createdAt": 0,
  "updatedAt": 0
}
```

## Create quick link

`POST https://api.polymorfa.com/messaging/quicklinks` (Messaging API)

Required permission: `quicklink:manage`

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

Creates a persistent hosted link that connects one WhatsApp number to a new session in the project.

### Body

- `signalMode` (string). Signal key custody for a new Number. Inherits Customer then Project default; cannot change an existing Number. Customer-owned custody requires beta admission and real Linked Devices. Values: `standard`, `zero_knowledge`.
- `projectId` (string (uuid), format uuid). Project that receives the connected number. Required for team keys with more than one project.
- `customerId` (string (uuid), format uuid). Customer that owns the connected number when Customers is enabled for the project.
- `billingControls` (object). Initial monthly spending limit and funding priority for a real Number. Requires a team key with billing:manage or a live team owner/admin on Pay-As-You-Go. Applied atomically before pairing admission.
  - `limitCredits` (number, required, nullable, range 0–1000000). Specifies limit credits for this billing control.
  - `priority` (integer, required, range 0–1000000). Specifies priority for this billing control.
- `externalId` (string, length 1–256, pattern ^[^\x00-\x1f\x7f]+$). Integrator correlation copied to the resulting session. May repeat across invitations; does not grant access.
- `configuration` (object). Specifies configuration for this native create quick link request.
  - `testing` (object). Structured testing values for this native quick link configuration.
    - `country` (string). ISO 3166-1 alpha-2 country code.
    - `configuration` (object). Structured configuration values for this testing.
      - `profile` (object). Structured profile values for this configuration.
        - `name` (string, length 1–128). Human-readable name for this resource.
        - `status` (string, max length 139). Current status of this resource or operation.
      - `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.).
      - `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
      - `replyBehavior` (string). Specifies reply behavior for this configuration. Values: `off`, `echo`.
      - `failureScenario` (string). Specifies failure scenario for this configuration. Values: `none`, `reject-send`.
      - `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.
    - `editable` (array of string, max items 3). Editable associated with this testing. Values: `profile.name`, `profile.status`, `accountType`, `primaryPlatform`, `replyBehavior`, `failureScenario`, `historyFixtureId`.
  - `prefillPhone` (string, pattern ^\+?\d{6,15}$). Specifies prefill phone for this native quick link configuration.
  - `connectionPreference` (string). Specifies connection preference for this native quick link configuration. Values: `cloud`, `linked`, `both`.
  - `connectionEnforcement` (string). Specifies connection enforcement for this native quick link configuration. Values: `prefer`, `force`.
  - `methods` (array of string, items 1–2). Linked Devices methods offered for this connection. Values: `qr`, `pairing`.
  - `defaultMethod` (string, nullable). Linked Devices method opened first. Omit to inherit the saved project setting, or set null to choose by recipient device. Values: `qr`, `pairing`.
  - `allowPhoneChange` (boolean). Whether allow phone change.
  - `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` keeps history chunks with the recipient for local processing. Omit to inherit saved defaults. Recipient history consent remains required. Values: `descriptor`.
    - `consent` (string). Specifies consent for this history sync. Values: `ask`, `force_on`, `force_off`.
  - `hms` (object). Specifies hms for this native quick link configuration.
    - 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 native quick link configuration.
    - `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`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/quicklinks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "signalMode": "standard",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "customerId": "00000000-0000-4000-8000-000000000000",
  "billingControls": {
    "limitCredits": 0,
    "priority": 0
  },
  "externalId": "string",
  "configuration": {
    "testing": {
      "country": "string",
      "configuration": {
        "profile": {
          "name": "string",
          "status": "string"
        },
        "accountType": "whatsapp_app",
        "primaryPlatform": "android",
        "replyBehavior": "off",
        "failureScenario": "none",
        "historyFixtureId": "00000000-0000-4000-8000-000000000000"
      },
      "editable": [
        "profile.name"
      ]
    },
    "prefillPhone": "string",
    "connectionPreference": "cloud",
    "connectionEnforcement": "prefer",
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "allowPhoneChange": true,
    "historySync": {
      "mode": "metadata_only",
      "requestFull": true,
      "delivery": "descriptor",
      "consent": "ask"
    },
    "hms": {
      "enabled": false
    },
    "observation": {
      "presenceMode": "off",
      "typingMode": "off",
      "labelMode": "off",
      "quickReplyMode": "off"
    }
  }
}'
```

### Responses

#### 201

QuickLink created
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, required). Stable QuickLink identifier, prefixed `ql_`.
  - `url` (string, required). Hosted connection URL. Share it only with the person holding the phone.
  - `session` (string, required). Session name that receives the connected number.
  - `expiresAt` (string, required, nullable). Null for new persistent QuickLinks. Legacy links retain their ISO-8601 expiry.

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": {
    "id": "string",
    "url": "string",
    "session": "string",
    "expiresAt": "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 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

Missing or invalid authentication token
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"
}
```

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

Resource not found
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"
}
```

#### 500

Internal server error
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"
}
```

## Start quick link testing

`POST https://api.polymorfa.com/quicklink/{token}/testing/start` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/testing/start" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Current test connection state
- `data` (object, required). Structured data carried by this object.
  - `testing` (object, required, nullable). Structured testing values for this native quick link state.
    - `country` (string, required). ISO 3166-1 alpha-2 country code.
    - `configuration` (object, required). Structured configuration values for this testing.
      - `profile` (object). Structured profile values for this configuration.
        - `name` (string, length 1–128). Human-readable name for this resource.
        - `status` (string, max length 139). Current status of this resource or operation.
      - `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.).
      - `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
      - `replyBehavior` (string). Specifies reply behavior for this configuration. Values: `off`, `echo`.
      - `failureScenario` (string). Specifies failure scenario for this configuration. Values: `none`, `reject-send`.
      - `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.
    - `editable` (array of string, required). Editable associated with this testing. Values: `profile.name`, `profile.status`, `accountType`, `primaryPlatform`, `replyBehavior`, `failureScenario`, `historyFixtureId`.
    - `state` (string, required). Current lifecycle state of this resource. Values: `pending`, `starting`, `ready`.
    - `phone` (string, required). Phone number in international format.
  - `historyConfiguration` (object, required, nullable). Structured history configuration values for this native quick link state.
    - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
    - `requestFull` (boolean, required). Whether request full.
  - `historyConsent` (string, required, nullable). Specifies history consent for this native quick link state. Values: `pending`, `accepted`, `declined`.
  - `id` (string, required). Identifier for this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `pending`, `opened`, `linked`, `connected`, `failed`, `cancelled`.
  - `expiresAt` (string, required, nullable). ISO 8601 timestamp when this resource expires.
  - `redirectUrl` (string (uri), nullable, format uri). Snapshotted failure callback for a failed link. Omitted for non-failed states.
  - `connections` (array of string, required). Connections associated with this native quick link state. Values: `cloud`, `linked`.
  - `selectedConnection` (string, required, nullable). Specifies selected connection for this native quick link state. Values: `cloud`, `linked`.
  - `connectionPreference` (string, required). Specifies connection preference for this native quick link state. Values: `cloud`, `linked`, `both`.
  - `connectionEnforcement` (string, required). Specifies connection enforcement for this native quick link state. Values: `prefer`, `force`.
  - `cloud` (object, required, nullable). Structured cloud values for this native quick link state.
    - `appId` (string, required). Identifier of the connected application.
    - `configId` (string, required). Identifier for the config.
  - `onboarding` (object, required, nullable). Structured onboarding values for this native quick link state.
    - `stage` (string, required). Specifies stage for this onboarding.
    - `connection` (string, required, nullable). Specifies connection for this onboarding.
    - `coexistence` (boolean, required, nullable). Whether coexistence.
    - `contactsSync` (string, required). Specifies contacts sync for this onboarding.
    - `historySync` (string, required). History synchronization behavior for newly connected sessions.
    - `historyProgress` (integer, required, range 0–100). Specifies history progress for this onboarding.
    - `errorCode` (string, required, nullable). Machine-readable error code for this onboarding.
    - `sync` (object, required). Specifies sync for this onboarding.
      - `contacts` (object, required). Contacts returned or affected by this operation.
        - `request` (string, required). Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
      - `history` (object, required). Structured history values for this native cloud sync status.
        - `request` (string, required). Specifies request for this history. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
        - `delivery` (string, required). Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists. Values: `not_applicable`, `not_requested`, `unconfirmed`, `partial`, `complete`, `declined`.
  - `methods` (array of string, required). Connection methods enabled for the widget. Values: `qr`, `pairing`.
  - `defaultMethod` (string, required, nullable). Specifies default method for this native quick link state. Values: `qr`, `pairing`.
  - `businessName` (string, required). Business name shown to the customer.
  - `headline` (string, required, nullable). Specifies headline for this native quick link state.
  - `description` (string, required, nullable). Human-readable description of this resource.
  - `successMessage` (string, required, nullable). Specifies success message for this native quick link state.
  - `supportUrl` (string, required, nullable). URL for the support.
  - `privacyUrl` (string, required, nullable). URL for the privacy.
  - `termsUrl` (string, required, nullable). URL for the terms.
  - `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `accent` (string, required, nullable). Specifies accent for this native quick link state.
  - `shape` (string, required, nullable). Specifies shape for this native quick link state. Values: `square`, `rounded`, `pill`.
  - `radiusPx` (number, required, nullable). Specifies radius px for this native quick link state.
  - `logoUrl` (string, required, nullable). URL for the logo.
  - `hideWatermark` (boolean, required). Whether hide watermark.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
  - `phoneStep` (object, required). Structured phone step values for this native quick link state.
    - `confirmed` (boolean, required). Whether confirmed.
    - `allowChange` (boolean, required). Whether allow change.
    - `noNumber` (boolean, required). Whether no number.
    - `allowNoNumber` (boolean, required). Whether allow no number.
  - `prefillPhone` (string, required, nullable). Specifies prefill phone for this native quick link state.
  - `phoneIdentity` (object, required, nullable). Structured phone identity values for this native quick link state.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string, required, nullable). Specifies whatsapp phone for this phone identity.
    - `accountType` (string, required). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string (uri), required, nullable, format uri). URL for the picture.
  - `customer` (boolean, required). True when the link assigns the number to a Customer.
  - `session` (object, required). Identifier of the connected Polymorfa session.
    - `status` (string, required). Current status of this resource or operation.
    - `phone` (string, required, nullable). Phone number in international format.
  - `qrSvg` (string, required, nullable). Inline SVG of the current WhatsApp QR code, when the QR method is offered and the number is not linked yet.
  - `passkeyAvailable` (boolean). Whether passkey pairing is available. State reads and cancellation remain available when false.
  - `passkeyConfirmation` (object, nullable). Structured passkey confirmation values for this native quick link state.
    - `status` (string, required). Current status of this resource or operation. Values: `none`, `challenge_pending`, `assertion_sending`, `assertion_submitted`, `code_available`, `confirmation_sending`, `waiting_for_pairing`, `completed`, `failed`.
    - `ticketId` (string). Identifier for the ticket.
    - `code` (string). Stable machine-readable code for this result.
    - `skipHandoffUX` (boolean). Whether skip handoff ux.
    - `error` (string). Error details returned when the operation fails.
  - `passkey` (object, nullable). Pending passkey challenge ticket for WebAuthn authentication.
    - `ticket` (string, required). Specifies ticket for this passkey.
    - `challengeB64Url` (string, required). URL for the challenge b64.
    - `rpId` (string, required). Identifier for the rp.
    - `userVerification` (string, required). Specifies user verification for this passkey. Values: `preferred`, `required`, `discouraged`.
    - `expiresAt` (string, required). ISO 8601 timestamp when this resource expires.
    - `timeoutMs` (integer). Specifies timeout ms for this passkey.
  - `tunnelAvailable` (boolean). Whether a new secure pairing channel may currently be admitted for this link.
  - `errorCode` (string, required, nullable). Machine-readable error code for this native quick link state.

```json
{
  "data": {
    "testing": {
      "country": "string",
      "configuration": {
        "profile": {
          "name": "string",
          "status": "string"
        },
        "accountType": "whatsapp_app",
        "primaryPlatform": "android",
        "replyBehavior": "off",
        "failureScenario": "none",
        "historyFixtureId": "00000000-0000-4000-8000-000000000000"
      },
      "editable": [
        "profile.name"
      ],
      "state": "pending",
      "phone": "string"
    },
    "historyConfiguration": {
      "mode": "metadata_only",
      "requestFull": true
    },
    "historyConsent": "pending",
    "id": "string",
    "status": "pending",
    "expiresAt": "string",
    "connections": [
      "cloud"
    ],
    "selectedConnection": "cloud",
    "connectionPreference": "cloud",
    "connectionEnforcement": "prefer",
    "cloud": {
      "appId": "string",
      "configId": "string"
    },
    "onboarding": {
      "stage": "string",
      "connection": "string",
      "coexistence": true,
      "contactsSync": "string",
      "historySync": "string",
      "historyProgress": 0,
      "errorCode": "string",
      "sync": {
        "contacts": {
          "request": "not_applicable",
          "receiptRecorded": true
        },
        "history": {
          "request": "not_applicable",
          "receiptRecorded": true,
          "delivery": "not_applicable"
        }
      }
    },
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "businessName": "string",
    "headline": "string",
    "description": "string",
    "successMessage": "string",
    "supportUrl": "string",
    "privacyUrl": "string",
    "termsUrl": "string",
    "theme": "light",
    "accent": "string",
    "shape": "square",
    "radiusPx": 0,
    "logoUrl": "string",
    "hideWatermark": true,
    "historySync": "ask",
    "phoneStep": {
      "confirmed": true,
      "allowChange": true,
      "noNumber": true,
      "allowNoNumber": true
    },
    "prefillPhone": "string",
    "phoneIdentity": {
      "registered": true,
      "phone": "string",
      "whatsappPhone": "string",
      "accountType": "whatsapp",
      "pushName": "string",
      "pictureUrl": "https://example.com"
    },
    "customer": true,
    "session": {
      "status": "string",
      "phone": "string"
    },
    "qrSvg": "string",
    "errorCode": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Get quick link

`GET https://api.polymorfa.com/messaging/quicklinks/{id}` (Messaging API)

Required permission: `quicklink:manage`

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

### Path parameters

- `id` (string, required). Identifier for this resource.

### Request

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

### Responses

#### 200

Current QuickLink status
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, required). Identifier for this resource.
  - `status` (string, required). `linked`: for Linked Devices, the device is linked and the recipient has not confirmed; for Meta Cloud API, the number is connected to Meta and is still being made ready to send. For Meta Cloud API, `connected` requires every readiness check to pass, a successful runtime connection, and the recipient's confirmation. `failed` carries the reason in `errorCode`. Values: `pending`, `opened`, `linked`, `connected`, `failed`, `cancelled`.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `expiresAt` (string, required, nullable). ISO 8601 timestamp when this resource expires.
  - `openedAt` (string, required, nullable). Timestamp for opened at.
  - `connectedAt` (string, required, nullable). Timestamp for connected at.
  - `phone` (string, required, nullable). Connected phone in E.164 once the link is connected.
  - `errorCode` (string, required, nullable). Machine-readable error code for this native quick link status.
  - `onboarding` (object, nullable). Durable connection and sync progress; omitted when the onboarding service is unavailable, null when no record exists. Sync request and delivery evidence are independent of the connection stage.
    - `stage` (string, required). Specifies stage for this onboarding.
    - `connection` (string, required, nullable). Specifies connection for this onboarding.
    - `coexistence` (boolean, required, nullable). Whether coexistence.
    - `contactsSync` (string, required). Specifies contacts sync for this onboarding.
    - `historySync` (string, required). History synchronization behavior for newly connected sessions.
    - `historyProgress` (integer, required, range 0–100). Specifies history progress for this onboarding.
    - `errorCode` (string, required, nullable). Machine-readable error code for this onboarding.
    - `sync` (object, required). Specifies sync for this onboarding.
      - `contacts` (object, required). Contacts returned or affected by this operation.
        - `request` (string, required). Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
      - `history` (object, required). Structured history values for this native cloud sync status.
        - `request` (string, required). Specifies request for this history. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
        - `delivery` (string, required). Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists. Values: `not_applicable`, `not_requested`, `unconfirmed`, `partial`, `complete`, `declined`.

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": {
    "id": "string",
    "status": "pending",
    "session": "string",
    "expiresAt": "string",
    "openedAt": "string",
    "connectedAt": "string",
    "phone": "string",
    "errorCode": "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 native public error.

Headers:

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

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

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

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

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

#### 403

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

Headers:

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

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

#### 404

Resource not found
Same fields as 400.

Headers:

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

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

#### 500

Internal server error
Same fields as 400.

Headers:

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

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

## Get quick link state

`GET https://api.polymorfa.com/quicklink/{token}` (Messaging API)

Returns the hosted page state for a QuickLink. Public; the token in the URL is the credential. Starts linked-device pairing after an allowed connection type has been selected.

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Header parameters

- `X-Polymorfa-Passkey-Context` (string, pattern ^[A-Za-z0-9_-]{43}$). Specifies x polymorfa passkey context for this header parameter.

### Request

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

### Responses

#### 200

Current QuickLink state
- `data` (object, required). Structured data carried by this object.
  - `testing` (object, required, nullable). Structured testing values for this native quick link state.
    - `country` (string, required). ISO 3166-1 alpha-2 country code.
    - `configuration` (object, required). Structured configuration values for this testing.
      - `profile` (object). Structured profile values for this configuration.
        - `name` (string, length 1–128). Human-readable name for this resource.
        - `status` (string, max length 139). Current status of this resource or operation.
      - `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.).
      - `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
      - `replyBehavior` (string). Specifies reply behavior for this configuration. Values: `off`, `echo`.
      - `failureScenario` (string). Specifies failure scenario for this configuration. Values: `none`, `reject-send`.
      - `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.
    - `editable` (array of string, required). Editable associated with this testing. Values: `profile.name`, `profile.status`, `accountType`, `primaryPlatform`, `replyBehavior`, `failureScenario`, `historyFixtureId`.
    - `state` (string, required). Current lifecycle state of this resource. Values: `pending`, `starting`, `ready`.
    - `phone` (string, required). Phone number in international format.
  - `historyConfiguration` (object, required, nullable). Structured history configuration values for this native quick link state.
    - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
    - `requestFull` (boolean, required). Whether request full.
  - `historyConsent` (string, required, nullable). Specifies history consent for this native quick link state. Values: `pending`, `accepted`, `declined`.
  - `id` (string, required). Identifier for this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `pending`, `opened`, `linked`, `connected`, `failed`, `cancelled`.
  - `expiresAt` (string, required, nullable). ISO 8601 timestamp when this resource expires.
  - `redirectUrl` (string (uri), nullable, format uri). Snapshotted failure callback for a failed link. Omitted for non-failed states.
  - `connections` (array of string, required). Connections associated with this native quick link state. Values: `cloud`, `linked`.
  - `selectedConnection` (string, required, nullable). Specifies selected connection for this native quick link state. Values: `cloud`, `linked`.
  - `connectionPreference` (string, required). Specifies connection preference for this native quick link state. Values: `cloud`, `linked`, `both`.
  - `connectionEnforcement` (string, required). Specifies connection enforcement for this native quick link state. Values: `prefer`, `force`.
  - `cloud` (object, required, nullable). Structured cloud values for this native quick link state.
    - `appId` (string, required). Identifier of the connected application.
    - `configId` (string, required). Identifier for the config.
  - `onboarding` (object, required, nullable). Structured onboarding values for this native quick link state.
    - `stage` (string, required). Specifies stage for this onboarding.
    - `connection` (string, required, nullable). Specifies connection for this onboarding.
    - `coexistence` (boolean, required, nullable). Whether coexistence.
    - `contactsSync` (string, required). Specifies contacts sync for this onboarding.
    - `historySync` (string, required). History synchronization behavior for newly connected sessions.
    - `historyProgress` (integer, required, range 0–100). Specifies history progress for this onboarding.
    - `errorCode` (string, required, nullable). Machine-readable error code for this onboarding.
    - `sync` (object, required). Specifies sync for this onboarding.
      - `contacts` (object, required). Contacts returned or affected by this operation.
        - `request` (string, required). Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
      - `history` (object, required). Structured history values for this native cloud sync status.
        - `request` (string, required). Specifies request for this history. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
        - `delivery` (string, required). Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists. Values: `not_applicable`, `not_requested`, `unconfirmed`, `partial`, `complete`, `declined`.
  - `methods` (array of string, required). Connection methods enabled for the widget. Values: `qr`, `pairing`.
  - `defaultMethod` (string, required, nullable). Specifies default method for this native quick link state. Values: `qr`, `pairing`.
  - `businessName` (string, required). Business name shown to the customer.
  - `headline` (string, required, nullable). Specifies headline for this native quick link state.
  - `description` (string, required, nullable). Human-readable description of this resource.
  - `successMessage` (string, required, nullable). Specifies success message for this native quick link state.
  - `supportUrl` (string, required, nullable). URL for the support.
  - `privacyUrl` (string, required, nullable). URL for the privacy.
  - `termsUrl` (string, required, nullable). URL for the terms.
  - `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `accent` (string, required, nullable). Specifies accent for this native quick link state.
  - `shape` (string, required, nullable). Specifies shape for this native quick link state. Values: `square`, `rounded`, `pill`.
  - `radiusPx` (number, required, nullable). Specifies radius px for this native quick link state.
  - `logoUrl` (string, required, nullable). URL for the logo.
  - `hideWatermark` (boolean, required). Whether hide watermark.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
  - `phoneStep` (object, required). Structured phone step values for this native quick link state.
    - `confirmed` (boolean, required). Whether confirmed.
    - `allowChange` (boolean, required). Whether allow change.
    - `noNumber` (boolean, required). Whether no number.
    - `allowNoNumber` (boolean, required). Whether allow no number.
  - `prefillPhone` (string, required, nullable). Specifies prefill phone for this native quick link state.
  - `phoneIdentity` (object, required, nullable). Structured phone identity values for this native quick link state.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string, required, nullable). Specifies whatsapp phone for this phone identity.
    - `accountType` (string, required). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string (uri), required, nullable, format uri). URL for the picture.
  - `customer` (boolean, required). True when the link assigns the number to a Customer.
  - `session` (object, required). Identifier of the connected Polymorfa session.
    - `status` (string, required). Current status of this resource or operation.
    - `phone` (string, required, nullable). Phone number in international format.
  - `qrSvg` (string, required, nullable). Inline SVG of the current WhatsApp QR code, when the QR method is offered and the number is not linked yet.
  - `passkeyAvailable` (boolean). Whether passkey pairing is available. State reads and cancellation remain available when false.
  - `passkeyConfirmation` (object, nullable). Structured passkey confirmation values for this native quick link state.
    - `status` (string, required). Current status of this resource or operation. Values: `none`, `challenge_pending`, `assertion_sending`, `assertion_submitted`, `code_available`, `confirmation_sending`, `waiting_for_pairing`, `completed`, `failed`.
    - `ticketId` (string). Identifier for the ticket.
    - `code` (string). Stable machine-readable code for this result.
    - `skipHandoffUX` (boolean). Whether skip handoff ux.
    - `error` (string). Error details returned when the operation fails.
  - `passkey` (object, nullable). Pending passkey challenge ticket for WebAuthn authentication.
    - `ticket` (string, required). Specifies ticket for this passkey.
    - `challengeB64Url` (string, required). URL for the challenge b64.
    - `rpId` (string, required). Identifier for the rp.
    - `userVerification` (string, required). Specifies user verification for this passkey. Values: `preferred`, `required`, `discouraged`.
    - `expiresAt` (string, required). ISO 8601 timestamp when this resource expires.
    - `timeoutMs` (integer). Specifies timeout ms for this passkey.
  - `tunnelAvailable` (boolean). Whether a new secure pairing channel may currently be admitted for this link.
  - `errorCode` (string, required, nullable). Machine-readable error code for this native quick link state.

```json
{
  "data": {
    "testing": {
      "country": "string",
      "configuration": {
        "profile": {
          "name": "string",
          "status": "string"
        },
        "accountType": "whatsapp_app",
        "primaryPlatform": "android",
        "replyBehavior": "off",
        "failureScenario": "none",
        "historyFixtureId": "00000000-0000-4000-8000-000000000000"
      },
      "editable": [
        "profile.name"
      ],
      "state": "pending",
      "phone": "string"
    },
    "historyConfiguration": {
      "mode": "metadata_only",
      "requestFull": true
    },
    "historyConsent": "pending",
    "id": "string",
    "status": "pending",
    "expiresAt": "string",
    "connections": [
      "cloud"
    ],
    "selectedConnection": "cloud",
    "connectionPreference": "cloud",
    "connectionEnforcement": "prefer",
    "cloud": {
      "appId": "string",
      "configId": "string"
    },
    "onboarding": {
      "stage": "string",
      "connection": "string",
      "coexistence": true,
      "contactsSync": "string",
      "historySync": "string",
      "historyProgress": 0,
      "errorCode": "string",
      "sync": {
        "contacts": {
          "request": "not_applicable",
          "receiptRecorded": true
        },
        "history": {
          "request": "not_applicable",
          "receiptRecorded": true,
          "delivery": "not_applicable"
        }
      }
    },
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "businessName": "string",
    "headline": "string",
    "description": "string",
    "successMessage": "string",
    "supportUrl": "string",
    "privacyUrl": "string",
    "termsUrl": "string",
    "theme": "light",
    "accent": "string",
    "shape": "square",
    "radiusPx": 0,
    "logoUrl": "string",
    "hideWatermark": true,
    "historySync": "ask",
    "phoneStep": {
      "confirmed": true,
      "allowChange": true,
      "noNumber": true,
      "allowNoNumber": true
    },
    "prefillPhone": "string",
    "phoneIdentity": {
      "registered": true,
      "phone": "string",
      "whatsappPhone": "string",
      "accountType": "whatsapp",
      "pushName": "string",
      "pictureUrl": "https://example.com"
    },
    "customer": true,
    "session": {
      "status": "string",
      "phone": "string"
    },
    "qrSvg": "string",
    "errorCode": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Get quick link logo

`GET https://api.polymorfa.com/quicklink/{token}/logo` (Messaging API)

Returns the saved logo image for the page. Public; the token in the URL is the credential.

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Request

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

### Responses

#### 200

Logo image

Content type: `image/png`

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Get quick link settings

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

Required permission: `quicklink:manage`

Returns the saved QuickLink settings for the authenticated team or one project, or null when nothing has been saved for that scope. There is no separate read permission: reading and updating both require `quicklink:manage`, because the settings include the redirect allowlist and branding that only a QuickLink manager should see.

Requires `quicklink:manage`. 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/quicklink" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required, nullable). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, nullable, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `successCallbackUrl` (string (uri), required, nullable, format uri). Project-owned HTTPS destination after connection confirmation.
  - `failureCallbackUrl` (string (uri), required, nullable, format uri). Project-owned HTTPS destination after cancellation.
  - `businessName` (string, required, nullable). Business name shown to the customer.
  - `headline` (string, required, nullable). Specifies headline for this management quick link setting.
  - `description` (string, required, nullable). Human-readable description of this resource.
  - `successMessage` (string, required, nullable). Specifies success message for this management quick link setting.
  - `supportUrl` (string, required, nullable). URL for the support.
  - `privacyUrl` (string, required, nullable). URL for the privacy.
  - `termsUrl` (string, required, nullable). URL for the terms.
  - `accent` (string, required, nullable). Specifies accent for this management quick link setting.
  - `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `hideWatermark` (boolean, required). Saved preference to hide Powered by Polymorfa. QuickLink pages hide it only while the team is active and has a Branded QuickLink add-on.
  - `allowPhoneChange` (boolean, required). Allow recipients to change a prefilled phone number. Defaults to false.
  - `shape` (string, required, nullable). Specifies shape for this management quick link setting. Values: `square`, `rounded`, `pill`.
  - `radiusPx` (number, required, nullable). Specifies radius px for this management quick link setting.
  - `logoMode` (string, required). Behavior selected for logo. Values: `none`, `custom`, `team`, `project`.
  - `logoStorageId` (string, required, nullable). Identifier for the logo storage.
  - `logoSourceStorageId` (string, required, nullable). Identifier for the logo source storage.
  - `logoUrl` (string, required, nullable). URL for the logo.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
  - `methods` (array of string, required, nullable). Connection methods enabled for the widget. Values: `qr`, `pairing`.
  - `defaultMethod` (string, required, nullable). Specifies default method for this management quick link setting. Values: `qr`, `pairing`.
  - `createdAt` (integer, required). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required). Unix timestamp in milliseconds when this resource was last updated.

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",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "successCallbackUrl": "https://example.com",
    "failureCallbackUrl": "https://example.com",
    "businessName": "string",
    "headline": "string",
    "description": "string",
    "successMessage": "string",
    "supportUrl": "string",
    "privacyUrl": "string",
    "termsUrl": "string",
    "accent": "string",
    "theme": "light",
    "hideWatermark": true,
    "allowPhoneChange": true,
    "shape": "square",
    "radiusPx": 0,
    "logoMode": "none",
    "logoStorageId": "string",
    "logoSourceStorageId": "string",
    "logoUrl": "string",
    "historySync": "ask",
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "createdAt": 0,
    "updatedAt": 0
  }
}
```

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

## Update quick link settings

`PUT https://api.polymorfa.com/platform/quicklink` (Platform API)

Required permission: `quicklink:manage`

Updates the saved QuickLink settings for the authenticated team or project and returns the saved record. Privacy and terms links are optional and shown when supplied. Setting `hideWatermark` to true without an active Branded QuickLink add-on returns 402 with code `addon_required`.

Requires `quicklink: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.
- `enabled` (boolean). Allows QuickLinks to be created for the scope.
- `successCallbackUrl` (string (uri), nullable, max length 2048, format uri, pattern ^[Hh][Tt][Tt][Pp][Ss]://). Project-only destination after connection confirmation. Snapshotted when issuing a link.
- `failureCallbackUrl` (string (uri), nullable, max length 2048, format uri, pattern ^[Hh][Tt][Tt][Pp][Ss]://). Project-only destination after cancellation. Snapshotted when issuing a link.
- `businessName` (string, nullable, max length 120). Business name shown to the customer.
- `headline` (string, nullable, max length 80). Page title shown above the pairing flow. Defaults to “Connect WhatsApp”.
- `description` (string, nullable, max length 280). Intro sentence shown under the headline.
- `successMessage` (string, nullable, max length 280). Message shown after the number connects.
- `supportUrl` (string (uri), nullable, max length 2048, format uri, pattern ^[Hh][Tt][Tt][Pp][Ss]://). Help link shown on the page.
- `privacyUrl` (string (uri), nullable, max length 2048, format uri, pattern ^[Hh][Tt][Tt][Pp][Ss]://). Optional privacy notice link, shown on the consent step when supplied. Set null to clear it. Team-wide settings cannot hold it.
- `termsUrl` (string (uri), nullable, max length 2048, format uri, pattern ^[Hh][Tt][Tt][Pp][Ss]://). Terms link shown on the consent step.
- `accent` (string, nullable, pattern ^#[0-9A-Fa-f]{6}$). Specifies accent for this management update quick link settings request.
- `theme` (string). Visual theme used by the widget. Values: `light`, `dark`, `system`.
- `hideWatermark` (boolean). Hide Powered by Polymorfa. Setting `true` requires an active team with a Branded QuickLink add-on; otherwise the request returns `402` with code `addon_required`.
- `allowPhoneChange` (boolean). Allow recipients to change a prefilled phone number. Defaults to false.
- `shape` (string, nullable). Specifies shape for this management update quick link settings request. Values: `square`, `rounded`, `pill`.
- `radiusPx` (number, nullable, range 0–999). Specifies radius px for this management update quick link settings request.
- `logoMode` (string). Behavior selected for logo. Values: `none`, `custom`, `team`, `project`.
- `logoStorageId` (string, nullable). Identifier for the logo storage.
- `logoSourceStorageId` (string, nullable). Identifier for the logo source storage.
- `historySync` (string). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
- `methods` (array of string, nullable, items 1–2, unique items). Connection methods offered on hosted QuickLink pages. Values: `qr`, `pairing`.
- `defaultMethod` (string, nullable). Method the page opens first. Unset lets the page choose by device. Values: `qr`, `pairing`.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/quicklink" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "00000000-0000-4000-8000-000000000000",
  "enabled": true,
  "successCallbackUrl": "https://example.com",
  "failureCallbackUrl": "https://example.com",
  "businessName": "string",
  "headline": "string",
  "description": "string",
  "successMessage": "string",
  "supportUrl": "https://example.com",
  "privacyUrl": "https://example.com",
  "termsUrl": "https://example.com",
  "accent": "string",
  "theme": "light",
  "hideWatermark": true,
  "allowPhoneChange": true,
  "shape": "square",
  "radiusPx": 0,
  "logoMode": "none",
  "logoStorageId": "string",
  "logoSourceStorageId": "string",
  "historySync": "ask",
  "methods": [
    "qr"
  ],
  "defaultMethod": "qr"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, nullable, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `successCallbackUrl` (string (uri), required, nullable, format uri). Project-owned HTTPS destination after connection confirmation.
  - `failureCallbackUrl` (string (uri), required, nullable, format uri). Project-owned HTTPS destination after cancellation.
  - `businessName` (string, required, nullable). Business name shown to the customer.
  - `headline` (string, required, nullable). Specifies headline for this management quick link setting.
  - `description` (string, required, nullable). Human-readable description of this resource.
  - `successMessage` (string, required, nullable). Specifies success message for this management quick link setting.
  - `supportUrl` (string, required, nullable). URL for the support.
  - `privacyUrl` (string, required, nullable). URL for the privacy.
  - `termsUrl` (string, required, nullable). URL for the terms.
  - `accent` (string, required, nullable). Specifies accent for this management quick link setting.
  - `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `hideWatermark` (boolean, required). Saved preference to hide Powered by Polymorfa. QuickLink pages hide it only while the team is active and has a Branded QuickLink add-on.
  - `allowPhoneChange` (boolean, required). Allow recipients to change a prefilled phone number. Defaults to false.
  - `shape` (string, required, nullable). Specifies shape for this management quick link setting. Values: `square`, `rounded`, `pill`.
  - `radiusPx` (number, required, nullable). Specifies radius px for this management quick link setting.
  - `logoMode` (string, required). Behavior selected for logo. Values: `none`, `custom`, `team`, `project`.
  - `logoStorageId` (string, required, nullable). Identifier for the logo storage.
  - `logoSourceStorageId` (string, required, nullable). Identifier for the logo source storage.
  - `logoUrl` (string, required, nullable). URL for the logo.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
  - `methods` (array of string, required, nullable). Connection methods enabled for the widget. Values: `qr`, `pairing`.
  - `defaultMethod` (string, required, nullable). Specifies default method for this management quick link setting. Values: `qr`, `pairing`.
  - `createdAt` (integer, required). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required). Unix timestamp in milliseconds when this resource was last updated.

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",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "successCallbackUrl": "https://example.com",
    "failureCallbackUrl": "https://example.com",
    "businessName": "string",
    "headline": "string",
    "description": "string",
    "successMessage": "string",
    "supportUrl": "string",
    "privacyUrl": "string",
    "termsUrl": "string",
    "accent": "string",
    "theme": "light",
    "hideWatermark": true,
    "allowPhoneChange": true,
    "shape": "square",
    "radiusPx": 0,
    "logoMode": "none",
    "logoStorageId": "string",
    "logoSourceStorageId": "string",
    "logoUrl": "string",
    "historySync": "ask",
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "createdAt": 0,
    "updatedAt": 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"
}
```

#### 402

`addon_required`: the request uses a benefit of an add-on that your team does not have active.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "addon_required",
    "message": "This request needs an add-on that is not active for your team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#addon-required"
}
```

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

## Exchange customer pairing link

`POST https://api.polymorfa.com/messaging/customer-pairing/exchange` (Messaging API)

Exchanges the invitation token in the request body for a hosted QuickLink URL. The invitation token is the credential; no API key is required. This request creates or resumes pairing and can affect the invitation's attempt limits. Open the returned URL to continue setup. The response is JSON, not an HTTP redirect. A lost response or a temporary error can follow pairing effects. Do not automatically replay this POST; Idempotency-Key is not supported. The returned expiry describes the QuickLink, not the Customer invitation. A missing business privacy link does not block the exchange.

### Body

- `token` (string, required, pattern ^[A-Za-z0-9_-]{43}$). The 43-character base64url token from the Customer invitation. Keep it private.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/customer-pairing/exchange" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'
```

### Responses

#### 200

Hosted QuickLink URL for this invitation
- `data` (object, required). Structured data carried by this object.
  - `url` (string, required). Hosted QuickLink URL. Treat it as a private credential.
  - `expiresAt` (string, required, nullable). Expiry of the returned QuickLink, or null when no fixed expiry is assigned. This is not the invitation expiry.

Headers:

- `Cache-Control` (string). Values: `no-store`.
- `Referrer-Policy` (string). Values: `no-referrer`.

```json
{
  "data": {
    "url": "string",
    "expiresAt": "string"
  }
}
```

#### 410

`pairing_link_unavailable`: malformed, unknown, expired, revoked or unusable invitation. No replacement token or invitation details are disclosed.
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result. Values: `pairing_link_unavailable`, `pairing_link_attempts_exhausted`, `pairing_rate_limited`, `pairing_temporarily_unavailable`.
  - `message` (string, required). Human-readable message associated with this result.

```json
{
  "error": {
    "code": "pairing_link_unavailable",
    "message": "string"
  }
}
```

#### 429

`pairing_rate_limited`: a source or invitation abuse limit rejected the request; or `pairing_link_attempts_exhausted`: the invitation reached its attempt limit. No Retry-After value is supplied by this operation.
Same fields as 410.

```json
{
  "error": {
    "code": "pairing_link_unavailable",
    "message": "string"
  }
}
```

#### 503

`pairing_temporarily_unavailable`: pairing could not complete. Effects can already have occurred; do not assume the request was unconsumed or automatically replay it.
Same fields as 410.

```json
{
  "error": {
    "code": "pairing_link_unavailable",
    "message": "string"
  }
}
```

## Cancel quick link

`DELETE https://api.polymorfa.com/messaging/quicklinks/{id}` (Messaging API)

Required permission: `quicklink:manage`

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

Cancels pending onboarding. Initial Number cleanup is accepted asynchronously and completes only after runtime teardown. Supplementary and reauthorization links cancel only their pending attempts; the existing Number remains. Accepted provider work must finish before cancellation.

### Path parameters

- `id` (string, required). Identifier for this resource.

### Request

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

### Responses

#### 200

Cancelled
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `message` (string, required). 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,
  "message": "string"
}
```

#### 202

QuickLink invalidated; Number cleanup pending
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `message` (string, required). Human-readable message associated with this result.

Headers:

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

```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 native public error.

Headers:

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

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

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

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

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

#### 403

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

Headers:

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

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

#### 404

Resource not found
Same fields as 400.

Headers:

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

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

#### 500

Internal server error
Same fields as 400.

Headers:

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

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

## Confirm quick link phone

`POST https://api.polymorfa.com/quicklink/{token}/phone` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `phone` (string, max length 32). Phone number in international format.
- `noNumber` (boolean). Whether no number. Values: `true`.
- `whatsappPhone` (string, max length 32). Specifies whatsapp phone for this schema.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/phone" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "string",
  "noNumber": true,
  "whatsappPhone": "string"
}'
```

### Responses

#### 200

Phone confirmed
- `data` (object, required). Structured data carried by this object.
  - `confirmed` (boolean, required). Whether confirmed.

```json
{
  "data": {
    "confirmed": true
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Reset quick link phone

`POST https://api.polymorfa.com/quicklink/{token}/phone/reset` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/phone/reset" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Phone entry restored
- `data` (object, required). Structured data carried by this object.
  - `confirmed` (boolean, required). Whether confirmed.

```json
{
  "data": {
    "confirmed": true
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Select quick link connection

`POST https://api.polymorfa.com/quicklink/{token}/connection` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `connection` (string, required). Specifies connection for this schema. Values: `cloud`, `linked`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/connection" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "connection": "cloud"
}'
```

### Responses

#### 200

Selected
- `data` (object, required). Structured data carried by this object.
  - `connection` (string, required). Specifies connection for this data. Values: `cloud`, `linked`.

```json
{
  "data": {
    "connection": "cloud"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Complete quick link cloud signup

`POST https://api.polymorfa.com/quicklink/{token}/cloud` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `result` (object). Specifies result for this schema.
  - `code` (string, required, length 1–4096). Stable machine-readable code for this result.
  - `wabaId` (string, required, pattern ^\d+$). Identifier for the waba.
  - `phoneNumberId` (string, required, pattern ^\d+$). Identifier for the phone number.
  - `coexistence` (boolean). Whether coexistence. Default: `true`.
  - `historySync` (boolean). History synchronization behavior for newly connected sessions. Default: `false`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/cloud" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "result": {
    "code": "string",
    "wabaId": "string",
    "phoneNumberId": "string"
  }
}'
```

### Responses

#### 200

Onboarding progress
- `data` (object, required). Structured data carried by this object.
  - `stage` (string, required). Specifies stage for this data.

```json
{
  "data": {
    "stage": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Choose quick link history

`POST https://api.polymorfa.com/quicklink/{token}/history` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `historySync` (boolean, required). History synchronization behavior for newly connected sessions.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/history" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "historySync": true
}'
```

### Responses

#### 200

History choice recorded
- `data` (object, required). Structured data carried by this object.
  - `testing` (object, required, nullable). Structured testing values for this native quick link state.
    - `country` (string, required). ISO 3166-1 alpha-2 country code.
    - `configuration` (object, required). Structured configuration values for this testing.
      - `profile` (object). Structured profile values for this configuration.
        - `name` (string, length 1–128). Human-readable name for this resource.
        - `status` (string, max length 139). Current status of this resource or operation.
      - `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.).
      - `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
      - `replyBehavior` (string). Specifies reply behavior for this configuration. Values: `off`, `echo`.
      - `failureScenario` (string). Specifies failure scenario for this configuration. Values: `none`, `reject-send`.
      - `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.
    - `editable` (array of string, required). Editable associated with this testing. Values: `profile.name`, `profile.status`, `accountType`, `primaryPlatform`, `replyBehavior`, `failureScenario`, `historyFixtureId`.
    - `state` (string, required). Current lifecycle state of this resource. Values: `pending`, `starting`, `ready`.
    - `phone` (string, required). Phone number in international format.
  - `historyConfiguration` (object, required, nullable). Structured history configuration values for this native quick link state.
    - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
    - `requestFull` (boolean, required). Whether request full.
  - `historyConsent` (string, required, nullable). Specifies history consent for this native quick link state. Values: `pending`, `accepted`, `declined`.
  - `id` (string, required). Identifier for this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `pending`, `opened`, `linked`, `connected`, `failed`, `cancelled`.
  - `expiresAt` (string, required, nullable). ISO 8601 timestamp when this resource expires.
  - `redirectUrl` (string (uri), nullable, format uri). Snapshotted failure callback for a failed link. Omitted for non-failed states.
  - `connections` (array of string, required). Connections associated with this native quick link state. Values: `cloud`, `linked`.
  - `selectedConnection` (string, required, nullable). Specifies selected connection for this native quick link state. Values: `cloud`, `linked`.
  - `connectionPreference` (string, required). Specifies connection preference for this native quick link state. Values: `cloud`, `linked`, `both`.
  - `connectionEnforcement` (string, required). Specifies connection enforcement for this native quick link state. Values: `prefer`, `force`.
  - `cloud` (object, required, nullable). Structured cloud values for this native quick link state.
    - `appId` (string, required). Identifier of the connected application.
    - `configId` (string, required). Identifier for the config.
  - `onboarding` (object, required, nullable). Structured onboarding values for this native quick link state.
    - `stage` (string, required). Specifies stage for this onboarding.
    - `connection` (string, required, nullable). Specifies connection for this onboarding.
    - `coexistence` (boolean, required, nullable). Whether coexistence.
    - `contactsSync` (string, required). Specifies contacts sync for this onboarding.
    - `historySync` (string, required). History synchronization behavior for newly connected sessions.
    - `historyProgress` (integer, required, range 0–100). Specifies history progress for this onboarding.
    - `errorCode` (string, required, nullable). Machine-readable error code for this onboarding.
    - `sync` (object, required). Specifies sync for this onboarding.
      - `contacts` (object, required). Contacts returned or affected by this operation.
        - `request` (string, required). Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
      - `history` (object, required). Structured history values for this native cloud sync status.
        - `request` (string, required). Specifies request for this history. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
        - `delivery` (string, required). Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists. Values: `not_applicable`, `not_requested`, `unconfirmed`, `partial`, `complete`, `declined`.
  - `methods` (array of string, required). Connection methods enabled for the widget. Values: `qr`, `pairing`.
  - `defaultMethod` (string, required, nullable). Specifies default method for this native quick link state. Values: `qr`, `pairing`.
  - `businessName` (string, required). Business name shown to the customer.
  - `headline` (string, required, nullable). Specifies headline for this native quick link state.
  - `description` (string, required, nullable). Human-readable description of this resource.
  - `successMessage` (string, required, nullable). Specifies success message for this native quick link state.
  - `supportUrl` (string, required, nullable). URL for the support.
  - `privacyUrl` (string, required, nullable). URL for the privacy.
  - `termsUrl` (string, required, nullable). URL for the terms.
  - `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `accent` (string, required, nullable). Specifies accent for this native quick link state.
  - `shape` (string, required, nullable). Specifies shape for this native quick link state. Values: `square`, `rounded`, `pill`.
  - `radiusPx` (number, required, nullable). Specifies radius px for this native quick link state.
  - `logoUrl` (string, required, nullable). URL for the logo.
  - `hideWatermark` (boolean, required). Whether hide watermark.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
  - `phoneStep` (object, required). Structured phone step values for this native quick link state.
    - `confirmed` (boolean, required). Whether confirmed.
    - `allowChange` (boolean, required). Whether allow change.
    - `noNumber` (boolean, required). Whether no number.
    - `allowNoNumber` (boolean, required). Whether allow no number.
  - `prefillPhone` (string, required, nullable). Specifies prefill phone for this native quick link state.
  - `phoneIdentity` (object, required, nullable). Structured phone identity values for this native quick link state.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string, required, nullable). Specifies whatsapp phone for this phone identity.
    - `accountType` (string, required). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string (uri), required, nullable, format uri). URL for the picture.
  - `customer` (boolean, required). True when the link assigns the number to a Customer.
  - `session` (object, required). Identifier of the connected Polymorfa session.
    - `status` (string, required). Current status of this resource or operation.
    - `phone` (string, required, nullable). Phone number in international format.
  - `qrSvg` (string, required, nullable). Inline SVG of the current WhatsApp QR code, when the QR method is offered and the number is not linked yet.
  - `passkeyAvailable` (boolean). Whether passkey pairing is available. State reads and cancellation remain available when false.
  - `passkeyConfirmation` (object, nullable). Structured passkey confirmation values for this native quick link state.
    - `status` (string, required). Current status of this resource or operation. Values: `none`, `challenge_pending`, `assertion_sending`, `assertion_submitted`, `code_available`, `confirmation_sending`, `waiting_for_pairing`, `completed`, `failed`.
    - `ticketId` (string). Identifier for the ticket.
    - `code` (string). Stable machine-readable code for this result.
    - `skipHandoffUX` (boolean). Whether skip handoff ux.
    - `error` (string). Error details returned when the operation fails.
  - `passkey` (object, nullable). Pending passkey challenge ticket for WebAuthn authentication.
    - `ticket` (string, required). Specifies ticket for this passkey.
    - `challengeB64Url` (string, required). URL for the challenge b64.
    - `rpId` (string, required). Identifier for the rp.
    - `userVerification` (string, required). Specifies user verification for this passkey. Values: `preferred`, `required`, `discouraged`.
    - `expiresAt` (string, required). ISO 8601 timestamp when this resource expires.
    - `timeoutMs` (integer). Specifies timeout ms for this passkey.
  - `tunnelAvailable` (boolean). Whether a new secure pairing channel may currently be admitted for this link.
  - `errorCode` (string, required, nullable). Machine-readable error code for this native quick link state.

```json
{
  "data": {
    "testing": {
      "country": "string",
      "configuration": {
        "profile": {
          "name": "string",
          "status": "string"
        },
        "accountType": "whatsapp_app",
        "primaryPlatform": "android",
        "replyBehavior": "off",
        "failureScenario": "none",
        "historyFixtureId": "00000000-0000-4000-8000-000000000000"
      },
      "editable": [
        "profile.name"
      ],
      "state": "pending",
      "phone": "string"
    },
    "historyConfiguration": {
      "mode": "metadata_only",
      "requestFull": true
    },
    "historyConsent": "pending",
    "id": "string",
    "status": "pending",
    "expiresAt": "string",
    "connections": [
      "cloud"
    ],
    "selectedConnection": "cloud",
    "connectionPreference": "cloud",
    "connectionEnforcement": "prefer",
    "cloud": {
      "appId": "string",
      "configId": "string"
    },
    "onboarding": {
      "stage": "string",
      "connection": "string",
      "coexistence": true,
      "contactsSync": "string",
      "historySync": "string",
      "historyProgress": 0,
      "errorCode": "string",
      "sync": {
        "contacts": {
          "request": "not_applicable",
          "receiptRecorded": true
        },
        "history": {
          "request": "not_applicable",
          "receiptRecorded": true,
          "delivery": "not_applicable"
        }
      }
    },
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "businessName": "string",
    "headline": "string",
    "description": "string",
    "successMessage": "string",
    "supportUrl": "string",
    "privacyUrl": "string",
    "termsUrl": "string",
    "theme": "light",
    "accent": "string",
    "shape": "square",
    "radiusPx": 0,
    "logoUrl": "string",
    "hideWatermark": true,
    "historySync": "ask",
    "phoneStep": {
      "confirmed": true,
      "allowChange": true,
      "noNumber": true,
      "allowNoNumber": true
    },
    "prefillPhone": "string",
    "phoneIdentity": {
      "registered": true,
      "phone": "string",
      "whatsappPhone": "string",
      "accountType": "whatsapp",
      "pushName": "string",
      "pictureUrl": "https://example.com"
    },
    "customer": true,
    "session": {
      "status": "string",
      "phone": "string"
    },
    "qrSvg": "string",
    "errorCode": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Customize quick link testing

`PATCH https://api.polymorfa.com/quicklink/{token}/testing` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `profile` (object). Structured profile values for this schema.
  - `name` (string, length 1–128). Human-readable name for this resource.
  - `status` (string, max length 139). Current status of this resource or operation.
- `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.).
- `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
- `replyBehavior` (string). Specifies reply behavior for this schema. Values: `off`, `echo`.
- `failureScenario` (string). Specifies failure scenario for this schema. Values: `none`, `reject-send`.
- `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/quicklink/<token>/testing" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "profile": {
    "name": "string",
    "status": "string"
  },
  "accountType": "whatsapp_app",
  "primaryPlatform": "android",
  "replyBehavior": "off",
  "failureScenario": "none",
  "historyFixtureId": "00000000-0000-4000-8000-000000000000"
}'
```

### Responses

#### 200

Test configuration updated
- `data` (object, required). Structured data carried by this object.
  - `testing` (object, required, nullable). Structured testing values for this native quick link state.
    - `country` (string, required). ISO 3166-1 alpha-2 country code.
    - `configuration` (object, required). Structured configuration values for this testing.
      - `profile` (object). Structured profile values for this configuration.
        - `name` (string, length 1–128). Human-readable name for this resource.
        - `status` (string, max length 139). Current status of this resource or operation.
      - `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.).
      - `primaryPlatform` (string). Primary phone platform the Test number emulates. Defaults to `android`. Not accepted when `accountType` is `meta_cloud`. Values: `android` (An Android phone.), `ios` (An iPhone.).
      - `replyBehavior` (string). Specifies reply behavior for this configuration. Values: `off`, `echo`.
      - `failureScenario` (string). Specifies failure scenario for this configuration. Values: `none`, `reject-send`.
      - `historyFixtureId` (string (uuid), format uuid). Identifier for the history fixture.
    - `editable` (array of string, required). Editable associated with this testing. Values: `profile.name`, `profile.status`, `accountType`, `primaryPlatform`, `replyBehavior`, `failureScenario`, `historyFixtureId`.
    - `state` (string, required). Current lifecycle state of this resource. Values: `pending`, `starting`, `ready`.
    - `phone` (string, required). Phone number in international format.
  - `historyConfiguration` (object, required, nullable). Structured history configuration values for this native quick link state.
    - `mode` (string, required). Operating mode selected for this feature. Values: `metadata_only`, `deliver`.
    - `requestFull` (boolean, required). Whether request full.
  - `historyConsent` (string, required, nullable). Specifies history consent for this native quick link state. Values: `pending`, `accepted`, `declined`.
  - `id` (string, required). Identifier for this resource.
  - `status` (string, required). Current status of this resource or operation. Values: `pending`, `opened`, `linked`, `connected`, `failed`, `cancelled`.
  - `expiresAt` (string, required, nullable). ISO 8601 timestamp when this resource expires.
  - `redirectUrl` (string (uri), nullable, format uri). Snapshotted failure callback for a failed link. Omitted for non-failed states.
  - `connections` (array of string, required). Connections associated with this native quick link state. Values: `cloud`, `linked`.
  - `selectedConnection` (string, required, nullable). Specifies selected connection for this native quick link state. Values: `cloud`, `linked`.
  - `connectionPreference` (string, required). Specifies connection preference for this native quick link state. Values: `cloud`, `linked`, `both`.
  - `connectionEnforcement` (string, required). Specifies connection enforcement for this native quick link state. Values: `prefer`, `force`.
  - `cloud` (object, required, nullable). Structured cloud values for this native quick link state.
    - `appId` (string, required). Identifier of the connected application.
    - `configId` (string, required). Identifier for the config.
  - `onboarding` (object, required, nullable). Structured onboarding values for this native quick link state.
    - `stage` (string, required). Specifies stage for this onboarding.
    - `connection` (string, required, nullable). Specifies connection for this onboarding.
    - `coexistence` (boolean, required, nullable). Whether coexistence.
    - `contactsSync` (string, required). Specifies contacts sync for this onboarding.
    - `historySync` (string, required). History synchronization behavior for newly connected sessions.
    - `historyProgress` (integer, required, range 0–100). Specifies history progress for this onboarding.
    - `errorCode` (string, required, nullable). Machine-readable error code for this onboarding.
    - `sync` (object, required). Specifies sync for this onboarding.
      - `contacts` (object, required). Contacts returned or affected by this operation.
        - `request` (string, required). Accepted means Meta returned a request receipt; it does not prove all contacts were delivered. Unknown means a one-time request may have been accepted without a saved receipt. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
      - `history` (object, required). Structured history values for this native cloud sync status.
        - `request` (string, required). Specifies request for this history. Values: `not_applicable`, `not_requested`, `pending`, `requesting`, `accepted`, `declined`, `unknown`.
        - `receiptRecorded` (boolean, required). Whether receipt recorded.
        - `delivery` (string, required). Partial and complete describe the latest history progress reported by Meta. Unconfirmed does not mean that no history exists. Values: `not_applicable`, `not_requested`, `unconfirmed`, `partial`, `complete`, `declined`.
  - `methods` (array of string, required). Connection methods enabled for the widget. Values: `qr`, `pairing`.
  - `defaultMethod` (string, required, nullable). Specifies default method for this native quick link state. Values: `qr`, `pairing`.
  - `businessName` (string, required). Business name shown to the customer.
  - `headline` (string, required, nullable). Specifies headline for this native quick link state.
  - `description` (string, required, nullable). Human-readable description of this resource.
  - `successMessage` (string, required, nullable). Specifies success message for this native quick link state.
  - `supportUrl` (string, required, nullable). URL for the support.
  - `privacyUrl` (string, required, nullable). URL for the privacy.
  - `termsUrl` (string, required, nullable). URL for the terms.
  - `theme` (string, required). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `accent` (string, required, nullable). Specifies accent for this native quick link state.
  - `shape` (string, required, nullable). Specifies shape for this native quick link state. Values: `square`, `rounded`, `pill`.
  - `radiusPx` (number, required, nullable). Specifies radius px for this native quick link state.
  - `logoUrl` (string, required, nullable). URL for the logo.
  - `hideWatermark` (boolean, required). Whether hide watermark.
  - `historySync` (string, required). History synchronization behavior for newly connected sessions. Values: `ask`, `force_on`, `force_off`.
  - `phoneStep` (object, required). Structured phone step values for this native quick link state.
    - `confirmed` (boolean, required). Whether confirmed.
    - `allowChange` (boolean, required). Whether allow change.
    - `noNumber` (boolean, required). Whether no number.
    - `allowNoNumber` (boolean, required). Whether allow no number.
  - `prefillPhone` (string, required, nullable). Specifies prefill phone for this native quick link state.
  - `phoneIdentity` (object, required, nullable). Structured phone identity values for this native quick link state.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string, required, nullable). Specifies whatsapp phone for this phone identity.
    - `accountType` (string, required). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string (uri), required, nullable, format uri). URL for the picture.
  - `customer` (boolean, required). True when the link assigns the number to a Customer.
  - `session` (object, required). Identifier of the connected Polymorfa session.
    - `status` (string, required). Current status of this resource or operation.
    - `phone` (string, required, nullable). Phone number in international format.
  - `qrSvg` (string, required, nullable). Inline SVG of the current WhatsApp QR code, when the QR method is offered and the number is not linked yet.
  - `passkeyAvailable` (boolean). Whether passkey pairing is available. State reads and cancellation remain available when false.
  - `passkeyConfirmation` (object, nullable). Structured passkey confirmation values for this native quick link state.
    - `status` (string, required). Current status of this resource or operation. Values: `none`, `challenge_pending`, `assertion_sending`, `assertion_submitted`, `code_available`, `confirmation_sending`, `waiting_for_pairing`, `completed`, `failed`.
    - `ticketId` (string). Identifier for the ticket.
    - `code` (string). Stable machine-readable code for this result.
    - `skipHandoffUX` (boolean). Whether skip handoff ux.
    - `error` (string). Error details returned when the operation fails.
  - `passkey` (object, nullable). Pending passkey challenge ticket for WebAuthn authentication.
    - `ticket` (string, required). Specifies ticket for this passkey.
    - `challengeB64Url` (string, required). URL for the challenge b64.
    - `rpId` (string, required). Identifier for the rp.
    - `userVerification` (string, required). Specifies user verification for this passkey. Values: `preferred`, `required`, `discouraged`.
    - `expiresAt` (string, required). ISO 8601 timestamp when this resource expires.
    - `timeoutMs` (integer). Specifies timeout ms for this passkey.
  - `tunnelAvailable` (boolean). Whether a new secure pairing channel may currently be admitted for this link.
  - `errorCode` (string, required, nullable). Machine-readable error code for this native quick link state.

```json
{
  "data": {
    "testing": {
      "country": "string",
      "configuration": {
        "profile": {
          "name": "string",
          "status": "string"
        },
        "accountType": "whatsapp_app",
        "primaryPlatform": "android",
        "replyBehavior": "off",
        "failureScenario": "none",
        "historyFixtureId": "00000000-0000-4000-8000-000000000000"
      },
      "editable": [
        "profile.name"
      ],
      "state": "pending",
      "phone": "string"
    },
    "historyConfiguration": {
      "mode": "metadata_only",
      "requestFull": true
    },
    "historyConsent": "pending",
    "id": "string",
    "status": "pending",
    "expiresAt": "string",
    "connections": [
      "cloud"
    ],
    "selectedConnection": "cloud",
    "connectionPreference": "cloud",
    "connectionEnforcement": "prefer",
    "cloud": {
      "appId": "string",
      "configId": "string"
    },
    "onboarding": {
      "stage": "string",
      "connection": "string",
      "coexistence": true,
      "contactsSync": "string",
      "historySync": "string",
      "historyProgress": 0,
      "errorCode": "string",
      "sync": {
        "contacts": {
          "request": "not_applicable",
          "receiptRecorded": true
        },
        "history": {
          "request": "not_applicable",
          "receiptRecorded": true,
          "delivery": "not_applicable"
        }
      }
    },
    "methods": [
      "qr"
    ],
    "defaultMethod": "qr",
    "businessName": "string",
    "headline": "string",
    "description": "string",
    "successMessage": "string",
    "supportUrl": "string",
    "privacyUrl": "string",
    "termsUrl": "string",
    "theme": "light",
    "accent": "string",
    "shape": "square",
    "radiusPx": 0,
    "logoUrl": "string",
    "hideWatermark": true,
    "historySync": "ask",
    "phoneStep": {
      "confirmed": true,
      "allowChange": true,
      "noNumber": true,
      "allowNoNumber": true
    },
    "prefillPhone": "string",
    "phoneIdentity": {
      "registered": true,
      "phone": "string",
      "whatsappPhone": "string",
      "accountType": "whatsapp",
      "pushName": "string",
      "pictureUrl": "https://example.com"
    },
    "customer": true,
    "session": {
      "status": "string",
      "phone": "string"
    },
    "qrSvg": "string",
    "errorCode": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Request quick link code

`POST https://api.polymorfa.com/quicklink/{token}/code` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `phone` (string, required, length 6–20). Phone number in international format.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/code" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "string"
}'
```

### Responses

#### 200

Pairing code issued
- `data` (object, required). Structured data carried by this object.
  - `code` (string, required). Stable machine-readable code for this result.
  - `phone` (string, required). Phone number in international format.

```json
{
  "data": {
    "code": "string",
    "phone": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 402

The team cannot fund pairing
Same fields as 400.

```json
{
  "error": {
    "code": "entitlement_required",
    "message": "Your team’s plan or billing mode does not include this action.",
    "type": "billing_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Confirm quick link

`POST https://api.polymorfa.com/quicklink/{token}/confirm` (Messaging API)

Records consent, applies the chat-history choice, assigns Customer ownership when applicable, and returns the redirect target.

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `historySync` (boolean). History synchronization behavior for newly connected sessions.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/confirm" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "historySync": true
}'
```

### Responses

#### 200

Connected
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation. Values: `connected`.
  - `phone` (string, required, nullable). Phone number in international format.
  - `historySync` (boolean, required). History synchronization behavior for newly connected sessions.
  - `redirectUrl` (string, required, nullable). URL for the redirect.

```json
{
  "data": {
    "status": "connected",
    "phone": "string",
    "historySync": true,
    "redirectUrl": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Cancel quick link by token

`POST https://api.polymorfa.com/quicklink/{token}/cancel` (Messaging API)

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/cancel" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Cancelled
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation. Values: `cancelled`.
  - `redirectUrl` (string, required, nullable). URL for the redirect.

```json
{
  "data": {
    "status": "cancelled",
    "redirectUrl": "string"
  }
}
```

#### 202

QuickLink invalidated; Number cleanup pending
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation. Values: `cancelled`.
  - `redirectUrl` (string, required, nullable). URL for the redirect.

```json
{
  "data": {
    "status": "cancelled",
    "redirectUrl": "string"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Confirm quick link passkey

`POST https://api.polymorfa.com/quicklink/{token}/passkey/confirmation` (Messaging API)

The complete HTTP body is limited to 1048576 UTF-8 bytes before JSON parsing.

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `ticketId` (string, required, min length 1). Identifier for the ticket.
- `code` (string, pattern ^[A-Z0-9]{4}-[A-Z0-9]{4}$). Stable machine-readable code for this result.
- `browserContext` (string, required, pattern ^[A-Za-z0-9_-]{43}$). The same in-memory browser context used to submit this assertion. Required even for skip-handoff and completed retries.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/passkey/confirmation" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "ticketId": "string",
  "browserContext": "string"
}'
```

### Responses

#### 200

Current passkey state; pairing may still be pending
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation. Values: `none`, `challenge_pending`, `assertion_sending`, `assertion_submitted`, `code_available`, `confirmation_sending`, `waiting_for_pairing`, `completed`, `failed`.
  - `ticketId` (string). Identifier for the ticket.
  - `code` (string). Stable machine-readable code for this result.
  - `skipHandoffUX` (boolean). Whether skip handoff ux.
  - `error` (string). Error details returned when the operation fails.

```json
{
  "data": {
    "status": "none"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

Confirmation is unavailable for this attempt
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 413

Passkey request body exceeds 1048576 bytes

#### 422

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 503

Confirmation is temporarily unavailable or its request deadline was exhausted
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```

## Submit quick link passkey

`POST https://api.polymorfa.com/quicklink/{token}/passkey` (Messaging API)

The complete HTTP body is limited to 1048576 UTF-8 bytes before JSON parsing. Credential IDs allow at most 1023 decoded bytes; user handles allow 64. Opaque assertion fields share the body budget without independent small caps. Redeems a pending passkey ceremony challenge for the session bound to this QuickLink.

### Path parameters

- `token` (string, required). Opaque token required by the target operation.

### Body

- `ticketId` (string, required, min length 1). Identifier for the ticket.
- `browserContext` (string, required, pattern ^[A-Za-z0-9_-]{43}$). 32 cryptographically random bytes, encoded as unpadded base64url. Create once per browser attempt and keep only in memory; reuse for retries, private polling and confirmation.
- `assertion` (object, required). Specifies assertion for this native quick link passkey submit request.
  - `id` (string, required, length 1–1364). Identifier for this resource.
  - `rawIdB64Url` (string, required, length 1–1364). URL for the raw id b64.
  - `response` (object, required). Structured response values for this native quick link passkey assertion.
    - `authenticatorDataB64` (string, required, min length 1). Specifies authenticator data b64 for this response.
    - `clientDataJSONB64` (string, required, min length 1). Specifies client data jsonb64 for this response.
    - `signatureB64` (string, required, min length 1). Specifies signature b64 for this response.
    - `userHandleB64` (string, max length 86). Specifies user handle b64 for this response.

### Request

```bash
curl -X POST "https://api.polymorfa.com/quicklink/<token>/passkey" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "ticketId": "string",
  "browserContext": "string",
  "assertion": {
    "id": "string",
    "rawIdB64Url": "string",
    "response": {
      "authenticatorDataB64": "string",
      "clientDataJSONB64": "string",
      "signatureB64": "string"
    }
  }
}'
```

### Responses

#### 200

Passkey assertion accepted
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation. Values: `submitted`.

```json
{
  "data": {
    "status": "submitted"
  }
}
```

#### 400

QuickLink request failed
- `error` (object, required). Error details returned when the operation fails.
  - `code` (string, required). Stable machine-readable code for this result.
  - `message` (string, required). Human-readable message associated with this result.
- `data` (object). Structured data carried by this object.
  - `candidates` (array of object, required). Candidates associated with this data.
    - `phone` (string, required). Phone number in international format.
    - `whatsappPhone` (string). Specifies whatsapp phone for this candidate.
    - `registered` (boolean, required, nullable). Whether WhatsApp registration was confirmed. Null means the result is unknown.
    - `pushName` (string, required, nullable). WhatsApp display name reported by the sender's client.
    - `pictureUrl` (string, required, nullable). URL for the picture.
    - `accountType` (string). Category assigned to account. Values: `whatsapp`, `business_app`, `cloud_api`, `coexistence`, `unknown`, `unregistered`.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 403

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "type": "permission_error"
  }
}
```

#### 404

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "type": "invalid_request_error"
  }
}
```

#### 409

An assertion is already being forwarded for this ticket
Same fields as 400.

```json
{
  "error": {
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "type": "conflict_error"
  }
}
```

#### 410

Passkey ticket expired
Same fields as 400.

```json
{
  "error": {
    "code": "resource_gone",
    "message": "The requested retained resource has expired or was removed.",
    "type": "invalid_request_error"
  }
}
```

#### 413

Passkey assertion body exceeds 1048576 UTF-8 bytes before JSON parsing.
- `error` (string, required). Error details returned when the operation fails.
- `code` (string, required). Stable machine-readable code for this result. Values: `passkey_payload_too_large`.

```json
{
  "error": "string",
  "code": "passkey_payload_too_large"
}
```

#### 422

Assertion validation or ticket binding failed
Same fields as 400.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "type": "invalid_request_error"
  }
}
```

#### 429

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "The request limit was reached. Follow Retry-After when supplied.",
    "type": "rate_limit_error"
  }
}
```

#### 500

QuickLink request failed
Same fields as 400.

```json
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "type": "api_error"
  }
}
```

#### 502

Session runner rejected the assertion
Same fields as 400.

```json
{
  "error": {
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "type": "upstream_error"
  }
}
```

#### 503

Assertion forwarding is temporarily unavailable or its request deadline was exhausted
Same fields as 400.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "type": "api_error"
  }
}
```
