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

Numbers

View as Markdown

The session object

Attributes

  • signalModestring

    Immutable Signal key custody selected before pairing. Customer-owned custody is a gated beta for real Linked Devices.

    Allowed valuesstandardzero_knowledge
  • sessionIdstringrequired

    Session ID. Use it to address this session in Platform and Messaging requests.

  • namestringrequired

    Display label, or the session identifier when no label is set.

  • externalIdstring

    Integrator correlation supplied when creating the QuickLink for this session.

  • tenantIdstringrequired

    Identifier of the team that owns this resource.

  • typestringrequired

    How the session connects to WhatsApp. 'linked_device' pairs as a WhatsApp linked device; 'cloud_api' uses the Meta Cloud API. Immutable after create.

    Allowed valueslinked_devicecloud_api
  • testModebooleanrequired

    Whether this session was created as a simulated testing number.

  • statusstringrequired

    Current status: CONNECTING, CONNECTED, or DISCONNECTED

  • statusReasonstring

    Reason for the current status.

  • configurationobject

    Specifies configuration for this management platform access session.

    Show 7 child fields
  • newChatCappingobjectnullable

    Specifies new chat capping for this management platform access session.

    Show 10 child fields
  • inspectorobject

    Inspector state for this Number. Returned by Get session only.

    Show 1 child field
  • createdAtstringrequired

    ISO 8601 timestamp when this resource was created.

  • updatedAtstringrequired

    ISO 8601 timestamp when this resource was last updated.

The session object
{
  "signalMode": "standard",
  "sessionId": "string",
  "name": "string",
  "externalId": "string",
  "tenantId": "string",
  "type": "linked_device",
  "testMode": true,
  "status": "string",
  "statusReason": "string",
  "configuration": {
    "requestedHistory": {
      "mode": "metadata_only",
      "requestFull": true,
      "delivery": "archive"
    },
    "historyConsent": "pending",
    "effective": {
      "observation": {
        "presenceMode": "off",
        "typingMode": "off",
        "labelMode": "off",
        "quickReplyMode": "off"
      },
      "historySync": {
        "mode": "metadata_only",
        "requestFull": true,
        "delivery": "archive"
      },
      "hms": {
        "enabled": false
      }
    },
    "overrides": {
      "historySync": {
        "mode": "metadata_only",
        "requestFull": true,
        "delivery": "descriptor"
      },
      "hms": {
        "enabled": false
      },
      "observation": {
        "presenceMode": "off",
        "typingMode": "off",
        "labelMode": "off",
        "quickReplyMode": "off"
      }
    },
    "sources": {
      "observation.presenceMode": "platform",
      "observation.typingMode": "platform",
      "observation.labelMode": "platform",
      "observation.quickReplyMode": "platform",
      "historySync.mode": "platform",
      "historySync.requestFull": "platform",
      "historySync.delivery": "platform",
      "hms": "platform"
    },
    "revisions": {
      "team": 0,
      "project": 0,
      "session": 0
    },
    "application": {
      "desiredGeneration": 0,
      "appliedGeneration": 0,
      "status": "pending"
    }
  },
  "newChatCapping": {
    "enabled": true,
    "pacing": true,
    "status": "first_warning",
    "capped": true,
    "limit": 50,
    "used": 26,
    "remaining": 24,
    "cycleStartsAt": "string",
    "resetsAt": "string",
    "observedAt": "string"
  },
  "inspector": {
    "claim": {
      "claimed": true,
      "claimedAt": "2026-09-22T12:00:00Z"
    }
  },
  "createdAt": "string",
  "updatedAt": "string"
}

Start session

POST/platform/sessions/{sessionId}/startPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

A start request creates an operation. Keep its operation ID and check the operation until it reaches a terminal status. A pending or running operation does not mean the number is connected.

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 402`billing_credit_required`: the paid number could not reserve enough available credit. Add credit to your team before starting it.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 500The session-control publisher or testing-number persistence path is temporarily unavailable.
POST /platform/sessions/{sessionId}/startcURL
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "00000000-0000-4000-8000-000000000000"
}'
Response
{
  "data": {
    "starting": true,
    "sessionId": "00000000-0000-4000-8000-000000000000"
  }
}

