---
title: "Attach numbers to a verified identity"
method: POST
path: "/v1/branded-calling/identities/{id}/numbers"
tags: ["Branded Calling"]
---

# Attach numbers to a verified identity

`POST /v1/branded-calling/identities/{id}/numbers`

Files a Letter of Authorization signed by you (Zernio is named as the authorized
agent managing the numbers) and opens a vetting batch of up to 15 US numbers you
own. The batch is all-or-nothing: one ineligible number refuses the whole call.
Each number shows the identity once its own status reaches `verified`. A number
belongs to one identity at a time.

## Path parameters

- `id` string, required

## Request body

- object
  - `phoneNumberIds` string[], required — Phone number record ids (from GET /v1/phone-numbers). Active US numbers only.
  - `signature` object, required
    - `imageBase64` string, required — The signer's drawn signature as a PNG, base64 (a data:image/png;base64 prefix is accepted).
    - `signerName` string — Printed under the signature. Defaults to the business contact's name.

## Response `201`

Batch opened.

- object
  - `numbers` BrandedCallingIdentityNumber[]
    - `phoneNumberId` string
    - `phoneNumber` string
    - `status` 'submitted' | 'in_review' | 'verified' | 'unsuccessful' | 'suspended' | 'expired' | 'permanently_rejected' — verified = the identity shows on calls from this number. permanently_rejected cannot be attached again anywhere.
    - `rejectionReason` object, nullable
      - `code` string
      - `title` string
      - `detail` string
      - `message` string, nullable
    - `verifiedAt` string, date-time, nullable
    - `addedAt` string, date-time, nullable

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `404` — Identity or phone number not found
- `409` — The identity is not verified yet, or a number already belongs to an identity (code invalid_resource_state).
- `422` — A number is not a US number or not active, or the carrier refused the batch (the message names the number).

## Changes

- **2026-09-30** `16a7b9d5373e` — 1 info
  - removed the `platform` enum value from the `details/budgetScope` response property for the response status `400`
- **2026-09-29** `698a0d89ab62` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/branded-calling/identities/:id/numbers/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/f92af0e169c1?raw)