> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Group Numbers by the people and businesses they belong to.

Customers gives every Number in a project an explicit owner. Use it when you
manage WhatsApp connections for multiple people, stores, teams, or client
accounts from one Polymorfa project.

## Enable Customers

Open **Customers** in the Console and select **Enable Customers**. Any signed-in
project member can enable and manage Customers.

Enablement makes two changes together:

* Polymorfa creates one protected **Default customer** for the project.
* Every Number already in that project is assigned to the Default customer.

Existing Numbers stay connected. The Default customer cannot be archived.
After enablement, a new Number belongs to the customer selected in the **New
number** flow. If no customer is selected through the API, Polymorfa assigns the
Default customer.

<Warning>
  Customers cannot be disabled after enablement. Confirm that the selected
  project is correct before continuing.
</Warning>

## Add a customer

1. Open **Customers** for the project.
2. Select **Add customer**.
3. Add a name or external ID, or leave both empty.
4. Select **Create customer**.

An unnamed record appears as **Unnamed customer**. An external ID must be unique
within the project. Customers do not have a phone number field. Phone numbers
belong to connected Numbers; an expected phone can be set on each pairing link.

Open a customer to see its Numbers and pairing links. Archiving removes a
non-default customer from active selection without deleting its record. Restore
an archived customer before creating another pairing link for it.

## Connect a Number for a customer

Use either workflow:

* Open **Numbers**, select **New number**, and choose the Customer before
  pairing in Console, sending a QuickLink, or creating a testing Number.
* Open the Customer and generate a private pairing link for the person who has
  the phone.

The **Customer** column and filter on **Numbers** are separate from **Owned by**.
Customer identifies the person or business the Number belongs to. Owned by
identifies the Console or Inspector user controlling it.

See [Customer pairing links](/guides/customers/pairing-links) for recipient
handoff, expiry, and recovery.

## API access

Use `customers:read` to read Customer status, records, Numbers, and pairing-link
status. Use `customers:manage` to enable Customers, change Customer records, or
create and revoke pairing links.

The Platform API keeps every request inside its authenticated project. A
Customer identifier from another project returns `404`.

See [Platform API](/api/platform-api#customers) for paths, request fields, and
credential behavior.

## TypeScript SDK and CLI

The TypeScript server SDK exposes the complete Customer workflow through
`PlatformClient.customers`. Customer creation and pairing-link creation require
an idempotency key. The create-link response returns the raw URL once; an
idempotent replay returns the record with `url: null`.

```ts theme={null}
const customer = await platform.customers.create(
  { projectId, name: "Ada", externalCustomerId: "crm_123" },
  { idempotencyKey: crypto.randomUUID() },
);

const pairing = await platform.customers.createPairingLink(
  customer.data.data.id,
  { projectId, methods: ["qr", "phone"] },
  { idempotencyKey: crypto.randomUUID() },
);
```

The CLI exposes the same operations under `polymorfa customer`. Supply an
team server key and the project ID.

```bash theme={null}
polymorfa customer list --project project_123
polymorfa customer pairing-link list customer_123 --project project_123
polymorfa customer event list customer_123 --project project_123
```

See [SDK availability](/sdks/typescript/installation) for development installation
status and a complete example.