pozyDocs
Dashboard

Phone, SMS & voice

Branded calling

Not available yet. Show your business name, logo and reason for calling on the callee's phone when you call from US numbers. Register the business, pass vetting, attach numbers.

Not available yet

Branded calling is not available yet: creating a caller identity answers 403 with code: "feature_not_available". Registering your business still works. The rest of this page describes branded calling as it will work.

With branded calling, the person you call sees your business name, logo and reason for calling instead of a plain number or a "Spam Likely" warning. It applies to calls from US numbers to US mobile phones. Attach a number to a verified caller identity and all its calls carry the brand; you dial exactly as before.

#Where it shows

The carriers verify that you are eligible. They do not promise the display on every phone.

Shows Does not show
Calls from US numbers to US mobiles on T-Mobile and Verizon Landlines and international destinations
Samsung, Motorola and TCL phones on Android 14 or later Most unlocked, bring-your-own and prepaid-brand phones (may show less or nothing)
iPhone XS or newer on iOS 18.5 or later Other carriers

Outbound calls placed through the API, the browser or a SIP trunk are all branded, because the identity belongs to the number.

#What it costs

Item Price
Caller identity $100 a month for as long as it is verified. You pay the first month only once the carrier verifies it, and nothing while it is in review or vetting, or if it is turned down.
Branded call $0.10 for each outbound call from an attached number to a US number, added to the per-minute rate. Carriers do not say which calls showed the brand, so all of those calls are counted.
Registering the business, attaching numbers Free

Deleting the identity ends the monthly fee. The month in progress is not prorated.

#Before you start

  • A voice-enabled US number.
  • A payment method on file. Without one, creating an identity returns 403 usage_billing_required.
  • A business registered in the US or Canada, with a federal tax id.

Vetting involves people: the carrier phones three references you name. Expect days, not minutes.

#Register the business

POST /v1/branded-calling/enterprises with the legal entity. Nothing is filed with the carrier yet. The tax id is stored encrypted, and only its last four digits are ever returned (feinLast4). One business can have any number of identities.

curl -X POST https://api.pozy.ai/v1/branded-calling/enterprises \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Acme Plumbing LLC",
    "doingBusinessAs": "Acme Plumbing",
    "organizationType": "commercial",
    "organizationLegalType": "llc",
    "countryCode": "US",
    "jurisdictionOfIncorporation": "Illinois",
    "website": "https://acmeplumbing.example",
    "fein": "12-3456789",
    "industry": "home services",
    "numberOfEmployees": "11-50",
    "organizationContact": { "firstName": "Sam", "lastName": "Rivera", "email": "sam@acmeplumbing.example", "jobTitle": "Owner", "phoneNumber": "+13125550100" },
    "billingContact": { "firstName": "Pat", "lastName": "Lee", "email": "billing@acmeplumbing.example", "phoneNumber": "+13125550101" },
    "physicalAddress": { "streetAddress": "100 N State St", "city": "Chicago", "administrativeArea": "IL", "postalCode": "60602", "country": "US" },
    "billingAddress": { "streetAddress": "100 N State St", "city": "Chicago", "administrativeArea": "IL", "postalCode": "60602", "country": "US" }
  }'

If you already registered the same business for 10DLC, copy the legal name, tax id, address and contacts from that registration instead of asking again.

#Create the caller identity

POST /v1/branded-calling/identities describes what the callee sees and what the carrier vets. Send an Idempotency-Key so a retry does not create a second identity.

