Telnyx Calling: Trusted Calling — Full Documentation

Complete page content for Trusted Calling (Calling section) of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://developers.telnyx.com/development/llms/calling-trusted-calling-llms-txt.md

Branded Calling

Overview

Source: https://developers.telnyx.com/docs/branded-calling/overview.md

Branded Calling is currently in beta. We’re rolling it out gradually, so some features may not be fully available yet and behavior can change while we finalize the product. The exact information displayed on the recipient’s phone depends on many factors (carrier network, device manufacturer, device type, OS version, etc.). If something doesn’t work exactly as documented, it’s most likely still being enabled, and we appreciate your patience as we get everything ready. For the latest on availability and how branded calls are delivered, see Making calls with Branded Calling. This feature is currently supported in the US only.

Overview

Branded Calling displays your verified business identity on the recipient’s phone screen before they answer. Instead of seeing a bare phone number, or worse, “Spam Likely”, recipients see your business name, logo, and the reason for your call. The screenshots below show Branded Calling in action.

How it works

You register your business as an Enterprise and create a display identity (Display Identity Record) with your name, logo, and call reason.
Telnyx vets the DIR, verifying your business identity, IP ownership, and compliance.
You associate your Telnyx phone numbers with the verified DIR.
When you place a call from those numbers, Telnyx automatically signs the call with a cryptographic token (SHAKEN PASSporT) containing your DIR’s rich call data.
The terminating carrier verifies the signature and renders your DIR info on the recipient’s device.

Resource hierarchy

Enterprise (your organization, registered once)
├── Display Identity Record (DIR, the display identity)
│   ├── Phone-number Batch (the unit of carrier-network vetting)
│   │   ├── Phone Number (+15551234567)
│   │   └── Phone Number (+15559876543)
│   └── Call Reasons ["Customer Service", "Appointment Reminder"]
├── Display Identity Record (DIR, another identity)
│   └── Phone-number Batch
│       └── Phone Number (+15550001111)
└── Terms of Service Agreement (Branded Calling)

An Enterprise can have multiple Display Identity Records (DIRs).
Each Display Identity Record has its own display name, logo, call reasons, and phone numbers.
A Phone Number belongs to exactly one Display Identity Record.
Phone numbers are added in batches: each POST creates one batch, and the batch is the unit that goes through carrier-network vetting.
Call reasons are set at the Display Identity Record level.

Key concepts

Term	Description
Enterprise	Your top-level business registration. Required before creating DIRs.
Display Identity Record (DIR)	Defines what recipients see (name, logo, call reason).
Vetting	The verification process that validates your DIR identity and business information.
Call Reason	Text shown to recipients explaining why you’re calling (e.g. “Appointment Reminder”).

Ecosystem

Branded Calling is built on an industry-wide registry, managed by CTIA. The registry ensures trust among all participants through common technical and governance frameworks. Telnyx handles all ecosystem interactions on your behalf, you interact only with the Telnyx API.

Next steps

Quickstart guide, get your first branded call working
Pricing, Branded Calling pricing details
Display Identity Records, create and manage display identities
Phone Numbers, associate numbers with DIRs
Call Reasons, configure what recipients see
Infringement Claims, what to do if a claim is filed against your DIR

Quickstart

Source: https://developers.telnyx.com/docs/branded-calling/quickstart.md

Branded Calling is in beta. Learn more in Making calls with Branded Calling. This walk-through takes you from a fresh account to a verified Display Identity Record (DIR) with phone numbers attached. You’ll need a verified or enterprise-level Telnyx account and an API key.

Before you begin

You’ll need:

A Telnyx account with verified or enterprise access and an API key.
One or more US Telnyx phone numbers in your inventory. (Branded Calling is currently US-to-US; non-US numbers won’t produce a branded result yet.)
Your business legal details (legal name, EIN, jurisdiction of incorporation, addresses, contacts).
A logo image, 256×256 BMP only, ≤1 MB, hosted at a publicly-reachable HTTPS URL (optional, you can submit without one). Most design tools export PNG by default; convert to BMP with any standard image editor (Preview, Photoshop, ImageMagick, GIMP) before hosting.
Supporting documents (e.g. business registration, letter of authorization). Upload each one through the Telnyx Documents API first; the API gives you back a document_id that you reference here.

Step 1: Accept the Branded Calling Terms of Service

Read the full terms at telnyx.com/terms/branded-calling.

curl -X POST https://api.telnyx.com/v2/terms_of_service/branded_calling/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

Idempotent, calling again after you’ve already agreed is a no-op. You can check your current agreement status at any time:

curl "https://api.telnyx.com/v2/terms_of_service/status?product_type=branded_calling" \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 2: Create an Enterprise

curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Healthcare Inc.",
    "doing_business_as": "Acme Healthcare",
    "organization_type": "commercial",
    "organization_legal_type": "corporation",
    "country_code": "US",
    "jurisdiction_of_incorporation": "Delaware",
    "website": "https://acmehealthcare.example.com",
    "fein": "12-3456789",
    "industry": "healthcare",
    "number_of_employees": "51-200",
    "organization_contact": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@acmehealthcare.example.com",
      "job_title": "VP Operations",
      "phone_number": "+12125551234"
    },
    "billing_contact": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "billing@acmehealthcare.example.com",
      "phone_number": "+12125551234"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "NY",
      "city": "New York",
      "postal_code": "10001",
      "street_address": "123 Main St"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "NY",
      "city": "New York",
      "postal_code": "10001",
      "street_address": "123 Main St"
    }
  }'

Save the id from the response, you’ll need it for the activation step. For the full field reference (every required field, enum values, contact + address shape), see Enterprises.

Step 3: Activate Branded Calling on the enterprise

Branded Calling is a paid product that must be explicitly activated per enterprise. Without this step, DIR creation in Step 5 returns 400 with code=10015 and a detail pointing back to this endpoint.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/branded_calling \
  -H "Authorization: Bearer YOUR_API_KEY"

