---
title: "Create a caller identity"
method: POST
path: "/v1/branded-calling/identities"
tags: ["Branded Calling"]
---

# Create a caller identity

`POST /v1/branded-calling/identities`

A caller identity is what the callee sees: display name, logo and call reasons,
backed by a registered business and three references the carrier vetting team
phones. It starts in Zernio review (`requested`). Once approved, the carrier emails
the authorizer a 6-digit code; confirm it with the verify-email endpoint and the
identity goes into carrier vetting on its own. Track it with `GET` or the
`branded_calling.identity.status_updated` webhook.

Billing: $100 per identity per month, the first month charged when the
identity is filed with the carrier and not refunded if the carrier rejects it,
then monthly while the identity exists. Branded calls add $0.10 each, counted
on every outbound call from a verified branded number to a US destination
(whether or not the callee's carrier displayed the branding); the surcharge
shows as `brandedCallUSD` on the call's billing and in
`GET /v1/voice/calls/estimate` when you pass `from`.

Run `POST /v1/branded-calling/identities/preflight` with the same body first to
catch what the review would bounce. Send an `Idempotency-Key` so a retry replays
the original response instead of creating a second identity.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `enterpriseId` string, required — A business from POST /v1/branded-calling/enterprises.
  - `displayName` string, required — Shown on the callee's screen. No emoji.
  - `callReasons` string[], required — 1 to 10 reasons you call, each up to 64 characters. Pick from GET /v1/branded-calling/call-reasons to skip manual vetting.
  - `logoUrl` string — HTTPS URL of a PNG, JPEG, WebP or SVG logo. Zernio converts it to the 256x256 BMP the carriers require and hosts it.
  - `authorizer` object, required
    - `name` string, required — A real person at the business who authorizes the registration.
    - `email` string, email, required — The carrier emails a 6-digit code here once the identity passes review.
  - `references` BrandedCallingReferences, required
    - `business` BrandedCallingReference[], required
      - `fullName` string, required
      - `jobTitle` string
      - `organization` string
      - `relationshipToRegistrant` string
      - `phoneNumber` string, required — E.164 with a leading +.
      - `email` string, email, required
      - `timezone` string, required — IANA timezone id, e.g. America/New_York.
    - `financial` BrandedCallingReference, required — A person the carrier vetting team phones to confirm the business. Business references are senior contacts at a vendor, partner or client; the financial reference is a CPA or a bank contact. Calls are placed in the reference's local 8am-9pm window.
      - `fullName` string, required
      - `jobTitle` string
      - `organization` string
      - `relationshipToRegistrant` string
      - `phoneNumber` string, required — E.164 with a leading +.
      - `email` string, email, required
      - `timezone` string, required — IANA timezone id, e.g. America/New_York.

## Response `201`

Identity created, in review.

- BrandedCallingIdentity
  - `id` string
  - `enterpriseId` string
  - `displayName` string
  - `callReasons` string[]
  - `callReasonsPreApproved` boolean — Every call reason matches the carrier catalogue (GET /v1/branded-calling/call-reasons); anything else is vetted by hand and takes longer.
  - `logoUrl` string, nullable — The image you sent. Zernio hosts the 256x256 BMP the carriers require.
  - `authorizer` object
    - `name` string
    - `email` string, email
  - `references` BrandedCallingReferences
    - `business` BrandedCallingReference[], required
      - `fullName` string, required
      - `jobTitle` string
      - `organization` string
      - `relationshipToRegistrant` string
      - `phoneNumber` string, required — E.164 with a leading +.
      - `email` string, email, required
      - `timezone` string, required — IANA timezone id, e.g. America/New_York.
    - `financial` BrandedCallingReference, required — A person the carrier vetting team phones to confirm the business. Business references are senior contacts at a vendor, partner or client; the financial reference is a CPA or a bank contact. Calls are placed in the reference's local 8am-9pm window.
      - `fullName` string, required
      - `jobTitle` string
      - `organization` string
      - `relationshipToRegistrant` string
      - `phoneNumber` string, required — E.164 with a leading +.
      - `email` string, email, required
      - `timezone` string, required — IANA timezone id, e.g. America/New_York.
  - `status` 'requested' | 'changes_requested' | 'rejected' | 'pending_email_verification' | 'in_review' | 'verified' | 'suspended' | 'expired' | 'permanently_rejected' — requested = in Zernio review; changes_requested = answer the review (PATCH); pending_email_verification = confirm the code emailed to the authorizer; in_review = with the carrier vetting team; verified = attach numbers; rejected = fix and PATCH to resubmit; suspended = an infringement claim is open; expired = the yearly verification lapsed; permanently_rejected = terminal.
  - `rejectionReasons` object[]
    - `code` string
    - `title` string
    - `detail` string
    - `message` string, nullable — Free-text note from the vetting team, on the first entry only.
  - `reviewNote` string, nullable — The open change request, as text.
  - `reviewRequest` object, nullable — The open change request as points; answer each by id in reviewAnswers on PATCH.
    - `id` string
    - `intro` string
    - `points` object[]
      - `id` string
      - `title` string
      - `detail` string
      - `answer` 'text' | 'link' | 'file' | 'link_or_file'
  - `emailVerifiedAt` string, date-time, nullable
  - `submittedAt` string, date-time, nullable
  - `verifiedAt` string, date-time, nullable
  - `expiringAt` string, date-time, nullable — Verification lasts one year; Zernio resubmits 30 days before this date.
  - `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
  - `createdAt` string, date-time, nullable
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Usage-based billing is required (code usage_billing_required).
- `404` — Business not found
- `409` — Same Idempotency-Key still processing; retry after a short backoff
- `422` — The logo could not be downloaded or is not an image, or the Idempotency-Key was reused with a different body (code idempotency_key_reused).

## 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/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)