List sessions

GET/platform/sessionsPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

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

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

Query parameters

  • projectIdstring

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 18 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/sessionscURL
curl "https://api.polymorfa.com/platform/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": [
    {
      "_id": "00000000-0000-4000-8000-000000000000",
      "_creationTime": 0,
      "projectId": "00000000-0000-4000-8000-000000000000",
      "sessionId": "string",
      "name": "string",
      "phone": "string",
      "platform": "string",
      "isBusiness": true,
      "testMode": true,
      "tierOverride": "free",
      "status": "string",
      "statusReason": "string",
      "messageCount": 0,
      "lastActiveAt": 0,
      "paidUntil": 0,
      "customer": {
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "isDefault": true
      },
      "claim": {
        "kind": "unclaimed"
      },
      "inspector": {
        "claim": {
          "claimed": true,
          "claimedAt": "2026-09-22T12:00:00Z"
        }
      }
    }
  ]
}

Get cloud credential health

GET/messaging/{session}/cloud-credentialsMessaging APIMeta Cloud API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

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

Path parameters

  • sessionstringrequiredlength1–128

    Identifier of the connected Polymorfa session.

Responses

GET /messaging/{session}/cloud-credentialscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/cloud-credentials" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "status": "pending",
    "checkedAt": "2026-09-22T12:00:00Z",
    "nextCheckAt": "2026-09-22T12:00:00Z",
    "token": {
      "status": "valid",
      "expiresAt": "2026-09-22T12:00:00Z"
    },
    "missingPermissions": [
      "whatsapp_business_messaging"
    ],
    "phoneRegistration": "registered",
    "webhookSubscription": "subscribed",
    "failureCode": "app_credentials_rejected"
  }
}

Get session

GET/platform/sessions/{sessionId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Session details
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 14 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /platform/sessions/{sessionId}cURL
curl "https://api.polymorfa.com/platform/sessions/<sessionId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "sessionId": "string",
    "name": "string",
    "tenantId": "string",
    "type": "linked_device",
    "testMode": true,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Get session account

GET/platform/sessions/{sessionId}/mePlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Account info
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 9 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /platform/sessions/{sessionId}/mecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/me" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "pushName": "string"
  }
}

Get handoff keys

POST/platform/sessions/{sessionId}/handoff-keysPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Destination pubkey + correlation id for the handoff
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/sessions/{sessionId}/handoff-keyscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/handoff-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "runnerPublicKeyB64": "string",
    "handoffId": "string"
  }
}

Get session tier change