The HTTP response returns with the enterprise body. Activation completes asynchronously. The enterprise body comes back immediately, but the registration finishes a few seconds later. If you create a DIR (Step 5) right away you may get 400 with detail: "Branded calling registration has not completed" for roughly 10 seconds. Wait and retry, or poll the enterprise until activation settles. Both endpoints are idempotent. A 403 here means the Branded Calling Terms of Service hasn’t been accepted yet (back to Step 1). Activating Branded Calling on an enterprise is billable. See Branded Calling pricing.

Step 4: (Optional) Validate your call reasons up front

When a DIR’s call reasons are all pre-approved, the call-reason vetting check passes automatically, which can speed up review (the DIR is still vetted and is not auto-approved). Run them through the validator before creating the DIR, both reasons below are on the pre-approved catalogue, so this example returns all_pre_approved: true:

curl -X POST https://api.telnyx.com/v2/call_reasons/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["Appointment Reminder", "Follow-Up Calls"]'

The body is a bare JSON array of strings: do not wrap it in { "call_reasons": [...] }.

If you instead send a mix that includes any custom string (for example "Patient Follow-up", which is not on the pre-approved list), the response is requires_manual_vetting: true with the offending entries in non_approved_reasons. Custom reasons are still allowed; the call-reason check is then reviewed manually, which can take longer. Pull the live pre-approved catalogue with GET /v2/call_reasons (see the Call Reasons guide) and copy the reason strings verbatim into your DIR to help speed up the call-reason check.

Step 5: Create a DIR

A Display Identity Record (DIR) defines what recipients see on their phone: display name, logo, and call reason.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/dir \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme Healthcare",
    "authorizer_name": "Jane Smith",
    "authorizer_email": "jane@acmehealthcare.example.com",
    "certify_brand_is_accurate": true,
    "certify_no_shaft_content": true,
    "certify_ip_ownership": true,
    "call_reasons": ["Appointment Reminder", "Follow-Up Calls"],
    "logo_url": "https://acmehealthcare.example.com/logo-256.bmp",
    "documents": [
      {
        "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
        "document_type": "business_registration",
        "description": "Certificate of incorporation."
      }
    ]
  }'

Field rules, these are enforced and a violation returns 400 (with an error code such as 10015, 10025, or 10026 and a source.pointer to the offending field):

Field	Rule
`display_name`	Required, 1-35 characters, no emoji, not whitespace-only. Shown to recipients.
`authorizer_name`	Required, max 255 chars. Person authorizing the DIR registration.
`authorizer_email`	Required, valid email.
`certify_brand_is_accurate`	Required, must be `true`.
`certify_no_shaft_content`	Required, must be `true`. (SHAFT = Sex, Hate, Alcohol, Firearms, Tobacco.)
`certify_ip_ownership`	Required, must be `true`.
`call_reasons`	Required, 1-10 items, each 1-64 characters.
`logo_url`	Optional. HTTPS only, max 128 chars. Telnyx downloads it and validates it as a 256×256 BMP (≤1 MB) at create time; if validation fails the DIR is not written.
`documents`	Optional, up to 20 entries. Each `document_id` must come from a prior upload to the Telnyx Documents API. Duplicates within one DIR are rejected.
`reselling`	Optional boolean. `true` if you resell calling services on behalf of others. Defaults to `false`.

The DIR is created in draft status. Save the id, this is your dir_id.

Step 6: Submit for vetting

curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/submit \
  -H "Authorization: Bearer YOUR_API_KEY"

The DIR moves to submitted, then in_review. Telnyx then reviews and approves the DIR out-of-band (this is not instantaneous; pre-approved call reasons can shorten it - see Step 4). Wait for the DIR to reach verified before attaching phone numbers in Step 7. Outcomes:

verified, approved. Phone numbers can now be attached.
rejected, fixable. Read rejection_reasons on the DIR and the vetting_comment / rejection_reason entries on GET /v2/dir/{dir_id}/comments for context, PATCH the offending fields, then POST /submit again.
unsuccessful, system error. Same handling as rejected.
permanently_rejected, terminal. The only exit is DELETE /v2/dir/{dir_id} (remove any attached phone numbers first, or the delete returns 400).

If all your call reasons are pre-approved (Step 4), the call-reason check passes automatically, which can shorten review - but the DIR still goes through vetting before it reaches verified. Once a DIR is verified, a non-trivial PATCH that actually changes a field moves it back to draft and tears down the live registration. You must POST /submit and be re-approved before it serves traffic again. Avoid editing a verified DIR unless you intend to re-vet it. While waiting, poll GET /v2/dir/{dir_id} for the current status. Use a sensible cadence (e.g. once every 30-60 seconds); don’t poll in a tight loop. If /submit fails with a 400 and the DIR has an open infringement claim, resolve the claim first, see Infringement Claims.

Step 7: Attach phone numbers

Once the DIR is verified, you can attach phone numbers. A signed Letter of Authorization (LOA) is required on every add request. First upload your signed LOA to the Telnyx Documents API and capture the returned id:

# Step 7a - upload the signed LOA (multipart); the response includes the document id
curl -X POST https://api.telnyx.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@loa.pdf"
# Response includes "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"

Then add the numbers, referencing that id as document_id:

# Step 7b - add the numbers, with the LOA in the documents array
curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/phone_numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12125551234", "+12125555678"],
    "documents": [
      {
        "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
        "document_type": "letter_of_authorization",
        "description": "LOA covering this set of numbers."
      }
    ]
  }'

A documents array with at least one letter_of_authorization entry is required (1-20 documents). The request is rejected with 400 if it’s missing or has no LOA entry.
Up to 15 numbers per request.
Atomic: if any number is invalid, already attached, or not in your inventory, the entire batch is rejected with 400 and nothing is written. The error response identifies the offending number(s); remove them and re-submit the rest.
Numbers must be E.164 format and present in your Telnyx inventory.
The DIR must be in verified status. Adding numbers to a DIR in any other status returns 400 with detail "...DIR must be verified".

