# Build your own pairing interface

> Request QR codes and pairing codes from your backend and show them in your own interface.

Direct pairing returns the raw QR code or pairing code for a Linked Devices
Number, so you can show it in your own interface instead of the hosted
QuickLink page.

> **Note**
>
> Direct pairing requires access for the team that owns the Number. Without it,
> both methods return `403` and the error points to QuickLink. Use
> [QuickLink](https://docs.polymorfa.com/numbers/quicklink) for standard connections, including when you
> connect a phone from the Console.

## Before you begin

- The team that owns the Number has direct-pairing access.
- The Number exists in your project and connects through Linked Devices. New
  Numbers are created through QuickLink; direct creation is retired and returns
  `410` `resource_gone`.
- Your server holds a credential with `sessions:manage`.
- The Number is funded. Polymorfa checks funding when pairing starts; see
  [Fund linked-device pairing](https://docs.polymorfa.com/numbers/quicklink#fund-linked-device-pairing).

Keep the credential on your server. Pass only the QR value or pairing code to
the browser or app that shows it.

## Pair with a QR code

### Request the QR code

Call [Get QR code](https://docs.polymorfa.com/api/pairing/get-qr-code):

```bash
curl "https://api.polymorfa.com/messaging/$SESSION/pair/qr" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

The JSON response holds the value to encode in `data.qr`. Add
`?format=image` to receive a PNG instead.

### Show the code

Render the value as a QR code. On the phone, the person opens WhatsApp,
selects **Linked devices**, then **Link a device**, and scans it.

### Refresh until it links

WhatsApp rotates QR codes. Request a new code when the current one expires,
and stop when the Number reports `session.connected`.

## Pair with a phone number

### Request a pairing code

Call [Request a pairing code](https://docs.polymorfa.com/api/pairing/request-pair-code) with
the phone number in international format:

```bash
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/pair/code" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+15550001111" }'
```

The response holds the code in `data.code`.

### Enter the code on the phone

In WhatsApp, the person opens **Linked devices**, selects **Link a device**,
then **Link with phone number instead**, and enters the code.

## Verify the connection

Subscribe to `session.connected` on a [webhook](https://docs.polymorfa.com/development/webhooks), or
read the Number with [Get session](https://docs.polymorfa.com/api/numbers/get-session) until
its `status` is `CONNECTED`. Then send a test message.

## See also

- [Connect a number with QuickLink](https://docs.polymorfa.com/numbers/quicklink)
- [Start, stop and restart Numbers](https://docs.polymorfa.com/numbers/manage)
- [Pairing API reference](https://docs.polymorfa.com/api/pairing/get-qr-code)