GET/platform/sessions/{sessionId}/tier-quotes/{quoteId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

  • quoteIdstringrequired

    Identifier for the quote.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/sessions/{sessionId}/tier-quotes/{quoteId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/tier-quotes/<quoteId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "status": "quoted",
    "failureReason": "string",
    "expiresAtMs": 0,
    "quote": {
      "tier": "string",
      "tierOverride": "string",
      "amountCents": 0,
      "priceVersion": "string",
      "action": "upgrade",
      "effectiveAtMs": 0,
      "replacesWindowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}

Get session capabilities

GET/platform/sessions/{sessionId}/capabilitiesPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 7 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
GET /platform/sessions/{sessionId}/capabilitiescURL
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/capabilities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "session": "string",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "status": "synced",
    "syncedAt": "2026-09-22T12:00:00Z",
    "checkedAt": "2026-09-22T12:00:00Z",
    "accountType": "business",
    "capabilities": [
      {
        "key": "string",
        "kind": "feature",
        "unit": "seconds",
        "value": true,
        "source": "server"
      }
    ]
  }
}

Update session

PUT/platform/sessions/{sessionId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Body

  • configurationobjectrequired

    Structured configuration values for this management platform access update session request.

    Show 2 child fields
  • revisionintegerrequiredmin0

    Specifies revision for this management platform access update session request.

Responses

  • 200Desired configuration stored; application reports pending until the runtime acknowledges
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 14 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409Configuration revision changed or previous runtime cleanup is required before changing history delivery
  • 500Internal server error
  • 503Session configuration persistence is unavailable
PUT /platform/sessions/{sessionId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/sessions/<sessionId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "configuration": {
    "set": {
      "historySync": {
        "mode": "metadata_only",
        "requestFull": true,
        "delivery": "descriptor"
      },
      "hms": {
        "enabled": false
      },
      "observation": {
        "presenceMode": "off",
        "typingMode": "off",
        "labelMode": "off",
        "quickReplyMode": "off"
      }
    },
    "reset": [
      "historySync"
    ]
  },
  "revision": 0
}'
Response
{
  "success": true,
  "data": {
    "sessionId": "string",
    "name": "string",
    "tenantId": "string",
    "type": "linked_device",
    "testMode": true,
    "status": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Reauthorize cloud credentials

POST/messaging/{session}/cloud-credentials/reauthorizeMessaging APIMeta Cloud API
Base URL
https://api.polymorfa.com
Required permission
quicklink:manage

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

Path parameters

  • sessionstringrequiredlength1–128

    Identifier of the connected Polymorfa session.

Responses

POST /messaging/{session}/cloud-credentials/reauthorizecURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/<session>/cloud-credentials/reauthorize" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "quicklinkId": "string",
    "url": "string",
    "session": "string"
  }
}

Set session tier override

PATCH/platform/sessions/{sessionId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • quoteIdstring (uuid)required

    Identifier for the quote.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
PATCH /platform/sessions/{sessionId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PATCH "https://api.polymorfa.com/platform/sessions/<sessionId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": "00000000-0000-4000-8000-000000000000"
}'
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "status": "quoted",
    "failureReason": "string",
    "expiresAtMs": 0,
    "quote": {
      "tier": "string",
      "tierOverride": "string",
      "amountCents": 0,
      "priceVersion": "string",
      "action": "upgrade",
      "effectiveAtMs": 0,
      "replacesWindowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}

Restart session

POST/platform/sessions/{sessionId}/restartPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 202Restart requested; completion is asynchronous
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • messagestringrequired

      Human-readable message associated with this result.

    • immediateboolean

      Whether immediate.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/sessions/{sessionId}/restartcURL
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/restart" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "message": "string"
}

Logout session

POST/platform/sessions/{sessionId}/logoutPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 202Session logout scheduled
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • messagestringrequired

      Human-readable message associated with this result.

    • immediateboolean

      Whether immediate.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/sessions/{sessionId}/logoutcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/logout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "message": "string"
}

Import handoff state

POST/platform/sessions/{sessionId}/handoff-importPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Body

  • handoffIdstringrequired

    Round-trip id returned by POST /handoff-keys.

  • sealedEnvelopeB64stringrequired

    Sealed-box envelope (ephemeral_pub(32) || ciphertext) wrapping the customer's SignalStoreSnapshot. Base64.

  • snapshotHashHexstringrequired

    SHA-256 of the unsealed snapshot JSON, hex-encoded. The runner verifies after decrypt before flipping bartenderMode.

Responses

  • 200Import accepted; bartenderMode will flip after the runner acks
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/sessions/{sessionId}/handoff-importcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/handoff-import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "handoffId": "string",
  "sealedEnvelopeB64": "string",
  "snapshotHashHex": "string"
}'
Response
{
  "success": true,
  "data": {
    "success": true
  }
}

Upload app-state keys

POST/platform/sessions/{sessionId}/upload-appstate-keysPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Body

  • keysarray of objectrequiredmax items1000

    Keys associated with this management platform access upload app state keys request.

    Show 4 child fields
  • upgradeTostring

    When set, atomically flips sessions.config.bartenderMode → passthrough_plus after the keys persist. Eliminates the window where mode is set but no keys are staged.

    Allowed valuespassthrough_plus

Responses

  • 200Keys persisted; mode may have been flipped per upgradeTo
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/sessions/{sessionId}/upload-appstate-keyscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/upload-appstate-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "keys": [
    {
      "keyId": "string",
      "keyB64": "string",
      "timestamp": 0
    }
  ]
}'
Response
{
  "success": true,
  "data": {
    "success": true
  }
}

