---
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`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/connect/whatsapp/select-phone-number`
- Auth: HTTP bearer

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`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `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 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-10-06** `f8c8f34fb41a`: 4 warning
  - added the new `account` enum value to the `details/budgetScope` response property for the response status `400`
  - added the new `account` enum value to the `details/budgetScope` response property for the response status `401`
  - added the new `account` enum value to the `details/budgetScope` response property for the response status `404`
  - added the new `account` enum value to the `details/budgetScope` response property for the response status `500`
- **2026-10-02** `d556591af3f6`: 10 info
  - added the optional property `code` to the response with the `401` status
  - added the optional property `details` to the response with the `401` status
  - added the optional property `docUrl` to the response with the `400` status
  - added the optional property `docUrl` to the response with the `401` status
  - …6 more
- **2026-09-30** `16a7b9d5373e`: 3 info
  - removed the `platform` enum value from the `details/budgetScope` response property for the response status `400`
  - removed the `platform` enum value from the `details/budgetScope` response property for the response status `404`
  - removed the `platform` enum value from the `details/budgetScope` response property for the response status `500`
- …earlier changes not shown

[Operation 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/4e74db179e73?raw)