Adding phone numbers is billable. See Branded Calling pricing. Each POST creates one batch. Track batch progress through carrier-network vetting:

curl https://api.telnyx.com/v2/dir/{dir_id}/phone_number_batches \
  -H "Authorization: Bearer YOUR_API_KEY"

See Phone Numbers for the full batch lifecycle.

Step 8: Make branded calls

Once a phone number reaches verified status, it is eligible to display your branded identity on outbound calls. The recipient’s experience depends on their carrier and device supporting branded calling. Coverage is strongest on major US carriers with compatible devices.

What’s next

Display Identity Records (DIRs), full DIR lifecycle, statuses, editing, deletion.
Phone Numbers, adding/removing numbers and inspecting batches.
Call Reasons, the pre-approved list and the validator.
Infringement Claims, what to do if a claim is filed against your DIR.

Pricing

Source: https://developers.telnyx.com/docs/branded-calling/pricing.md

Pricing

Branded Calling pricing has three components:

Component	Cost	Description
Enterprise registration	Free	Registering your business as an Enterprise is free of charge.
Brand registration (OTC)	$50 one-time per Brand	A one-time fee when you create a Display Identity Record (Brand).
Brand registration (MRC)	$50/month per Brand	A recurring monthly fee for each active Brand.
Branded Call Display	$0.075 per call	Charged per call that displays your branded identity to the recipient.

For the full pricing details, see the Branded Calling pricing page.

Overview

Source: https://developers.telnyx.com/docs/branded-calling/enterprises.md

Overview

An Enterprise represents your business entity on the Telnyx platform. It’s the top-level resource you must register before you can use Branded Calling to display your verified business identity (display name, logo, call reason) on outbound calls.

What you need

To create an enterprise, you’ll need:

Field	Required	Description
`legal_name`	yes	Registered legal name (3-64 chars).
`doing_business_as`	yes	DBA name (max 255 chars).
`organization_type`	yes	One of `commercial`, `government`, `non_profit`.
`organization_legal_type`	yes	One of `corporation`, `llc`, `partnership`, `nonprofit`, `other`.
`country_code`	yes	ISO 3166-1 alpha-2 code. `US` and `CA` are accepted (`CA` applies to Number Reputation). Branded Calling itself is currently US-only.
`role_type`	no	One of `enterprise` (registers its own DIRs) or `bpo` (Business Process Outsourcer calling on behalf of others). Defaults to `enterprise`.
`jurisdiction_of_incorporation`	yes	State/province/country of registration (e.g. `Delaware`).
`website`	yes	Your business website.
`fein`	yes	Federal Employer Identification Number (`XX-XXXXXXX` or `XXXXXXXXX`).
`industry`	yes	Industry classification. Must be one of a fixed set of values (e.g. `technology`, `healthcare`, `retail`, `finance`, `legal`, `insurance`); an unrecognized value returns `400`.
`number_of_employees`	yes	One of `1-10`, `11-50`, `51-200`, `201-500`, `501-2000`, `2001-10000`, `10001+`.
`organization_contact`	yes	Object with `first_name`, `last_name`, `email`, `job_title`, `phone_number`.
`billing_contact`	yes	Object with `first_name`, `last_name`, `email`, `phone_number`.
`organization_physical_address`	yes	Physical business address.
`billing_address`	yes	Billing address.
`customer_reference`	no	Optional free-form identifier you can attach for your own bookkeeping (max 255 chars).

Quick start

1. Accept the Branded Calling Terms of Service

You must agree to the Branded Calling ToS before activating the product.

curl -X POST https://api.telnyx.com/v2/terms_of_service/branded_calling/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Create an enterprise

curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Plumbing LLC",
    "doing_business_as": "Acme Plumbing",
    "organization_type": "commercial",
    "organization_legal_type": "llc",
    "country_code": "US",
    "role_type": "enterprise",
    "jurisdiction_of_incorporation": "Delaware",
    "website": "https://acmeplumbing.example.com",
    "fein": "12-3456789",
    "industry": "technology",
    "number_of_employees": "51-200",
    "organization_contact": {
      "first_name": "Sam",
      "last_name": "Owner",
      "email": "sam@acmeplumbing.example.com",
      "job_title": "Compliance Lead",
      "phone_number": "+13125550000"
    },
    "billing_contact": {
      "first_name": "Alex",
      "last_name": "Bill",
      "email": "billing@acmeplumbing.example.com",
      "phone_number": "+13125550001"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    }
  }'

The response includes an id, use this enterprise ID for all subsequent API calls.

3. Activate Branded Calling on the enterprise

Branded Calling is a paid product that must be explicitly activated per enterprise. Without this step, DIR creation returns 400 with code=10015 and a detail pointing back to this endpoint.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/branded_calling \
  -H "Authorization: Bearer YOUR_API_KEY"

The HTTP response returns with the enterprise body. Activation completes asynchronously; if DIR creation returns 400 right after activation, wait a moment and retry. Both endpoints are idempotent. A 403 here means the Branded Calling Terms of Service hasn’t been accepted yet (back to step 1). Activating Branded Calling is billable. See Branded Calling pricing.

4. Next steps

Create your first Display Identity Record (DIR) and submit it for vetting.

Reusing the enterprise

Register the enterprise once and reuse it for all of your Branded Calling work. The API collects all required fields up front so you don’t need to update them later.

Access requirements

All Branded Calling endpoints require a verified or enterprise-level Telnyx account. Trial and standard paid accounts cannot access these features. See Account Levels and Capabilities for details on upgrading.

Overview

Source: https://developers.telnyx.com/docs/branded-calling/brands.md

Overview

A Display Identity Record (DIR) defines what recipients see on their phone screen when you call. Each DIR has a display name, an optional logo, and 1-10 call reasons. Display Identity Records must be vetted and approved by Telnyx before they become active. Once a DIR reaches verified status, calls placed from any phone number attached to it will display the branded identity on supported carriers and devices.

Prerequisites

Before creating a DIR:

