# Customers

## Endpoints

- `POST /platform/customers`: [Create customer](https://docs.polymorfa.com/api/customers/create-customer)
- `POST /platform/customers/{customerId}/pairing-links`: [Create customer pairing link](https://docs.polymorfa.com/api/customers/create-customer-pairing-link)
- `GET /platform/customers`: [List customers](https://docs.polymorfa.com/api/customers/list-customers)
- `GET /platform/customers/{customerId}/numbers`: [List customer numbers](https://docs.polymorfa.com/api/customers/list-customer-numbers)
- `GET /platform/customers/{customerId}/events`: [List customer events](https://docs.polymorfa.com/api/customers/list-customer-events)
- `GET /platform/customers/{customerId}/pairing-links`: [List customer pairing links](https://docs.polymorfa.com/api/customers/list-customer-pairing-links)
- `GET /platform/projects/{projectId}/customers/status`: [Get customers status](https://docs.polymorfa.com/api/customers/get-customers-status)
- `GET /platform/customers/{customerId}`: [Get customer](https://docs.polymorfa.com/api/customers/get-customer)
- `PATCH /platform/customers/{customerId}`: [Update customer](https://docs.polymorfa.com/api/customers/update-customer)
- `POST /platform/projects/{projectId}/customers/enable`: [Enable customers](https://docs.polymorfa.com/api/customers/enable-customers)
- `POST /platform/customers/{customerId}/archive`: [Archive customer](https://docs.polymorfa.com/api/customers/archive-customer)
- `POST /platform/customers/{customerId}/restore`: [Restore customer](https://docs.polymorfa.com/api/customers/restore-customer)
- `POST /platform/customers/{customerId}/numbers/{sessionId}/transfer`: [Transfer customer number](https://docs.polymorfa.com/api/customers/transfer-customer-number)
- `DELETE /platform/customers/{customerId}/pairing-links/{pairingLinkId}`: [Revoke customer pairing link](https://docs.polymorfa.com/api/customers/revoke-customer-pairing-link)

## The customer object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `teamId` (string (uuid), required, format uuid). Identifier for the team.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `name` (string, required, nullable, max length 120). Human-readable name for this resource.
- `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
- `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
- `isDefault` (boolean, required). Whether default.
- `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
- `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
- `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.
```json
{
  "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 https://api.polymorfa.com/platform/customers` (Platform API)

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.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `name` (string, nullable, length 1–120). Human-readable name for this resource.
- `externalCustomerId` (string, nullable, length 1–200). Identifier for the external customer.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/customers" \
  -H "Authorization: Bearer <POLYMORFA_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"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
  - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
  - `isDefault` (boolean, required). Whether default.
  - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

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

## Create customer pairing link

`POST https://api.polymorfa.com/platform/customers/{customerId}/pairing-links` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `expectedPhone` (string, nullable). Optional expected phone, normalized to E.164. Creation attempts WhatsApp registration resolution; confirmed nonregistration is rejected, while an inconclusive result remains unknown.
- `methods` (array of string, items 1–2, unique items). Connection methods enabled for the widget. Values: `qr`, `phone`.
- `expiresInSeconds` (integer, range 900–604800). Specifies expires in seconds for this management create customer pairing link request. Default: `86400`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/pairing-links" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `customerId` (string (uuid), required, format uuid). Identifier for the customer.
  - `expectedPhoneMasked` (string, required, nullable). Specifies expected phone masked for this management created customer pairing link.
  - `methods` (array of string, required, items 1–2, unique items). Connection methods enabled for the widget. Values: `qr`, `phone`.
  - `locale` (string, required, nullable). Specifies locale for this management created customer pairing link. Values: `en`, `pt-BR`.
  - `theme` (string, required, nullable). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `expiresAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource expires.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `opened`, `connecting`, `connected`, `failed`, `expired`, `revoked`.
  - `attemptCount` (integer, required, min 0). Number of attempts.
  - `maxAttempts` (integer, required, range 1–20). Specifies max attempts for this management created customer pairing link.
  - `pendingSessionId` (string (uuid), required, nullable, format uuid). Identifier for the pending session.
  - `createdBy` (string, required, nullable). Specifies created by for this management created customer pairing link.
  - `reservedAt` (integer, required, nullable, format int64). Timestamp for reserved at.
  - `openedAt` (integer, required, nullable, format int64). Timestamp for opened at.
  - `connectingAt` (integer, required, nullable, format int64). Timestamp for connecting at.
  - `connectedAt` (integer, required, nullable, format int64). Timestamp for connected at.
  - `failedAt` (integer, required, nullable, format int64). Timestamp for failed at.
  - `expiredAt` (integer, required, nullable, format int64). Timestamp for expired at.
  - `revokedAt` (integer, required, nullable, format int64). Timestamp for revoked at.
  - `lastErrorCode` (string, required, nullable). Machine-readable last error code for this management created customer pairing link.
  - `failedExchangeCount` (integer, required, range 0–5). Number of failed exchanges.
  - `phoneMismatchCount` (integer, required, range 0–3). Number of phone mismatches.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.
  - `url` (string (uri), required, nullable, format uri). Returned once; null on an idempotent replay.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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"
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

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

## List customers

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

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

- `projectId` (string, required). Identifier of the Polymorfa project that owns this resource.
- `cursor` (string). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.
- `search` (string). Specifies search for this query parameter.
- `status` (string). Current status of this resource or operation. Values: `active`, `archiving`, `archived`, `all`.
- `isDefault` (boolean). Whether default.
- `hasNumbers` (boolean). Whether numbers.
- `needsAttention` (boolean). Whether needs attention.

### Request

```bash
curl "https://api.polymorfa.com/platform/customers?projectId=<projectId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
  - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
  - `isDefault` (boolean, required). Whether default.
  - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
  - `numberCount` (integer, required, min 0). Number of numbers.
  - `connectedNumberCount` (integer, required, min 0). Number of connected numbers.
  - `activePairingLinkState` (string, required, nullable). Specifies active pairing link state for this management customer summary.
  - `lastActivityAt` (integer, required, nullable, format int64). Timestamp for last activity at.
  - `needsAttention` (boolean, required). Whether needs attention.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.
- `page` (object, required). Specifies page for this schema.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management cursor page metadata.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

## List customer numbers

`GET https://api.polymorfa.com/platform/customers/{customerId}/numbers` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Query parameters

- `projectId` (string, required). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/customers/<customerId>/numbers?projectId=<projectId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `customerId` (string (uuid), required, format uuid). Identifier for the customer.
  - `sessionId` (string, required). Identifier of the connected Polymorfa session.
  - `name` (string, required, nullable). Human-readable name for this resource.
  - `phoneMasked` (string, required, nullable). Specifies phone masked for this management customer number.
  - `status` (string, required). Current status of this resource or operation.
  - `backend` (string, required, nullable). Specifies backend for this management customer number.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "customerId": "00000000-0000-4000-8000-000000000000",
      "sessionId": "string",
      "name": "string",
      "phoneMasked": "string",
      "status": "string",
      "backend": "string",
      "createdAt": 0
    }
  ]
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

## List customer events

`GET https://api.polymorfa.com/platform/customers/{customerId}/events` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Query parameters

- `projectId` (string, required). Identifier of the Polymorfa project that owns this resource.
- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `25`.

### Request

```bash
curl "https://api.polymorfa.com/platform/customers/<customerId>/events?projectId=<projectId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `action` (string, required, max length 128, pattern ^customer(?:\.[a-z0-9_]+){1,3}$). Action represented by this management customer event.
  - `fromStatus` (string, required, nullable). Specifies from status for this management customer event.
  - `toStatus` (string, required, nullable). Specifies to status for this management customer event.
  - `sessionId` (string (uuid), required, nullable, format uuid). Identifier of the connected Polymorfa session.
  - `pairingLinkId` (string (uuid), required, nullable, format uuid). Identifier for the pairing link.
  - `metadata` (object, required). Structured metadata values for this management customer event.
    - `fields` (array of string, unique items). Fields associated with this metadata. Values: `name`, `phone`, `externalCustomerId`.
  - `occurredAt` (integer, required, format int64). Timestamp for occurred at.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "action": "string",
      "fromStatus": "string",
      "toStatus": "string",
      "sessionId": "00000000-0000-4000-8000-000000000000",
      "pairingLinkId": "00000000-0000-4000-8000-000000000000",
      "metadata": {
        "fields": [
          "name"
        ]
      },
      "occurredAt": 0
    }
  ]
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

## List customer pairing links

`GET https://api.polymorfa.com/platform/customers/{customerId}/pairing-links` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Query parameters

- `projectId` (string, required). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/customers/<customerId>/pairing-links?projectId=<projectId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `customerId` (string (uuid), required, format uuid). Identifier for the customer.
  - `expectedPhoneMasked` (string, required, nullable). Specifies expected phone masked for this management customer pairing link.
  - `methods` (array of string, required, items 1–2, unique items). Connection methods enabled for the widget. Values: `qr`, `phone`.
  - `locale` (string, required, nullable). Specifies locale for this management customer pairing link. Values: `en`, `pt-BR`.
  - `theme` (string, required, nullable). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `expiresAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource expires.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `opened`, `connecting`, `connected`, `failed`, `expired`, `revoked`.
  - `attemptCount` (integer, required, min 0). Number of attempts.
  - `maxAttempts` (integer, required, range 1–20). Specifies max attempts for this management customer pairing link.
  - `pendingSessionId` (string (uuid), required, nullable, format uuid). Identifier for the pending session.
  - `createdBy` (string, required, nullable). Specifies created by for this management customer pairing link.
  - `reservedAt` (integer, required, nullable, format int64). Timestamp for reserved at.
  - `openedAt` (integer, required, nullable, format int64). Timestamp for opened at.
  - `connectingAt` (integer, required, nullable, format int64). Timestamp for connecting at.
  - `connectedAt` (integer, required, nullable, format int64). Timestamp for connected at.
  - `failedAt` (integer, required, nullable, format int64). Timestamp for failed at.
  - `expiredAt` (integer, required, nullable, format int64). Timestamp for expired at.
  - `revokedAt` (integer, required, nullable, format int64). Timestamp for revoked at.
  - `lastErrorCode` (string, required, nullable). Machine-readable last error code for this management customer pairing link.
  - `failedExchangeCount` (integer, required, range 0–5). Number of failed exchanges.
  - `phoneMismatchCount` (integer, required, range 0–3). Number of phone mismatches.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "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
    }
  ]
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

## Get customers status

`GET https://api.polymorfa.com/platform/projects/{projectId}/customers/status` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/projects/<projectId>/customers/status" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `enabledAt` (integer, required, nullable, format int64). Timestamp for enabled at.
  - `enabledBy` (string, required, nullable). Specifies enabled by for this management customers status.
  - `defaultCustomer` (object, required, nullable). Structured default customer values for this management customers status.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `teamId` (string (uuid), required, format uuid). Identifier for the team.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
    - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
    - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
    - `isDefault` (boolean, required). Whether default.
    - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
    - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
    - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "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
    }
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

## Get customer

`GET https://api.polymorfa.com/platform/customers/{customerId}` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Query parameters

- `projectId` (string, required). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/customers/<customerId>?projectId=<projectId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
  - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
  - `isDefault` (boolean, required). Whether default.
  - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

## Update customer

`PATCH https://api.polymorfa.com/platform/customers/{customerId}` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `name` (string, nullable, length 1–120). Human-readable name for this resource.
- `externalCustomerId` (string, nullable, length 1–200). Identifier for the external customer.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/customers/<customerId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "externalCustomerId": "string"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
  - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
  - `isDefault` (boolean, required). Whether default.
  - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

## Enable customers

`POST https://api.polymorfa.com/platform/projects/{projectId}/customers/enable` (Platform API)

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

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/projects/<projectId>/customers/enable" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Idempotency-Key: <idempotency_key>"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `enabled` (boolean, required). Whether this feature is enabled.
  - `enabledAt` (integer, required, nullable, format int64). Timestamp for enabled at.
  - `enabledBy` (string, required, nullable). Specifies enabled by for this management customers enablement.
  - `defaultCustomer` (object, required, nullable). Structured default customer values for this management customers enablement.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `teamId` (string (uuid), required, format uuid). Identifier for the team.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
    - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
    - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
    - `isDefault` (boolean, required). Whether default.
    - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
    - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
    - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.
  - `migratedNumberCount` (integer, required, min 0). Number of migrated numbers.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

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

## Archive customer

`POST https://api.polymorfa.com/platform/customers/{customerId}/archive` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/archive" \
  -H "Authorization: Bearer <POLYMORFA_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"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
  - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
  - `isDefault` (boolean, required). Whether default.
  - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

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

## Restore customer

`POST https://api.polymorfa.com/platform/customers/{customerId}/restore` (Platform API)

Required permission: `customers:manage`

Restores an archived Customer.

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

### Path parameters

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/restore" \
  -H "Authorization: Bearer <POLYMORFA_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"
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required, nullable, max length 120). Human-readable name for this resource.
  - `externalCustomerId` (string, required, nullable, max length 200). Identifier for the external customer.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `archiving`, `archived`.
  - `isDefault` (boolean, required). Whether default.
  - `archivedAt` (integer, required, nullable, format int64). Timestamp for archived at.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

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

## Transfer customer number

`POST https://api.polymorfa.com/platform/customers/{customerId}/numbers/{sessionId}/transfer` (Platform API)

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

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.
- `sessionId` (string, required, length 1–64). Database session UUID or stable session slug.

### Header parameters

- `Idempotency-Key` (string, required, length 1–255). Specifies idempotency key for this header parameter.

### Body

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `sourceCustomerId` (string (uuid), required, format uuid). Identifier for the source customer.
- `confirm` (boolean, required). Whether confirm. Values: `true`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/customers/<customerId>/numbers/<sessionId>/transfer" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `customerId` (string (uuid), required, format uuid). Identifier for the customer.
  - `sessionId` (string, required). Identifier of the connected Polymorfa session.
  - `name` (string, required, nullable). Human-readable name for this resource.
  - `phoneMasked` (string, required, nullable). Specifies phone masked for this management customer number.
  - `status` (string, required). Current status of this resource or operation.
  - `backend` (string, required, nullable). Specifies backend for this management customer number.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "customerId": "00000000-0000-4000-8000-000000000000",
    "sessionId": "string",
    "name": "string",
    "phoneMasked": "string",
    "status": "string",
    "backend": "string",
    "createdAt": 0
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`).
Same fields as 400.

Headers:

- `Link` (string). Documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

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

## Revoke customer pairing link

`DELETE https://api.polymorfa.com/platform/customers/{customerId}/pairing-links/{pairingLinkId}` (Platform API)

Required permission: `customers:manage`

Revokes an open pairing link.

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

### Path parameters

- `customerId` (string (uuid), required, format uuid). Identifier for the customer.
- `pairingLinkId` (string, required). Identifier for the pairing link.

### Query parameters

- `projectId` (string, required). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/customers/<customerId>/pairing-links/<pairingLinkId>?projectId=<projectId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `teamId` (string (uuid), required, format uuid). Identifier for the team.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `customerId` (string (uuid), required, format uuid). Identifier for the customer.
  - `expectedPhoneMasked` (string, required, nullable). Specifies expected phone masked for this management customer pairing link.
  - `methods` (array of string, required, items 1–2, unique items). Connection methods enabled for the widget. Values: `qr`, `phone`.
  - `locale` (string, required, nullable). Specifies locale for this management customer pairing link. Values: `en`, `pt-BR`.
  - `theme` (string, required, nullable). Visual theme used by the widget. Values: `light`, `dark`, `system`.
  - `expiresAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource expires.
  - `status` (string, required). Current status of this resource or operation. Values: `active`, `opened`, `connecting`, `connected`, `failed`, `expired`, `revoked`.
  - `attemptCount` (integer, required, min 0). Number of attempts.
  - `maxAttempts` (integer, required, range 1–20). Specifies max attempts for this management customer pairing link.
  - `pendingSessionId` (string (uuid), required, nullable, format uuid). Identifier for the pending session.
  - `createdBy` (string, required, nullable). Specifies created by for this management customer pairing link.
  - `reservedAt` (integer, required, nullable, format int64). Timestamp for reserved at.
  - `openedAt` (integer, required, nullable, format int64). Timestamp for opened at.
  - `connectingAt` (integer, required, nullable, format int64). Timestamp for connecting at.
  - `connectedAt` (integer, required, nullable, format int64). Timestamp for connected at.
  - `failedAt` (integer, required, nullable, format int64). Timestamp for failed at.
  - `expiredAt` (integer, required, nullable, format int64). Timestamp for expired at.
  - `revokedAt` (integer, required, nullable, format int64). Timestamp for revoked at.
  - `lastErrorCode` (string, required, nullable). Machine-readable last error code for this management customer pairing link.
  - `failedExchangeCount` (integer, required, range 0–5). Number of failed exchanges.
  - `phoneMismatchCount` (integer, required, range 0–3). Number of phone mismatches.
  - `createdAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was created.
  - `updatedAt` (integer, required, format int64). Unix timestamp in milliseconds when this resource was last updated.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

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

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

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

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

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

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

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

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

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

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

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

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```
