---
title: "Complete number selection"
method: POST
path: "/v1/connect/whatsapp/select-phone-number"
tags: ["Connect"]
---

# Complete number selection

`POST /v1/connect/whatsapp/select-phone-number`

Bind a specific WhatsApp phone number to the Zernio profile after the user picks one from `listWhatsAppPhoneNumbers`. Exchanges the short-lived OAuth token for a long-lived token, subscribes the WABA to webhooks, and creates the SocialAccount.

## Headers

- `X-Connect-Token` string

## Request body

- object
  - `profileId` string, required — The Zernio profile ID
  - `phoneNumberId` string, required — The selected phone number ID (from listWhatsAppPhoneNumbers)
  - `wabaId` string, required — The WABA ID containing the selected phone
  - `tempToken` string, required — The temporary access token from the headless redirect
  - `userProfile` object — Optional user profile data (passthrough)
  - `redirect_url` string — Optional URL to receive the post-connection redirect target

## Response `200`

Phone number connected successfully

- object
  - `message` string
  - `redirect_url` string — Present only if redirect_url was provided in the request
  - `account` object
    - `accountId` string
    - `platform` 'whatsapp'
    - `username` string — Display phone number
    - `displayName` string — Meta-verified business name
    - `isActive` boolean
    - `selectedPhoneNumber` string

## Other responses

- `400` — Missing required fields (profileId, phoneNumberId, wabaId, or tempToken)
- `401` — Unauthorized
- `403` — Profile limit exceeded for the user's plan (PROFILE_LIMIT_EXCEEDED)
- `404` — Selected phone number not found in the specified WABA
- `409` — Conflict with an existing connection. One of: the target profile already has a WhatsApp number connected (code ONE_WHATSAPP_PER_PROFILE, each profile holds exactly one WhatsApp number, so connect this number to a different or new profile); the phone number is a Zernio-provisioned number pinned to a different profile (code WHATSAPP_NUMBER_PINNED_TO_PROFILE, connect it from that profile or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile); or the number is already actively connected on another profile or team (code WHATSAPP_NUMBER_ALREADY_CONNECTED, disconnect it there first). A number can only be live on one profile. Or, for a number connected from the WhatsApp Business app (coexistence), the phone never registered the number on the Cloud API, so Meta reported it as platform_type ON_PREMISE and refused the contacts/history sync with error 133010 (code WHATSAPP_COEXISTENCE_NOT_REGISTERED). No account is created in that case: the customer opens WhatsApp Business on the phone, keeps it open and updated, and runs the same Embedded Signup again, which succeeds on the second attempt in practice.
- `500` — Failed to bind phone number

## Changes

- **2026-09-16** `3e6ddf2a99ea` — 3 info
  - added the optional property `details/budgetScope` to the response with the `400` status
  - added the optional property `details/budgetScope` to the response with the `404` status
  - added the optional property `details/budgetScope` to the response with the `500` status
- **2026-09-15** `0dba7d004d75` — 6 info
  - added the optional property `details/quotaExhausted` to the response with the `400` status
  - added the optional property `details/quotaExhausted` to the response with the `404` status
  - added the optional property `details/quotaExhausted` to the response with the `500` status
  - added the optional property `details/quotaScope` to the response with the `400` status
  - …2 more
- **2026-08-07** `51932b099b2f` — 1 info
  - added the non-success response with the status `409`

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/connect/whatsapp/select-phone-number/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/a0d8f21b5abe?raw)