The parent Enterprise must exist (POST /v2/enterprises).
The Branded Calling Terms of Service must be accepted (POST /v2/terms_of_service/branded_calling/agree).
Branded Calling must be activated on the enterprise (POST /v2/enterprises/{enterprise_id}/branded_calling). Without this, DIR creation returns 400 with code=10015. Activation completes asynchronously; if DIR creation returns 400 immediately after, retry - both endpoints are idempotent.

API endpoints

Method	Path	Description
`POST`	`/v2/enterprises/{enterprise_id}/dir`	Create a new DIR under an enterprise
`GET`	`/v2/dir`	List DIRs across the account
`GET`	`/v2/enterprises/{enterprise_id}/dir`	List DIRs under one enterprise
`GET`	`/v2/dir/{dir_id}`	Get a DIR
`PATCH`	`/v2/dir/{dir_id}`	Update a DIR
`DELETE`	`/v2/dir/{dir_id}`	Delete a DIR
`POST`	`/v2/dir/{dir_id}/submit`	Submit for vetting

Required fields

These are the DIR-level required fields. Anything related to the legal entity (legal name, EIN, addresses, contacts, jurisdiction) lives on the parent Enterprise: not on the DIR.

Field	Type	Description
`display_name`	string	Shown to recipients. 1-35 characters, no emoji, not whitespace-only.
`authorizer_name`	string	Authorizer point-of-contact name. Max 255 chars.
`authorizer_email`	string	Authorizer point-of-contact email.
`certify_brand_is_accurate`	boolean	Must be `true`.
`certify_no_shaft_content`	boolean	Must be `true`. (SHAFT = Sex, Hate, Alcohol, Firearms, Tobacco.)
`certify_ip_ownership`	boolean	Must be `true`.
`call_reasons`	array	1-10 strings, each 1-64 characters.

Optional fields

Field	Type	Description
`logo_url`	string	HTTPS URL (max 128 chars) to a 256×256 BMP image (≤1 MB). Telnyx downloads and validates it on every create / `PATCH`.
`documents`	array	Up to 20 entries of `{document_id, document_type, description?}`. Each `document_id` must come from a prior upload to the Telnyx Documents API.
`reselling`	boolean	`true` if you resell calling services on behalf of others. Defaults to `false`.

Logo requirements

The logo must be a BMP image, exactly 256×256 pixels, ≤1 MB, ≤32-bit color depth, hosted at a publicly-reachable HTTPS URL. PNG, JPEG, and other formats are rejected at create / PATCH time with a 400. Most design tools export PNG by default, convert to BMP with any standard image editor (Preview, Photoshop, ImageMagick, GIMP).

Document types

When you attach documents to a DIR, each entry’s document_type must be one of: letter_of_authorization, business_registration, articles_of_incorporation, tax_document, ein_letter, trademark_registration, website_ownership, business_license, professional_license, government_id, utility_bill, bank_statement, other The actual file is uploaded separately via the Telnyx Documents API; the document_id you receive from that upload is what you reference here.

Display Identity Record statuses

Status	Meaning
`draft`	Initial state. You’re still preparing the DIR. Editable.
`submitted`	Vetting requested. Editing, deleting, and re-submitting are blocked.
`in_review`	Telnyx is actively reviewing. Same restrictions as `submitted`.
`verified`	Approved. Phone numbers can be attached. Editable (but any non-trivial PATCH moves the DIR back to `draft` and tears down the live registration).
`rejected`	Vetting failed for fixable reasons. Edit and re-submit.
`unsuccessful`	Vetting failed for a system reason. Edit and re-submit.
`suspended`	The normal state for a DIR with an attached infringement claim (Telnyx may pre-emptively suspend the DIR while a claim is `pending` or `contested`). While the claim is open, recover with `PUT /v2/dir/{dir_id}/infringement_update` - plain `PATCH` + `POST /submit` is blocked (`409`). A DIR can also remain `suspended` after a `modified` resolution, at which point the claim is closed and `PATCH` + `POST /submit` work normally.
`expired`	The one-year verification window has closed. Re-submit to renew.
`infringement_claimed`	Legacy status. A new infringement claim moves the DIR to `suspended`, not here; you will not normally see this state. Where it still exists, phone numbers cannot be added and `PATCH` is rejected with a `400`.
`permanently_rejected`	Terminal. Cannot be re-submitted. The only exit is `DELETE`.

Updating a DIR

curl -X PATCH https://api.telnyx.com/v2/dir/{dir_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Updated Display Name",
    "call_reasons": ["Customer Service", "Billing Inquiry"]
  }'

PATCH is allowed in draft, rejected, unsuccessful, suspended, and verified. A few things to know:

For draft / rejected / unsuccessful, PATCH is a pure edit. The status doesn’t change. Call POST /submit to re-vet when ready.
suspended means an infringement claim is attached. PATCH itself is allowed and leaves the status unchanged, but POST /submit is blocked with a 409 while the claim is still pending or contested (the no_active_claims gate). To revise content and re-vet during an open claim, use PUT /v2/dir/{dir_id}/infringement_update instead - see Infringement Claims. The plain PATCH + POST /submit flow only works once the claim is resolved (e.g. resolution = modified, which leaves the DIR suspended with the claim closed).
For verified, a PATCH that actually changes a field flips the DIR back to draft and tears down the live registration. The DIR stops serving its branded identity on calls until you POST /submit and Telnyx re-approves it. Don’t edit a live verified DIR unless you intend to take it out of service and re-vet it.
If you provide logo_url, it is re-downloaded and re-validated on every PATCH. If validation fails the DIR isn’t updated.
documents are append-only, existing documents are never removed by a PATCH.

Resubmitting after rejection

When a DIR is rejected or unsuccessful, the headline reasons are in the rejection_reasons array on the DIR itself; the detailed reviewer notes appear on the comments thread. Read both. Fix the issues with PATCH, then submit again:

curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/submit \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a DIR

