Customers
The customer object
Attributes
idstring (uuid)requiredIdentifier for this resource.
teamIdstring (uuid)requiredIdentifier for the team.
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
namestringrequirednullablemax length120Human-readable name for this resource.
externalCustomerIdstringrequirednullablemax length200Identifier for the external customer.
statusstringrequiredCurrent status of this resource or operation.
Allowed valuesactivearchivingarchivedisDefaultbooleanrequiredWhether default.
archivedAtintegerrequirednullableformatint64Timestamp for archived at.
createdAtintegerrequiredformatint64Unix timestamp in milliseconds when this resource was created.
updatedAtintegerrequiredformatint64Unix timestamp in milliseconds when this resource was last updated.
{
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}Create customer
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Creates a Customer with optional name and caller-defined external identifier.
Requires customers:manage. Project tokens only access resources in their own project.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
namestringnullablelength1–120Human-readable name for this resource.
externalCustomerIdstringnullablelength1–200Identifier for the external customer.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 10 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.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/customers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>" \
-H "Content-Type: application/json" \
-d '{
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string"
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}
}Create customer pairing link
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Creates a revocable Customer invitation. The raw URL is returned only in this response.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
expectedPhonestringnullableOptional expected phone, normalized to E.164. Creation attempts WhatsApp registration resolution; confirmed nonregistration is rejected, while an inconclusive result remains unknown.
methodsarray of stringitems1–2unique itemsConnection methods enabled for the widget.
Allowed valuesqrphoneexpiresInSecondsintegerrange900–604800Specifies expires in seconds for this management create customer pairing link request.
Default86400
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 27 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.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/pairing-links" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>" \
-H "Content-Type: application/json" \
-d '{
"projectId": "00000000-0000-4000-8000-000000000000",
"expectedPhone": "string",
"methods": [
"qr"
],
"expiresInSeconds": 86400
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"customerId": "00000000-0000-4000-8000-000000000000",
"expectedPhoneMasked": "string",
"methods": [
"qr"
],
"locale": "en",
"theme": "light",
"expiresAt": 0,
"status": "active",
"attemptCount": 0,
"maxAttempts": 1,
"pendingSessionId": "00000000-0000-4000-8000-000000000000",
"createdBy": "string",
"reservedAt": 0,
"openedAt": 0,
"connectingAt": 0,
"connectedAt": 0,
"failedAt": 0,
"expiredAt": 0,
"revokedAt": 0,
"lastErrorCode": "string",
"failedExchangeCount": 0,
"phoneMismatchCount": 0,
"createdAt": 0,
"updatedAt": 0,
"url": "https://example.com"
}
}List customers
- Base URL
https://api.polymorfa.com- Required permission
customers:read
Lists masked Customer summaries in the exact authenticated project with cursor pagination and filters.
Requires customers:read. Project tokens only access resources in their own project.
Query parameters
projectIdstringrequiredIdentifier of the Polymorfa project that owns this resource.
cursorstringSpecifies cursor for this query parameter.
limitintegerrange1–100Specifies limit for this query parameter.
Default25searchstringSpecifies search for this query parameter.
statusstringCurrent status of this resource or operation.
Allowed valuesactivearchivingarchivedallisDefaultbooleanWhether default.
hasNumbersbooleanWhether numbers.
needsAttentionbooleanWhether needs attention.
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 15 child fields
pageobjectrequiredSpecifies page for this schema.
Show 2 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/customers?projectId=<projectId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"numberCount": 0,
"connectedNumberCount": 0,
"activePairingLinkState": "string",
"lastActivityAt": 0,
"needsAttention": true,
"createdAt": 0,
"updatedAt": 0
}
],
"page": {
"nextCursor": "string",
"hasMore": true
}
}List customer numbers
- Base URL
https://api.polymorfa.com- Required permission
customers:read
Lists Numbers assigned to one Customer in the exact project.
Requires customers:read. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Query parameters
projectIdstringrequiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 8 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/customers/<customerId>/numbers?projectId=<projectId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"customerId": "00000000-0000-4000-8000-000000000000",
"sessionId": "string",
"name": "string",
"phoneMasked": "string",
"status": "string",
"backend": "string",
"createdAt": 0
}
]
}List customer events
- Base URL
https://api.polymorfa.com- Required permission
customers:read
Lists the newest Customer lifecycle events with safe metadata. Actor identities, message content, phone values, invitation tokens, and URLs are excluded.
Requires customers:read. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Query parameters
projectIdstringrequiredIdentifier of the Polymorfa project that owns this resource.
limitintegerrange1–100Specifies limit for this query parameter.
Default25
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 8 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/customers/<customerId>/events?projectId=<projectId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"action": "string",
"fromStatus": "string",
"toStatus": "string",
"sessionId": "00000000-0000-4000-8000-000000000000",
"pairingLinkId": "00000000-0000-4000-8000-000000000000",
"metadata": {
"fields": [
"name"
]
},
"occurredAt": 0
}
]
}List customer pairing links
- Base URL
https://api.polymorfa.com- Required permission
customers:read
Lists safe pairing-link metadata. Raw invitation tokens and URLs are never returned.
Requires customers:read. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Query parameters
projectIdstringrequiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataarray of objectrequiredStructured data carried by this object.
Show 26 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/customers/<customerId>/pairing-links?projectId=<projectId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"customerId": "00000000-0000-4000-8000-000000000000",
"expectedPhoneMasked": "string",
"methods": [
"qr"
],
"locale": "en",
"theme": "light",
"expiresAt": 0,
"status": "active",
"attemptCount": 0,
"maxAttempts": 1,
"pendingSessionId": "00000000-0000-4000-8000-000000000000",
"createdBy": "string",
"reservedAt": 0,
"openedAt": 0,
"connectingAt": 0,
"connectedAt": 0,
"failedAt": 0,
"expiredAt": 0,
"revokedAt": 0,
"lastErrorCode": "string",
"failedExchangeCount": 0,
"phoneMismatchCount": 0,
"createdAt": 0,
"updatedAt": 0
}
]
}Get customers status
- Base URL
https://api.polymorfa.com- Required permission
customers:read
Returns whether Customers is enabled for the exact project and its protected default Customer when enabled.
Requires customers:read. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 4 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/projects/<projectId>/customers/status" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"enabled": true,
"enabledAt": 0,
"enabledBy": "string",
"defaultCustomer": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}
}
}Get customer
- Base URL
https://api.polymorfa.com- Required permission
customers:read
Returns one Customer from the exact authenticated project.
Requires customers:read. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Query parameters
projectIdstringrequiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 10 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/customers/<customerId>?projectId=<projectId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}
}Update customer
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Updates supplied Customer profile fields. Null clears an optional field.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
namestringnullablelength1–120Human-readable name for this resource.
externalCustomerIdstringnullablelength1–200Identifier for the external customer.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 10 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/customers/<customerId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string"
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}
}Enable customers
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Enables Customers once, creates the default Customer, and assigns every existing Number in the project to it atomically.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
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.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/customers/enable" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>"{
"data": {
"enabled": true,
"enabledAt": 0,
"enabledBy": "string",
"defaultCustomer": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
},
"migratedNumberCount": 0
}
}Archive customer
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Archives a non-default Customer. The default Customer cannot be archived.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 10 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.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/archive" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>" \
-H "Content-Type: application/json" \
-d '{
"projectId": "00000000-0000-4000-8000-000000000000"
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}
}Restore customer
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Restores an archived Customer.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
projectIdstring (uuid)Identifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 10 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.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/restore" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>" \
-H "Content-Type: application/json" \
-d '{
"projectId": "00000000-0000-4000-8000-000000000000"
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"name": "string",
"externalCustomerId": "string",
"status": "active",
"isDefault": true,
"archivedAt": 0,
"createdAt": 0,
"updatedAt": 0
}
}Transfer customer number
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Atomically transfers one eligible Number from the explicitly confirmed source Customer to the destination Customer.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
sessionIdstringrequiredlength1–64Database session UUID or stable session slug.
Headers
Idempotency-Keystringrequiredlength1–255Specifies idempotency key for this header parameter.
Body
projectIdstring (uuid)requiredIdentifier of the Polymorfa project that owns this resource.
sourceCustomerIdstring (uuid)requiredIdentifier for the source customer.
confirmbooleanrequiredWhether confirm.
Allowed valuestrue
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 8 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.
422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/numbers/<sessionId>/transfer" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Idempotency-Key: <idempotency_key>" \
-H "Content-Type: application/json" \
-d '{
"projectId": "00000000-0000-4000-8000-000000000000",
"sourceCustomerId": "00000000-0000-4000-8000-000000000000",
"confirm": true
}'{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"customerId": "00000000-0000-4000-8000-000000000000",
"sessionId": "string",
"name": "string",
"phoneMasked": "string",
"status": "string",
"backend": "string",
"createdAt": 0
}
}Revoke customer pairing link
- Base URL
https://api.polymorfa.com- Required permission
customers:manage
Revokes an open pairing link.
Requires customers:manage. Project tokens only access resources in their own project.
Path parameters
customerIdstring (uuid)requiredIdentifier for the customer.
pairingLinkIdstringrequiredIdentifier for the pairing link.
Query parameters
projectIdstringrequiredIdentifier of the Polymorfa project that owns this resource.
Responses
200Success
dataobjectrequiredStructured data carried by this object.
Show 26 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 DELETE "https://api.polymorfa.com/platform/customers/<customerId>/pairing-links/<pairingLinkId>?projectId=<projectId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"data": {
"id": "00000000-0000-4000-8000-000000000000",
"teamId": "00000000-0000-4000-8000-000000000000",
"projectId": "00000000-0000-4000-8000-000000000000",
"customerId": "00000000-0000-4000-8000-000000000000",
"expectedPhoneMasked": "string",
"methods": [
"qr"
],
"locale": "en",
"theme": "light",
"expiresAt": 0,
"status": "active",
"attemptCount": 0,
"maxAttempts": 1,
"pendingSessionId": "00000000-0000-4000-8000-000000000000",
"createdBy": "string",
"reservedAt": 0,
"openedAt": 0,
"connectingAt": 0,
"connectedAt": 0,
"failedAt": 0,
"expiredAt": 0,
"revokedAt": 0,
"lastErrorCode": "string",
"failedExchangeCount": 0,
"phoneMismatchCount": 0,
"createdAt": 0,
"updatedAt": 0
}
}