Confirm handoff

POST/platform/sessions/{sessionId}/handoff-ackPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionIdstringrequired

    Identifier of the connected Polymorfa session.

Body

  • handoffIdstringrequired

    Identifier of the session handoff operation.

  • snapshotHashHexstringrequired

    SHA-256 of the snapshot the customer received via mode.handoff_export. API verifies this matches what the runner exported before flipping bartenderMode.

Responses

  • 200Ack accepted; bartenderMode flipped from magic → passthrough
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/sessions/{sessionId}/handoff-ackcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/handoff-ack" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "handoffId": "string",
  "snapshotHashHex": "string"
}'
Response
{
  "success": true,
  "data": {
    "success": true
  }
}

Quote session tier change

POST/platform/sessions/{sessionId}/tier-quotesPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • tierOverridestringrequirednullable

    Specifies tier override for this management number tier quote request.

    Allowed valuesfreestandardpro

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
POST /platform/sessions/{sessionId}/tier-quotescURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/tier-quotes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "tierOverride": "free"
}'
Response
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "status": "quoted",
    "failureReason": "string",
    "expiresAtMs": 0,
    "quote": {
      "tier": "string",
      "tierOverride": "string",
      "amountCents": 0,
      "priceVersion": "string",
      "action": "upgrade",
      "effectiveAtMs": 0,
      "replacesWindowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}

Release Inspector claim

POST/platform/sessions/{sessionId}/inspector/claim/releasePlatform API
Base URL
https://api.polymorfa.com

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

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

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

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

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Body

  • expectedClaimedAtstring (date-time)

    The inspector.claim.claimedAt value you last read. A different current claim returns 409.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 1 child field
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 503`service_unavailable`: the claimant's Inspector device could not be removed, so the Number is still claimed. Nothing changed. Retry after `Retry-After` seconds; repeating the request is safe.
POST /platform/sessions/{sessionId}/inspector/claim/releasecURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/inspector/claim/release" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedClaimedAt": "2026-09-22T12:00:00Z"
}'
Response
{
  "data": {
    "released": true
  }
}

Stop session

POST/platform/sessions/{sessionId}/stopPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 500The session-control publisher or testing-number persistence path is temporarily unavailable.
POST /platform/sessions/{sessionId}/stopcURL
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/stop" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "00000000-0000-4000-8000-000000000000"
}'
Response
{
  "data": {
    "stopping": true,
    "sessionId": "00000000-0000-4000-8000-000000000000"
  }
}

Stop sessions

POST/platform/sessions/stopPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • sessionIdsarray of stringrequireditems1–100unique itemsitem length1–64

    Session ids associated with this management session batch request.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 1 child field
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 500The session-control publisher or testing-number persistence path is temporarily unavailable.
POST /platform/sessions/stopcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/stop" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionIds": [
    "string"
  ]
}'
Response
{
  "data": {
    "stopping": 0
  }
}

Delete session

DELETE/platform/sessions/{sessionId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

Path parameters

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
DELETE /platform/sessions/{sessionId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/sessions/<sessionId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "removed": true,
    "sessionId": "00000000-0000-4000-8000-000000000000"
  }
}

Delete sessions

POST/platform/sessions/deletePlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

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

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

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • sessionIdsarray of stringrequireditems1–100unique itemsitem length1–64

    Session ids associated with this management session batch request.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 1 child field
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 409The request conflicts with the resource's current state.
POST /platform/sessions/deletecURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sessions/delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionIds": [
    "string"
  ]
}'
Response
{
  "data": {
    "removed": 0
  }
}