curl -X DELETE https://api.telnyx.com/v2/dir/{dir_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Allowed in: draft, rejected, unsuccessful, verified, suspended, expired, infringement_claimed, and permanently_rejected. The mid-vetting statuses submitted and in_review return 400. The DIR must have no phone numbers still attached. If any numbers are attached, the delete returns 400 (“DIR has N phone number(s) still attached. Delete every phone first, then delete the DIR.”). Remove them with DELETE /v2/dir/{dir_id}/phone_numbers first, then delete the DIR. Returns 409 if the DIR has a pending or contested infringement claim. Customers can only contest the claim, Telnyx adjudicates resolution.

Overview

Source: https://developers.telnyx.com/docs/branded-calling/bc-phone-numbers.md

Overview

After your DIR reaches verified status, attach your Telnyx phone numbers to it. Outbound calls from those numbers automatically display the DIR’s name, logo, and call reason on supported carriers and devices. Numbers are added in batches: each POST creates one batch, and the batch is the unit that goes through carrier-network vetting. A phone number can be attached to only one DIR at a time.

Pre-conditions

The DIR must be in verified status. Adding numbers to a DIR in any other status returns 400 (detail: ”…DIR must be verified”).
The phone numbers must already be in your Telnyx phone-number inventory.
Numbers must be in strict E.164 format: a leading + followed by 10-15 digits (no spaces, dashes, or parentheses).
A signed Letter of Authorization (LOA) must accompany every add request. Upload it to the Telnyx Documents API first and reference the returned id as a document_id.

Adding phone numbers is billable. See Branded Calling pricing.

API endpoints

Method	Path	Description
`POST`	`/v2/dir/{dir_id}/loa`	Render the DIR’s Letter of Authorization as a PDF
`POST`	`/v2/dir/{dir_id}/phone_numbers`	Add phone numbers (creates a batch)
`GET`	`/v2/dir/{dir_id}/phone_numbers`	List phone numbers attached to a DIR
`DELETE`	`/v2/dir/{dir_id}/phone_numbers`	Remove phone numbers from a DIR
`GET`	`/v2/dir/{dir_id}/phone_number_batches`	List batches for a DIR
`GET`	`/v2/dir/{dir_id}/phone_number_batches/{batch_id}`	Get one batch with its numbers

Each path above also has an equivalent form that includes the enterprise: /v2/enterprises/{enterprise_id}/dir/{dir_id}/phone_numbers (and the phone_number_batches variants). Both forms share the same request and response contract.

Render the Letter of Authorization (optional)

You can have Telnyx generate a pre-filled LOA PDF for the DIR instead of writing your own. POST /v2/dir/{dir_id}/loa returns an application/pdf. The enterprise identity and DIR display name are filled in server-side; you supply the phone numbers you intend to authorize (the same list you will add below), and optionally a third-party agent block and a drawn signature.

curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o loa.pdf \
  -d '{
    "phone_numbers": ["+12025551234", "+12025555678"]
  }'

phone_numbers: 1-15 numbers in +E164 format (the same numbers you authorize below).
agent: optional. The third-party reseller/partner managing the numbers; omit when you work with Telnyx directly.
signature: optional. When provided, the PDF embeds the signature image and printed name. When omitted, the PDF comes back unsigned so you can sign it externally.

Sign the rendered PDF, then upload it to the Telnyx Documents API and reference the returned document_id as a letter_of_authorization document when adding numbers (below).

Adding phone numbers (creating a batch)

A documents array containing at least one Letter of Authorization is required. First upload the signed LOA to the Telnyx Documents API:

# Step 1 - upload the signed LOA, returns a document id
curl -X POST https://api.telnyx.com/v2/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@loa.pdf"

Then add the numbers, referencing the returned document_id:

# Step 2 - add the numbers with the LOA
curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/phone_numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12125551234", "+12125555678"],
    "documents": [
      {
        "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
        "document_type": "letter_of_authorization",
        "description": "LOA covering this set of numbers."
      }
    ]
  }'

A documents array with at least one letter_of_authorization entry is required (1-20 documents).
The phone_numbers array must contain 1-15 numbers per request.
The batch is atomic: if any number fails validation (invalid format, duplicate within the request, not in your inventory, already attached to another DIR, or in a terminal permanently_rejected state), the entire request is rejected with 400 and nothing is written. On success the response is 201 with {"data": [...]}. On failure the body is the standard Telnyx error envelope with one errors[] entry per failure category, identifying the offending numbers; remove them and re-submit the rest.
A 400 is also returned if the DIR is in a status that cannot accept new numbers, including a suspended DIR with an open infringement claim (the detail then includes the open claim IDs).

Phone number statuses

Status	Meaning
`submitted`	Awaiting verification.
`in_review`	Under review by the vetting agent.
`verified`	Successfully verified and active for this DIR.
`unsuccessful`	An unexpected system error occurred.
`suspended`	Temporarily suspended.
`expired`	Past expiration date.
`permanently_rejected`	Terminally rejected by an admin. The number cannot be re-added to any DIR; attempting to add it returns `400`.

Inspecting batches

A batch is the unit of carrier-network vetting. Once a batch reaches verified (every number in it is verified), branded calling is active for the whole batch.

# List batches
curl -g "https://api.telnyx.com/v2/dir/{dir_id}/phone_number_batches?page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get one batch with its numbers
curl https://api.telnyx.com/v2/dir/{dir_id}/phone_number_batches/{batch_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Listing numbers

curl -g "https://api.telnyx.com/v2/dir/{dir_id}/phone_numbers?page[size]=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Standard JSON:API pagination (page[number], page[size], max 250).

Removing numbers

curl -X DELETE https://api.telnyx.com/v2/dir/{dir_id}/phone_numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+12125551234", "+12125555678"]
  }'

Up to 100 phone numbers per request. This call is partial-success: numbers that can be removed are returned under top-level data, and numbers that can’t (not associated, invalid, etc.) come back in a meta.errors array on the same response. If every number fails, the response is a 400 with the standard Telnyx error envelope. Removing a number tears down its registration on the Branded Calling network and frees the number to be attached to a different DIR.

