Request a phone pairing code
Requests a pairing code to attach a number **without scanning a QR** — the alternative to the QR endpoint. Requires the `manage` capability. **Input.** Pass the target `phone` (international format, digits only, no leading + — e.g. `628123456789`) in the request body. **Output.** The response returns a short code such as `ABCD-1234` to enter in WhatsApp on that phone under Settings → Linked devices → Link a device → Link with phone number instead. **Precondition.** The session must be unpaired; requesting a code for an already-paired session returns an error. The code is short-lived — request a fresh one if it expires before use. **Errors.** `validation_error` (400) — missing or malformed `phone`, or the session is already paired. `not_found` (404) — no such session in your organization. `unauthorized` (401) / `forbidden` (403) — credential / capability failures.
Send Authorization: Bearer <token>. The router accepts two kinds of token and tries each in turn: a frontend-minted login JWT (verified against the frontend JWKS; the person's org + role are read from it), or an api-key for a script/service (carrying a fixed set of gateway permissions). The bearerFormat: JWT label describes the person-login case.
In: header
Path Parameters
The session id to pair. Must be an existing, not-yet-paired session in your organization; a session in another organization is reported as not_found (404).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The phone number to pair, in international format with country code and no leading + or spaces (E.164 digits only). This is the WhatsApp number the code will be entered on under "Link a device".
Response Body
application/json
application/json
curl -X POST "https://example.com/api/v1/sessions/sess_01HZX8K3M9/pairing-code" \ -H "Content-Type: application/json" \ -d '{}'{ "code": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Get the connected account's own identity GET
Returns the WhatsApp identity of the number attached to this session — its JID, linked-device id, push name, and phone number. Requires the `manage` capability. **Precondition.** The session must be paired; if no number is attached yet, this returns `not_found` (404). On builds where this is not yet wired, it may return `not_implemented` (501). **Errors.** `not_found` (404) — session unknown or not yet paired. `not_implemented` (501) — the feature is stubbed in this build. `unauthorized` (401) / `forbidden` (403) — credential / capability failures.
Get the current pairing QR code GET
Returns the QR code to scan from WhatsApp on the phone (Settings → Linked devices → Link a device) to attach a number to this session. Requires the `manage` capability. **Behavior.** Returns the raw QR code string in the JSON body. **Side effect.** If no code is ready yet, this endpoint *starts pairing* and returns `not_found` (404) until a code exists. QR codes are short-lived and refresh periodically; they also stream live over the event stream as `auth.qr` events, so the recommended pattern is to subscribe there and follow the codes as they rotate rather than polling. **Precondition.** The session must be unpaired — requesting a QR for an already-paired session returns an error. **Errors.** `not_found` (404) — no code ready yet (pairing was started) or session unknown. `unauthorized` (401) / `forbidden` (403) — credential / capability failures.