Request body
{
  "enterpriseId": "66f1a2b3c4d5e6f7a8b9c0d1",
  "displayName": "Acme Plumbing",
  "callReasons": ["Appointment Reminder", "Customer Service"],
  "logoUrl": "https://acmeplumbing.example/logo.png",
  "authorizer": { "name": "Sam Rivera", "email": "sam@acmeplumbing.example" },
  "references": {
    "business": [
      { "fullName": "Dana Reyes", "jobTitle": "Operations Manager", "organization": "Reyes Supply", "relationshipToRegistrant": "Supplier", "phoneNumber": "+14155550123", "email": "dana@reyessupply.example", "timezone": "America/Chicago" },
      { "fullName": "Lee Park", "jobTitle": "Owner", "organization": "Park Realty", "relationshipToRegistrant": "Client", "phoneNumber": "+14155550124", "email": "lee@parkrealty.example", "timezone": "America/New_York" }
    ],
    "financial": { "fullName": "Morgan Cole", "jobTitle": "CPA", "organization": "Cole Accounting", "phoneNumber": "+14155550125", "email": "morgan@coleaccounting.example", "timezone": "America/Chicago" }
  }
}
Field Rules
displayName Between 1 and 35 characters, without emoji: the name people know the business by. Using some other brand's name is refused as impersonation.
callReasons 1 to 10 reasons, up to 64 characters each. Reasons from GET /v1/branded-calling/call-reasons pass automatically. Other wording is vetted by hand and takes longer.
logoUrl HTTPS PNG, JPEG, WebP or SVG. Use the mark on the business's own website. Pozy converts and hosts it in the format carriers need.
authorizer A real person at the business. The carrier emails them a 6-digit code after review. Avoid free-mail addresses.
references Two business references (senior contacts at a supplier, partner or client) and one financial reference (the company's accountant or bank contact). The vetting team phones each one during their local business hours, so give direct numbers, monitored inboxes and the right IANA timezone.

#Preflight the body

POST /v1/branded-calling/identities/preflight applies the review's checks without creating anything, and returns ok with a list of findings. A block finding means review would fail; a warn finding means vetting will take longer. Codes include display_name_differs_from_legal_name, call_reason_not_in_catalogue, duplicate_reference_phone, reference_inside_business, invalid_timezone, free_mail_authorizer and logo_unreachable.

#Pass review and confirm the code

The identity starts in requested while Pozy reviews it. When it passes, it is filed with the carrier and moves to pending_email_verification. The authorizer receives a 6-digit code, and branded_calling.identity.action_required fires with reason: "email_code". Confirm it:

Confirm the authorizer's code
curl -X POST https://api.pozy.ai/v1/branded-calling/identities/66f1a2b3c4d5e6f7a8b9c0d2/verify-email/confirm \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482915" }'

Now the identity is in_review, and the carrier's vetting team will call your references, so warn them first. If the email code ran out before it was used, POST /v1/branded-calling/identities/{id}/verify-email sends another.

#Attach numbers

Once the identity is verified, attach up to 15 active US numbers per call. Attaching files a letter of authorization with the carrier, so you include a signature image and the signer's name. Send an Idempotency-Key here too.

Attach numbers
curl -X POST https://api.pozy.ai/v1/branded-calling/identities/66f1a2b3c4d5e6f7a8b9c0d2/numbers \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: brand-attach-2026-10-30" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberIds": ["6650d2e1b3c4d5e6f7081923"],
    "signature": { "imageBase64": "data:image/png;base64,iVBORw0KGgo...", "signerName": "Sam Rivera" }
  }'

Numbers are attached together or not at all: if any one is not eligible, the request fails with 422. Every number begins as submitted and displays the identity when it becomes verified.

#Identity statuses

Status Meaning What to do
requested In Pozy review Wait. Review usually finishes the same day.
changes_requested Review needs something from you Answer the points (below)
rejected Declined by review or by the carrier Fix and resubmit
pending_email_verification Filed. Waiting for the authorizer's code. Confirm the code
in_review With the carrier's vetting team Wait. Warn the references.
verified Live Attach numbers
suspended Someone filed a trademark or impersonation claim Wait for the claim to close. Until then branding is off and the identity cannot be deleted.
expired The yearly renewal failed Edit and resubmit
permanently_rejected Final Create a new identity

Number statuses are submitted, in_review, verified, unsuccessful, suspended, expired and permanently_rejected.

Important

Once the carrier sets a number to permanently_rejected, your workspace can never brand it again, so check the display name and references carefully before filing.

#Answer a change request