Overview

Source: https://developers.telnyx.com/docs/branded-calling/call-reasons.md

Overview

A call reason is a short string explaining why your business is calling, for example, “Appointment Reminder” or “Delivery Update”. Call reasons are set at the DIR level as a list of 1-10 strings (each up to 64 characters) at DIR-create time. Telnyx maintains a list of pre-approved call reasons. When a DIR’s call_reasons are all pre-approved, the call-reason vetting check passes automatically, which can help speed up review. If any reason is custom (not pre-approved), that check is reviewed by a human instead. Either way the DIR still goes through full vetting; pre-approved reasons are not auto-approved.

API endpoints

Method	Path	Description
`GET`	`/v2/call_reasons`	List pre-approved call reasons.
`POST`	`/v2/call_reasons/validate`	Check whether a list of reasons is fully pre-approved.

List pre-approved call reasons

Default page[size] is 100 (max 250).

curl -g "https://api.telnyx.com/v2/call_reasons?page[size]=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use the returned reason strings verbatim in your DIR’s call_reasons array to help speed up the call-reason check during vetting.

Validate a list of call reasons

Before creating a DIR, check whether the reasons you plan to use are pre-approved:

curl -X POST https://api.telnyx.com/v2/call_reasons/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["Appointment Reminder", "Follow-Up Calls"]'

The body is a bare JSON array of strings: do not wrap it in { "call_reasons": [...] }. This is unusual for Telnyx APIs; copy the example verbatim.

The result is returned under a top-level data object with three fields: all_pre_approved (true when every reason is pre-approved and enabled), requires_manual_vetting (true when at least one reason is not pre-approved), and non_approved_reasons (the list of reasons that are not pre-approved).

Constraints

Limit	Value
Min call reasons per DIR	1
Max call reasons per DIR	10
Max characters per reason	64

Overview

Source: https://developers.telnyx.com/docs/branded-calling/terms-of-service.md

Overview

You must accept the Branded Calling Terms of Service before activating Branded Calling on any enterprise (POST /v2/enterprises/{enterprise_id}/branded_calling); without it, activation returns 403. Read the full terms at telnyx.com/terms/branded-calling. Acceptance is a one-time, idempotent action per user. If Telnyx publishes a new ToS version, you may need to re-accept.

API endpoints

Method	Path	Description
`GET`	`/v2/terms_of_service/status`	Check whether the current user has agreed to the current ToS for a product.
`POST`	`/v2/terms_of_service/branded_calling/agree`	Agree to the Branded Calling ToS. No body.
`GET`	`/v2/terms_of_service/agreements`	List your past agreements (paginated).
`GET`	`/v2/terms_of_service/agreements/{agreement_id}`	Get one specific agreement.

The generic GET /v2/terms_of_service/status, GET /v2/terms_of_service/agreements, and GET /v2/terms_of_service/info endpoints accept a product_type query parameter that defaults to branded_calling.

Check your status

curl "https://api.telnyx.com/v2/terms_of_service/status?product_type=branded_calling" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pass product_type=branded_calling. If omitted, it defaults to branded_calling.

Accept Branded Calling ToS

curl -X POST https://api.telnyx.com/v2/terms_of_service/branded_calling/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

Idempotent, calling again after you’ve already agreed returns the existing agreement.

Overview

Source: https://developers.telnyx.com/docs/branded-calling/infringement-claims.md

Overview

If a third party believes your DIR’s display name, logo, or content infringes on a protected right (trademark, copyright, etc.), they can file an infringement claim through Telnyx. Claims are filed and adjudicated by Telnyx, you cannot create a claim through this API, but you can read and contest claims filed against your own DIRs. While a claim is pending or contested:

The DIR is moved to suspended.
Branded calling pauses for the affected DIR.
You cannot add phone numbers to the DIR (returns 400).
You cannot delete the DIR (returns 409, blocked by the no_active_claims precondition).
You cannot re-submit the DIR with POST /submit (returns 409 with the open claim IDs, blocked by the no_active_claims precondition).
To revise content while the claim is open, call PUT /v2/dir/{dir_id}/infringement_update on the suspended DIR (see “Fix-and-resubmit” below). This is the only way to re-vet during an open claim.

Claim lifecycle

pending ──► contested  (you submit a contest)
        ──► resolved   (Telnyx admin adjudicates)

resolved.resolution = upheld   ──► your DIR moves to permanently_rejected (terminal); the live registration and phone-number registrations are torn down. The DIR cannot be recovered, create a new DIR with corrected content.
resolved.resolution = rejected ──► claim is dismissed; if your DIR was suspended for the claim, it is restored to verified and branded calling resumes.
resolved.resolution = modified ──► partial outcome; DIR status is unchanged by the resolve, see resolution_notes for required follow-up.

API endpoints

Method	Path	Description
`GET`	`/v2/dir/{dir_id}/infringement_claims`	List claims against a DIR
`GET`	`/v2/infringement_claims/{claim_id}`	Get a single claim
`POST`	`/v2/infringement_claims/{claim_id}/contest`	File a contest

Listing claims on a DIR

curl -g "https://api.telnyx.com/v2/dir/{dir_id}/infringement_claims?page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting a single claim

curl https://api.telnyx.com/v2/infringement_claims/{claim_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Contesting a claim

You can submit a contest more than once, the first submission moves the claim from pending to contested; later submissions append additional notes and documents to the same claim without changing status.

curl -X POST https://api.telnyx.com/v2/infringement_claims/{claim_id}/contest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contest_notes": "Acme Plumbing LLC has been operating under this name since 2008, predating the cited trademark filing. Attached: trademark search results and our state business registration.",
    "documents": [
      {
        "document_id": "d1e2f3a4-573d-446d-b3ce-aff9117272a6",
        "document_type": "trademark_registration",
        "description": "Our 2008 state trademark registration."
      }
    ]
  }'

