---
title: "Edit or resubmit a caller identity"
method: PATCH
path: "/v1/branded-calling/identities/{id}"
tags: ["Branded Calling"]
---

# Edit or resubmit a caller identity

`PATCH /v1/branded-calling/identities/{id}`

Allowed while the identity is `requested`, `changes_requested` or `rejected`.
Answering a change request (send `reviewAnswers` keyed by point id, and any
edited fields) puts it back in review. On a carrier rejection the edits are
applied at the carrier and the identity is resubmitted straight away.

## Path parameters

- `id` string, required

## Request body

- object
  - `displayName` string — Shown on the callee's screen. No emoji.
  - `callReasons` string[] — 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
    - `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
    - `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.
  - `reviewAnswers` object — One entry per point id of the open reviewRequest. A text point takes text; a link point takes url; file and link_or_file points take url set to the URL of a file you uploaded first (POST /v1/media/upload). A point id that is not on the open request is a 422.
  - `reviewNote` string

## Response `200`

The updated identity.

- 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
- `404` — Identity not found
- `409` — The identity cannot be edited in its current status (code invalid_resource_state).
- `422` — reviewAnswers names a point id that is not on the open change request, or there is no open request (code invalid_field_value, param reviewAnswers).

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