Numbers
The session object
Attributes
signalModestringImmutable Signal key custody selected before pairing. Customer-owned custody is a gated beta for real Linked Devices.
Allowed valuesstandardzero_knowledgesessionIdstringrequiredSession ID. Use it to address this session in Platform and Messaging requests.
namestringrequiredDisplay label, or the session identifier when no label is set.
externalIdstringIntegrator correlation supplied when creating the QuickLink for this session.
tenantIdstringrequiredIdentifier of the team that owns this resource.
typestringrequiredHow 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_apitestModebooleanrequiredWhether this session was created as a simulated testing number.
statusstringrequiredCurrent status: CONNECTING, CONNECTED, or DISCONNECTED
statusReasonstringReason for the current status.
configurationobjectSpecifies configuration for this management platform access session.
Show 7 child fields
newChatCappingobjectnullableSpecifies new chat capping for this management platform access session.
Show 10 child fields
inspectorobjectInspector state for this Number. Returned by Get session only.
Show 1 child field
createdAtstringrequiredISO 8601 timestamp when this resource was created.
updatedAtstringrequiredISO 8601 timestamp when this resource was last updated.
{
"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
- 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–64Database session UUID or stable session slug.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"data": {
"starting": true,
"sessionId": "00000000-0000-4000-8000-000000000000"
}
}List sessions
- 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
projectIdstringIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataarray of objectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/sessions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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–128Identifier of the connected Polymorfa session.
Responses
200Credential health
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 8 child fields
Show 3 headers
400Request failed
401Request failed
403Request failed
404Request failed
409Request failed
500Request failed
503Request failed
curl "https://api.polymorfa.com/messaging/<session>/cloud-credentials" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Responses
200Session details
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
curl "https://api.polymorfa.com/platform/sessions/<sessionId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"sessionId": "string",
"name": "string",
"tenantId": "string",
"type": "linked_device",
"testMode": true,
"status": "string",
"createdAt": "string",
"updatedAt": "string"
}
}Get session account
- Base URL
https://api.polymorfa.com- Required permission
sessions:read
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Responses
200Account info
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/me" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"pushName": "string"
}
}Get handoff keys
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Responses
200Destination pubkey + correlation id for the handoff
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/handoff-keys" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": {
"runnerPublicKeyB64": "string",
"handoffId": "string"
}
}Get session tier change
- 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–64Database session UUID or stable session slug.
quoteIdstringrequiredIdentifier for the quote.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/tier-quotes/<quoteId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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–64Database session UUID or stable session slug.
Responses
200Success
dataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/platform/sessions/<sessionId>/capabilities" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Body
configurationobjectrequiredStructured configuration values for this management platform access update session request.
Show 2 child fields
revisionintegerrequiredmin0Specifies revision for this management platform access update session request.
Responses
200Desired configuration stored; application reports pending until the runtime acknowledges
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
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
}'{
"success": true,
"data": {
"sessionId": "string",
"name": "string",
"tenantId": "string",
"type": "linked_device",
"testMode": true,
"status": "string",
"createdAt": "string",
"updatedAt": "string"
}
}Set session tier override
- 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–64Database session UUID or stable session slug.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
quoteIdstring (uuid)requiredIdentifier for the quote.
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"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
- 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
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Responses
202Restart requested; completion is asynchronous
successbooleanrequiredWhether the request succeeded.
Allowed valuestruemessagestringrequiredHuman-readable message associated with this result.
immediatebooleanWhether 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
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/restart" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"message": "string"
}Logout session
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Responses
202Session logout scheduled
successbooleanrequiredWhether the request succeeded.
Allowed valuestruemessagestringrequiredHuman-readable message associated with this result.
immediatebooleanWhether 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
curl -X POST "https://api.polymorfa.com/platform/sessions/<sessionId>/logout" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"message": "string"
}Import handoff state
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Body
handoffIdstringrequiredRound-trip id returned by POST /handoff-keys.
sealedEnvelopeB64stringrequiredSealed-box envelope (ephemeral_pub(32) || ciphertext) wrapping the customer's SignalStoreSnapshot. Base64.
snapshotHashHexstringrequiredSHA-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
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
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"
}'{
"success": true,
"data": {
"success": true
}
}Upload app-state keys
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Body
keysarray of objectrequiredmax items1000Keys associated with this management platform access upload app state keys request.
Show 4 child fields
upgradeTostringWhen 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
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
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
}
]
}'{
"success": true,
"data": {
"success": true
}
}Confirm handoff
- Base URL
https://api.polymorfa.com- Required permission
sessions:manage
Path parameters
sessionIdstringrequiredIdentifier of the connected Polymorfa session.
Body
handoffIdstringrequiredIdentifier of the session handoff operation.
snapshotHashHexstringrequiredSHA-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
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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
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"
}'{
"success": true,
"data": {
"success": true
}
}Quote session tier change
- 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–64Database session UUID or stable session slug.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
tierOverridestringrequirednullableSpecifies tier override for this management number tier quote request.
Allowed valuesfreestandardpro
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"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
- 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–64Database session UUID or stable session slug.
Body
expectedClaimedAtstring (date-time)The
inspector.claim.claimedAtvalue you last read. A different current claim returns 409.
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"data": {
"released": true
}
}Stop session
- 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–64Database session UUID or stable session slug.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured 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.
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"
}'{
"data": {
"stopping": true,
"sessionId": "00000000-0000-4000-8000-000000000000"
}
}Stop sessions
- 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–64Session ids associated with this management session batch request.
Responses
200Success
dataobjectrequiredStructured 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.
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"
]
}'{
"data": {
"stopping": 0
}
}Delete session
- 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–64Database session UUID or stable session slug.
Responses
200Success
dataobjectrequiredStructured 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.
curl -X DELETE "https://api.polymorfa.com/platform/sessions/<sessionId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"removed": true,
"sessionId": "00000000-0000-4000-8000-000000000000"
}
}Delete sessions
- 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–64Session ids associated with this management session batch request.
Responses
200Success
dataobjectrequiredStructured 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.
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"
]
}'{
"data": {
"removed": 0
}
}