Field	Required	Description
`contest_notes`	yes	10-2000 characters. Explain why the claim is invalid or how you’ve addressed it.
`documents`	no	Up to 20 supporting documents per submission. Each must reference a `document_id` from the Telnyx Documents API and include a `document_type`. Duplicate `document_id`s within one submission are rejected.

Contesting a resolved claim returns 400.

Fix-and-resubmit a `suspended` DIR

While an infringement claim is open (pending or contested), Telnyx may pre-emptively move your DIR to suspended to halt branded calling. To recover without waiting for the claim to be resolved, use the dedicated PUT /v2/dir/{dir_id}/infringement_update endpoint to atomically apply your content fix and re-submit for vetting in one call. This endpoint requires an active (unresolved) claim and a suspended DIR (see “After the claim resolves” below).

curl -X PUT https://api.telnyx.com/v2/dir/{dir_id}/infringement_update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Acme Local Plumbing",
    "logo_url": "https://acmeplumbing.example.com/logo-v2-256.bmp",
    "certify_no_infringement": true,
    "certify_brand_is_accurate": true,
    "certify_no_shaft_content": true,
    "certify_ip_ownership": true,
    "infringement_resolution_notes": "Renamed to Acme Local Plumbing and replaced the logo so the new display identity no longer reads on the cited trademark.",
    "documents": [
      {
        "document_id": "550e8400-e29b-41d4-a716-446655440000",
        "document_type": "trademark_registration",
        "description": "Registration proving we own the revised name."
      }
    ]
  }'

Requirements:

The DIR must have an active (unresolved) infringement claim.
The DIR must be in suspended status.
All four certifications (certify_no_infringement, certify_brand_is_accurate, certify_no_shaft_content, certify_ip_ownership) must be supplied as true.
infringement_resolution_notes is required (10-500 chars), explain how the edits resolve the claim.

The content fields (display_name, logo_url, call_reasons) are all optional; send only the ones you’re changing. You can also attach supporting documents (up to 20, append-only) as proof that backs your fix, for example authorization or licensing paperwork. Each entry references a document_id from the Telnyx Documents API plus a document_type, and re-attaching a document already on the DIR is rejected. See the Infringement Claims guide for the full field table. After the update, the DIR moves to submitted and goes through vetting again, even though the claim is still open. If the new content passes vetting, the DIR returns to verified and the claim can be resolved. If vetting rejects the changes, the DIR returns to suspended and you can update again. You can submit infringement_update multiple times while the claim is open.

Why the standard PATCH + POST /submit flow doesn’t work here: POST /submit is gated by the FSM’s no_active_claims precondition and returns 409 while a claim is still pending or contested. PUT /infringement_update is the only customer-callable endpoint that can move a suspended-with-open-claim DIR back into vetting; it bypasses the no_active_claims gate by design. Use PATCH + POST /submit only after Telnyx has marked the claim resolved with resolution = modified. resolution = rejected auto-restores the DIR and resolution = upheld is terminal, neither requires a customer PATCH + /submit.

After the claim resolves

resolution = rejected: your DIR is automatically restored to verified; no action required. Branded calling resumes.
resolution = upheld: your DIR is permanently_rejected and cannot be reused. To continue branded calling, create a new DIR with corrected content; you may reuse the same enterprise.
resolution = modified: read resolution_notes for the required content edits, then PATCH the DIR and POST /submit (the no_active_claims gate is now open because the claim is resolved).

API Reference (Trusted Calling)

Enterprises

