Request a pairing code (link with phone number)

Issues a WhatsApp **pairing code** for a connection that is waiting to be paired — the alternative to scanning the QR. The customer opens WhatsApp → Settings → Linked devices → **Link with phone number** and types the 8-character code you return. **Why you want it:** a QR needs two devices — a screen showing the code and a phone photographing it. A large share of real onboardings happen on ONE device: the customer completes your flow on the same phone that runs WhatsApp, and cannot photograph its own screen. For those customers the QR path is not inconvenient, it is impossible. **A pairing code is NOT always available.** The engine can decline to issue one, and that is an ordinary outcome rather than an outage — it answers **502 `pairing_code_unavailable`**. **Your application must keep the QR flow on screen as a fallback.** An integration that offers only the pairing code will strand customers with no way to connect at all. **Re-requestable.** Calling this again on the same connection returns a NEW code and does not rebuild the session, so a "send me another code" button is safe. It is capped: **5 requests per connection per 15 minutes**, then **429 `rate_limited`** with `Retry-After`. The cap is not bureaucracy — repeatedly requesting codes for one number is exactly the pattern WhatsApp's anti-abuse systems act on, and the number at risk is your customer's. **Nothing extra is consumed.** This does not provision anything: the connection, its paid slot and its 7-day trial behave exactly as with QR pairing. The licence is claimed when the number actually pairs, whichever way it paired. **Status monitoring is unchanged.** Poll `GET /connections/{id}` until `status` is `"connected"`, and/or listen for the `connection.connected` webhook. There is no separate "code accepted" event. QR/WAPP connections only (`provider: qr`). Meta/WABA numbers (`provider: cloud_api`) are onboarded through Meta embedded signup and answer 409 `not_supported_for_provider`.

curl -X POST "https://example.com/connections/string/pairing-code" \  -H "Content-Type: application/json" \  -d '{    "phoneNumber": "40740267964"  }'

{  "code": "7S59-1KZP"}