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

Customers

View as Markdown

The customer object

Attributes

  • idstring (uuid)required

    Identifier for this resource.

  • teamIdstring (uuid)required

    Identifier for the team.

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • namestringrequirednullablemax length120

    Human-readable name for this resource.

  • externalCustomerIdstringrequirednullablemax length200

    Identifier for the external customer.

  • statusstringrequired

    Current status of this resource or operation.

    Allowed valuesactivearchivingarchived
  • isDefaultbooleanrequired

    Whether default.

  • archivedAtintegerrequirednullableformatint64

    Timestamp for archived at.

  • createdAtintegerrequiredformatint64

    Unix timestamp in milliseconds when this resource was created.

  • updatedAtintegerrequiredformatint64

    Unix timestamp in milliseconds when this resource was last updated.

The customer object
{
  "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

POST/platform/customersPlatform API
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–255

    Specifies idempotency key for this header parameter.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • namestringnullablelength1–120

    Human-readable name for this resource.

  • externalCustomerIdstringnullablelength1–200

    Identifier for the external customer.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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`).
POST /platform/customerscURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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
  }
}

List customers

GET/platform/customersPlatform API
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

  • projectIdstringrequired

    Identifier of the Polymorfa project that owns this resource.

  • cursorstring

    Specifies cursor for this query parameter.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25
  • searchstring

    Specifies search for this query parameter.

  • statusstring

    Current status of this resource or operation.

    Allowed valuesactivearchivingarchivedall
  • isDefaultboolean

    Whether default.

  • hasNumbersboolean

    Whether numbers.

  • needsAttentionboolean

    Whether needs attention.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 15 child fields
    • pageobjectrequired

      Specifies 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.
GET /platform/customerscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/customers?projectId=<projectId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/customers/{customerId}/numbersPlatform API
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)required

    Identifier for the customer.

Query parameters

  • projectIdstringrequired

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataarray of objectrequired

      Structured 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.
GET /platform/customers/{customerId}/numberscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/customers/<customerId>/numbers?projectId=<projectId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/customers/{customerId}/eventsPlatform API
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)required

    Identifier for the customer.

Query parameters

  • projectIdstringrequired

    Identifier of the Polymorfa project that owns this resource.

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 25

Responses

  • 200Success
    • dataarray of objectrequired

      Structured 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.
GET /platform/customers/{customerId}/eventscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/customers/<customerId>/events?projectId=<projectId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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
    }
  ]
}

Get customers status

GET/platform/projects/{projectId}/customers/statusPlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/projects/{projectId}/customers/statuscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/projects/<projectId>/customers/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

GET/platform/customers/{customerId}Platform API
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)required

    Identifier for the customer.

Query parameters

  • projectIdstringrequired

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
GET /platform/customers/{customerId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/customers/<customerId>?projectId=<projectId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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

PATCH/platform/customers/{customerId}Platform API
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)required

    Identifier for the customer.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • namestringnullablelength1–120

    Human-readable name for this resource.

  • externalCustomerIdstringnullablelength1–200

    Identifier for the external customer.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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.
PATCH /platform/customers/{customerId}cURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

POST/platform/projects/{projectId}/customers/enablePlatform API
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)required

    Identifier of the Polymorfa project that owns this resource.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

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.
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`).
POST /platform/projects/{projectId}/customers/enablecURL
Not available with the Test key. Use a team key or project token.
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>"
Response
{
  "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

POST/platform/customers/{customerId}/archivePlatform API
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)required

    Identifier for the customer.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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`).
POST /platform/customers/{customerId}/archivecURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

POST/platform/customers/{customerId}/restorePlatform API
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)required

    Identifier for the customer.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured 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`).
POST /platform/customers/{customerId}/restorecURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "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

POST/platform/customers/{customerId}/numbers/{sessionId}/transferPlatform API
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)required

    Identifier for the customer.

  • sessionIdstringrequiredlength1–64

    Database session UUID or stable session slug.

Headers

  • Idempotency-Keystringrequiredlength1–255

    Specifies idempotency key for this header parameter.

Body

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • sourceCustomerIdstring (uuid)required

    Identifier for the source customer.

  • confirmbooleanrequired

    Whether confirm.

    Allowed valuestrue

Responses

  • 200Success
    • dataobjectrequired

      Structured 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`).
POST /platform/customers/{customerId}/numbers/{sessionId}/transfercURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "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
  }
}