List enterprises: Return the enterprises you own, paginated. The default page size is 20; the maximum is 250.
Create an enterprise: Create the legal entity (enterprise) that represents your business on the Telnyx platform.
Get an enterprise: Retrieve a single enterprise by id. Returns 404 if the id does not exist or does not belong to your account.
Replace an enterprise: Replace the enterprise’s mutable fields. Only mutable fields may be sent. Server-assigned and immutable fields (id, record_type, created_at, updated_at…
Delete an enterprise: Soft-delete an enterprise.
Activate Branded Calling on an enterprise: Branded Calling is a paid product that must be activated on each enterprise. Activation is idempotent:

Display Identity Records

List DIRs in an enterprise: Return the DIRs (Display Identity Records) belonging to a single enterprise. Pagination is JSON:API style (page[number], page[size], max 250). Supports `fi…
Create a Display Identity Record (DIR): Create a new DIR under the given enterprise. The DIR starts in draft status; it must be submitted (POST .../submit) and approved by Telnyx before any phone…
List all DIRs across your enterprises: Returns every DIR (Display Identity Record) you own, across all of your enterprises, as a single list. Pagination is JSON:API style (page[number], `page[size…
Get a DIR by id: Returns a single DIR by id. The enterprise is resolved server-side from the DIR id. Returns 404 if the DIR does not exist or is not yours.
Update a DIR: Edit a DIR. DIRs in draft, rejected, unsuccessful, or suspended can be edited freely: PATCH is a pure edit, status is never changed, and you re-vet b…
Delete a DIR: Delete a DIR. Failure modes: 400 if a child phone number is in a non-deletable status, 409 if the DIR has an unresolved infringement claim, 404 if the DI…
Submit a DIR for vetting: Submit a DIR for vetting. Sends the DIR back through the vetting cycle from any non-terminal status. When re-submitting from suspended or expired, the DIR’…
Render the Branded Calling LOA for a DIR: Generate a pre-filled Letter of Authorization (LOA) PDF for a DIR. Enterprise identity (legal name, DBA, address, contact, website, tax id) and the DIR display…

Reference Data

List supported DIR document types: Reference list of document_type values accepted by DirCreateRequest.documents[].document_type and the infringement-contest endpoint. Each entry has a stabl…
List standard call reasons: Telnyx maintains a library of pre-vetted call-reason phrases (e.g. “Appointment reminders”, “Billing inquiries”) that carry through DIR vetting smoothly. You c…
Validate a list of call reasons: Check up to 10 candidate call_reasons strings against Telnyx’s vetting heuristics before sending them on a DIR create or update. The endpoint flags strings t…

Comments

List comments on a DIR: List the comments on a DIR. The enterprise is resolved server-side from the DIR id.
Post a comment on a DIR: Post a customer comment on a DIR (for example, to respond to reviewer notes). Send only content (1–5000 chars) and an optional parent_comment_id; the serve…

Phone Numbers

List phone numbers attached to a DIR: List the phone numbers registered under a DIR. The enterprise is resolved server-side from the DIR id.
Add phone numbers to a DIR: Register phone numbers under a DIR. The enterprise is resolved server-side from the DIR id. Same body, failure modes, and batch semantics whichever path form y…
Remove phone numbers from a DIR: Deregister phone numbers from a DIR. The enterprise is resolved server-side from the DIR id. Returns a partial-success envelope.

Phone Number Batches

List phone-number batches for a DIR: List the phone-number batches submitted under a DIR. The enterprise is resolved server-side from the DIR id.
Get a phone-number batch: Get a single phone-number batch by id. The enterprise is resolved server-side from the DIR id.

Infringement Claims

List infringement claims for a DIR: Return the trademark or copyright claims filed against this DIR. Each claim’s status is pending (newly filed; DIR auto-suspended), contested (you have su…
Update a DIR to resolve an infringement concern: Push a fix for a DIR that is suspended with an open infringement claim back into vetting. POST /dir/{dir_id}/submit is blocked while a claim is open, so th…
Get an infringement claim: Retrieve a single claim by id. Returns 404 if the claim does not exist or is not against a DIR you own.
Contest an infringement claim: Submit a written response and supporting documents disputing the claim. The first call moves the claim from pending to contested; subsequent calls append s…

Terms of Service

Agree to the Branded Calling Terms of Service: Records the authenticated user’s agreement to the current Branded Calling ToS. No body required. Idempotent - re-calling after agreement is a no-op and returns…
Get Terms of Service information: Returns the available Terms of Service agreements (product, current version, terms URL, effective date). Omit product_type to return all products; pass it to…
Get the calling user’s Terms of Service status: Returns whether the authenticated user has agreed to the current Terms of Service for the product given by product_type. Used during onboarding to decide whe…
List the calling user’s Terms of Service agreements: Returns the Terms of Service agreements the authenticated user has on file. Each entry records the version agreed to and when. Most users only have one agreeme…
Get a Terms of Service agreement by id: Retrieve a single ToS agreement record. Returns 404 if the agreement does not exist or does not belong to the authenticated user.

​Telnyx Calling: Trusted Calling — Full Documentation

​Branded Calling

​Overview

​Overview

​How it works

​Resource hierarchy

​Key concepts

​Ecosystem

​Next steps

​Quickstart

​Before you begin

​Step 1: Accept the Branded Calling Terms of Service

​Step 2: Create an Enterprise

​Step 3: Activate Branded Calling on the enterprise

​Step 4: (Optional) Validate your call reasons up front

​Step 5: Create a DIR

​Step 6: Submit for vetting

​Step 7: Attach phone numbers

​Step 8: Make branded calls

​What’s next

​Pricing

​Pricing

​Overview

​Overview

​What you need

​Quick start

​1. Accept the Branded Calling Terms of Service

​2. Create an enterprise

​3. Activate Branded Calling on the enterprise

​4. Next steps

​Reusing the enterprise

​Access requirements

​Overview

​Overview

​Prerequisites

​API endpoints

​Required fields

​Optional fields

​Logo requirements

​Document types

​Display Identity Record statuses

​Updating a DIR

​Resubmitting after rejection

​Deleting a DIR

​Overview

​Overview

​Pre-conditions

​API endpoints

​Render the Letter of Authorization (optional)

​Adding phone numbers (creating a batch)

​Phone number statuses

​Inspecting batches

​Listing numbers

​Removing numbers

​Overview

​Overview

​API endpoints

​List pre-approved call reasons

​Validate a list of call reasons

​Constraints

​Overview

​Overview

​API endpoints

​Check your status

​Accept Branded Calling ToS

​Overview

​Overview

​Claim lifecycle

​API endpoints

​Listing claims on a DIR

​Getting a single claim

​Contesting a claim

​Fix-and-resubmit a suspended DIR

​After the claim resolves

​API Reference (Trusted Calling)

​Enterprises

​Display Identity Records

​Reference Data

​Comments

​Phone Numbers

Telnyx Calling: Trusted Calling — Full Documentation

Branded Calling

Overview

Overview

How it works

Resource hierarchy

Key concepts

Ecosystem

Next steps

Quickstart

Before you begin

Step 1: Accept the Branded Calling Terms of Service

Step 2: Create an Enterprise

Step 3: Activate Branded Calling on the enterprise

Step 4: (Optional) Validate your call reasons up front

Step 5: Create a DIR

Step 6: Submit for vetting

Step 7: Attach phone numbers

Step 8: Make branded calls

What’s next

Pricing

Pricing

Overview

Overview

What you need

Quick start

1. Accept the Branded Calling Terms of Service

2. Create an enterprise

3. Activate Branded Calling on the enterprise

4. Next steps

Reusing the enterprise

Access requirements

Overview

Overview

Prerequisites

API endpoints

Required fields

Optional fields

Logo requirements

Document types

Display Identity Record statuses

Updating a DIR

Resubmitting after rejection

Deleting a DIR

Overview

Overview

Pre-conditions

API endpoints

Render the Letter of Authorization (optional)

Adding phone numbers (creating a batch)

Phone number statuses

Inspecting batches

Listing numbers

Removing numbers

Overview

Overview

API endpoints

List pre-approved call reasons

Validate a list of call reasons

Constraints

Overview

Overview

API endpoints

Check your status

Accept Branded Calling ToS

Overview

Overview

Claim lifecycle

API endpoints

Listing claims on a DIR

Getting a single claim

Contesting a claim

Fix-and-resubmit a `suspended` DIR

After the claim resolves

API Reference (Trusted Calling)

Enterprises

Display Identity Records

Reference Data

Comments

Phone Numbers