When an identity is changes_requested, reviewRequest.points lists what to fix, one point each. A point has an id, a title, a detail and the answer type it expects: text, link, file or link_or_file. Reply to all points in a single PATCH /v1/branded-calling/identities/{id}, putting the replies in reviewAnswers under each point's id along with any fields you edited. Points left unanswered come back.

PATCH body
{
  "logoUrl": "https://acmeplumbing.example/logo-official.png",
  "reviewAnswers": {
    "p1": { "text": "Changed to morgan@coleaccounting.example, the firm address." },
    "p2": { "url": "https://acmeplumbing.example/logo-official.png" }
  }
}

#Fix a rejection

  • Rejected in Pozy review (before filing): reviewNote explains why and rejectionReasons is empty. Impersonation, prohibited content and businesses that cannot be verified stop here. Fix the fields and PATCH.
  • Rejected by the carrier: rejectionReasons lists each reason with a code, title, detail, and a message from the vetting team on the first entry. PATCH the named fields and the identity goes straight back to in_review.

Rejections and resubmissions cost nothing.

#Renewal

A verified identity lasts one year (expiringAt). Pozy resubmits it 30 days before that date, and the branding stays live during the renewal review. You only see expired if renewal failed.

Changing a verified identity's display name, logo or call reasons returns it to vetting. The monthly fee stops until it is verified once more.

#Let the business fill it in

Not available yet

Hosted identity forms are not available yet: POST /v1/branded-calling/share answers 403 with code: "feature_not_available".

When the business behind the identity is your customer, POST /v1/branded-calling/share returns a single-use link (valid 7 days) where they complete the identity themselves, with no Pozy login. Scope the link with an identityId (to finish or correct one), an enterpriseId (to add a new identity to a registered business), or neither (the business registers itself and its first identity together). What they submit arrives under your workspace as requested and goes through the same review.

#Remove numbers or the identity

  • DELETE /v1/branded-calling/identities/{id}/numbers with phoneNumbers (E.164, up to 100) detaches numbers. They can then join another identity.
  • DELETE /v1/branded-calling/identities/{id} detaches every number, removes the identity at the carrier and stops the monthly fee. It returns 409 while a claim is open.

#Errors

Status Code Cause Fix
422 feature_not_available The business is not in the US or Canada, or one of the numbers is not an active US number Register a US or Canadian business, with active US numbers
409 invalid_resource_state The identity's status does not allow the action (editing outside requested, changes_requested or rejected, attaching before verified, a number already on an identity, deleting during a claim) Check status first
400 The 6-digit code is incorrect or too old Ask for another code
403 usage_billing_required The workspace has no payment method Add one
422 logoUrl could not be downloaded or is not an image Use a reachable HTTPS image

#Endpoints

Endpoint What it does
GET /v1/branded-calling/enterprises List registered businesses
POST /v1/branded-calling/enterprises Register a business for Branded Calling
GET /v1/branded-calling/enterprises/{id} Get a registered business
DELETE /v1/branded-calling/enterprises/{id} Delete a registered business
POST /v1/branded-calling/share Create a caller identity share link (not available yet)
GET /v1/branded-calling/call-reasons List pre-approved call reasons
GET /v1/branded-calling/identities List caller identities
POST /v1/branded-calling/identities Create a caller identity (not available yet)
POST /v1/branded-calling/identities/preflight Dry-run a caller identity before creating it
GET /v1/branded-calling/identities/{id} Get a caller identity
PATCH /v1/branded-calling/identities/{id} Edit or resubmit a caller identity
DELETE /v1/branded-calling/identities/{id} Delete a caller identity
POST /v1/branded-calling/identities/{id}/verify-email Resend the authorizer's code
POST /v1/branded-calling/identities/{id}/verify-email/confirm Confirm the authorizer's code
GET /v1/branded-calling/identities/{id}/numbers List the numbers on a caller identity
POST /v1/branded-calling/identities/{id}/numbers Attach numbers to a verified identity
DELETE /v1/branded-calling/identities/{id}/numbers Detach numbers from an identity

#Webhook events

Event When it fires
branded_calling.identity.status_updated Caller identity status updated.
branded_calling.identity.action_required Caller identity action required.
branded_calling.number.status_updated Branded number status updated.