# Telnyx Calling: Trusted Calling — Full Documentation
> Complete page content for Trusted Calling (Calling section) of the Telnyx developer docs (https://developers.telnyx.com).
> This file: https://developers.telnyx.com/docs/development/llms/calling-trusted-calling-llms-full-txt · Root index: https://developers.telnyx.com/llms.txt

## 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](https://support.telnyx.com/en/articles/15138152-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

1. You register your business as an **Enterprise** and create a display identity (**Display Identity Record**) with your name, logo, and call reason.
2. Telnyx vets the DIR, verifying your business identity, IP ownership, and compliance.
3. You associate your Telnyx phone numbers with the verified DIR.
4. 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.
5. 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](/docs/branded-calling/quickstart), get your first branded call working
- [Pricing](/docs/branded-calling/pricing), Branded Calling pricing details
- [Display Identity Records](/docs/branded-calling/brands), create and manage display identities
- [Phone Numbers](/docs/branded-calling/bc-phone-numbers), associate numbers with DIRs
- [Call Reasons](/docs/branded-calling/call-reasons), configure what recipients see
- [BPO (Business Process Outsourcer)](/docs/branded-calling/bpo), for call centers placing branded calls on behalf of their clients
- [Infringement Claims](/docs/branded-calling/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](https://support.telnyx.com/en/articles/15138152-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](/docs/account-setup/levels-and-capabilities) and an API key.

## Before you begin

You'll need:

- A Telnyx account with **verified** or **enterprise** access and an [API key](https://portal.telnyx.com/#/app/api-keys).
- 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](/api-reference/documents/upload-a-document) 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](https://telnyx.com/terms/branded-calling).

```bash
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:

```bash
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

```bash
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](/docs/branded-calling/enterprises).

## Step 3: Activate Branded Calling on the enterprise

Branded Calling 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.

```bash
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 is **free**. Your account must have available credit, or the request is rejected with `400`. The Branded Calling fees are charged per DIR and per branded call. See [Branded Calling pricing](/docs/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`:

```bash
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](/docs/branded-calling/call-reasons)) 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.

```bash
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](/api-reference/documents/upload-a-document). 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

```bash
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](/docs/branded-calling/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](/api-reference/documents/upload-a-document) and capture the returned `id`:

```bash
# 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`:

```bash
# 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 **free**. The Branded Calling fees are charged per DIR and per branded call. See [Branded Calling pricing](/docs/branded-calling/pricing).

Each `POST` creates one **batch**. Track batch progress through carrier-network vetting:

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

See [Phone Numbers](/docs/branded-calling/bc-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)](/docs/branded-calling/brands), full DIR lifecycle, statuses, editing, deletion.
- [Phone Numbers](/docs/branded-calling/bc-phone-numbers), adding/removing numbers and inspecting batches.
- [Call Reasons](/docs/branded-calling/call-reasons), the pre-approved list and the validator.
- [Infringement Claims](/docs/branded-calling/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](https://telnyx.com/pricing/branded-calling).

---

### 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](/docs/branded-calling/overview) 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` (a business registering its own DIRs, the default and the right choice for almost everyone) or `bpo` (a call center that places calls on behalf of another business and cannot own DIRs). Fixed at creation. 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). |

Set `role_type` to `bpo` only for the enterprise that describes a call center (a Business Process Outsourcer, or BPO) that places calls on behalf of other businesses. That BPO enterprise holds the call center's own details and cannot have a DIR. Each client the call center calls for gets its own normal enterprise (leave `role_type` unset) and a DIR under it, created in the same account. For example, if the call center Dial Partners LLC calls for Maple Ridge Insurance, its BPO enterprise uses `"legal_name": "Dial Partners LLC"` and Dial Partners' own FEIN, contact, and address, while Maple Ridge's company details go on a separate Maple Ridge enterprise, and its display name, logo, and phone numbers go on a DIR under that enterprise. If your calls display your own business's name, you do not need a BPO enterprise. See [BPO (Business Process Outsourcer) support](/docs/branded-calling/bpo) for the full flow.

## Quick start

### 1. Accept the Branded Calling Terms of Service

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

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

### 2. Create an enterprise

```bash
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 must be explicitly activated per enterprise. Without this step, DIR creation returns `400` with `code=10015` and a `detail` pointing back to this endpoint.

```bash
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 **free**. Your account must have available credit, or the request is rejected with `400`. The Branded Calling fees are charged per DIR and per branded call. See [Branded Calling pricing](/docs/branded-calling/pricing).

### 4. Next steps

- [Create your first Display Identity Record (DIR)](/docs/branded-calling/quickstart) 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](/docs/account-setup/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:

1. The parent **Enterprise** must exist (`POST /v2/enterprises`).
2. The Branded Calling **Terms of Service** must be accepted (`POST /v2/terms_of_service/branded_calling/agree`).
3. **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}` | Request deletion of 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](/api-reference/documents/upload-a-document). |
| `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](/api-reference/documents/upload-a-document); 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 and re-submitting are blocked. Deletion can still be requested. |
| `in_review` | Telnyx is actively reviewing. Editing, re-submitting, and deleting are blocked. |
| `verified` | Approved. Phone numbers can be attached. Editable (a PATCH that changes a field moves the DIR back to `draft`; the approved identity keeps displaying until the edit is re-approved). |
| `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`. |
| `delete_requested` | You requested deletion. Telnyx completes the removal shortly after. A verified DIR keeps its branded identity, and its billing, until then. |

## Updating a DIR

```bash
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](/docs/branded-calling/infringement-claims#fix-and-resubmit-a-suspended-dir). 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`. The currently approved identity keeps displaying; your edits go live only after you `POST /submit` and Telnyx re-approves the DIR. Changing only `bpo_authorizations` or `webhook_url` is the exception: the DIR stays `verified`.
- 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](/docs/branded-calling/brands). Read both. Fix the issues with `PATCH`, then submit again:

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

## Deleting a DIR

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

`DELETE` requests deletion. It returns `202` with the DIR in `delete_requested`, and Telnyx completes the removal (de-registration and cleanup) shortly after. A verified DIR keeps its branded identity, and its billing, until then.

```json
{ "data": { "id": "c1e5a8a2-7f53-4c6b-9d2e-1f0b6a9d4e21", "status": "delete_requested" } }
```

Allowed in every status except `in_review`, which returns `400` (wait for the review to finish).

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](/docs/branded-calling/infringement-claims) the claim, Telnyx adjudicates resolution.

---

### Overview

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

## Overview

A **Business Process Outsourcer (BPO)** is a call center or outsourcer that places calls on behalf of other businesses. When a BPO calls for a client, the person being called should see the **client's** name and logo, not the call center's.

With Branded Calling, a BPO does this from its own Telnyx account. In that one account it sets up three separate records, each describing a different company or brand:

1. **A BPO enterprise** (`"role_type": "bpo"`), describing **the call center itself**.
2. **An enterprise for each client** (`"role_type": "enterprise"`, the default), describing **that client's business**.
3. **A DIR under each client's enterprise**, describing **the brand the called person sees**: display name, logo, call reasons, and phone numbers.

Then it links each client's DIR to its BPO enterprise, backed by a Letter of Authorization (LOA) the client signs. Once approved, the link adds the call center to the client DIR's list of authorized callers in the branded calling registry.

If your calls display **your own** business's name, you are not acting as a BPO, even if you run your own call center. Create a normal enterprise and a DIR for your own brand. See the [Quickstart](/docs/branded-calling/quickstart).

## Example: which data goes where

This guide follows two fictional companies:

- **Dial Partners LLC** is the **BPO**. It is a call center and the Telnyx customer. Everything below is done from Dial Partners' Telnyx account, with its API key.
- **Maple Ridge Insurance Inc.** is Dial Partners' **client**, the brand owner. It hired Dial Partners to call its policyholders, and wants them to see "Maple Ridge Insurance" and its logo on their phone.

Dial Partners does all the data entry, but not all the data is its own. Each record holds **one company's data only**, and for the client's records Dial Partners has to get the information from Maple Ridge:

| Record | Describes | Where Dial Partners gets the data | Example values | Must NOT contain |
| :--- | :--- | :--- | :--- | :--- |
| BPO enterprise (`"role_type": "bpo"`) | Dial Partners, the call center | Its own records | `"legal_name": "Dial Partners LLC"`, Dial Partners' FEIN `98-7654321`, website, address, contact Alex Rivera (`alex@dialpartners.example.com`) | Anything about Maple Ridge: its name, FEIN, address, logo, call reasons, or phone numbers |
| Client enterprise (`"role_type": "enterprise"`) | Maple Ridge, the client business | **From Maple Ridge** | `"legal_name": "Maple Ridge Insurance Inc."`, Maple Ridge's FEIN `36-4829105`, website, address, contact Jordan Lee (`jordan.lee@mapleridge.example.com`) | Dial Partners' details |
| DIR, under the client enterprise | The brand the called person sees | Display name, logo, call reasons, and authorizer **from Maple Ridge**. The phone numbers are Telnyx numbers in Dial Partners' account that it will call from for Maple Ridge. | `"display_name": "Maple Ridge Insurance"`, Maple Ridge's logo, call reasons `["Policy renewal", "Claim follow-up"]`, authorizer Jordan Lee, the phone numbers that display the brand | Dial Partners' name or logo |
| Link: `bpo_authorizations` on the DIR | Permission for Dial Partners to call as Maple Ridge | The BPO enterprise `id` is Dial Partners' own; the LOA is **signed by Maple Ridge** | The BPO enterprise's `id`, plus the LOA signed by Maple Ridge | |

### Collect from your client before you start

Before creating the client's records, get the following from the client (Maple Ridge in the example). None of it can be filled in with the call center's own details.

- **Company details** for the client enterprise: legal name, DBA, FEIN, organization type and legal type, jurisdiction of incorporation, website, industry, number of employees, physical and billing address, and a contact person with name, job title, email, and phone. See [Enterprises](/docs/branded-calling/enterprises) for the full field list.
- **Brand details** for the DIR: the display name people should see, the logo (256x256 BMP), and the call reasons.
- **An authorizer at the client**: a person at Maple Ridge (name and email) who stands behind the brand. If Telnyx sends a verification code to the DIR's authorizer email, it goes to that person, so they have to pass the code back to you.
- **Supporting documents**, if any, that show the client owns the brand (for example, business registration).
- **Business and financial references** for the client, if your account is required to provide them. When required, they must be submitted before the DIR is submitted (verify the authorizer email, then submit references, then submit the DIR). These are the client's references, not the call center's.
- **A signature on the BPO Letter of Authorization** from the client's contact, in step 6. This is the client's written permission for you to call under its brand.
- **A signature on the phone-number Letter of Authorization** from the client's contact, in step 7. This letter lists the numbers that will display the client's brand. It names the client as the enterprise and your call center as the authorized agent, and the client signs it, not you.

**The most common mistake** is putting the client's details into the BPO enterprise. For example, Dial Partners creates its BPO enterprise and fills in `"legal_name": "Maple Ridge Insurance Inc."`, Maple Ridge's FEIN, and Maple Ridge's address. That BPO enterprise now describes the wrong company, and it still cannot carry the brand: a BPO enterprise can never have a DIR.

The BPO enterprise always describes the call center. The client's company details go on the client's own enterprise, and the brand (display name, logo, call reasons, phone numbers) goes on the DIR under the client's enterprise.

A few rules follow from this:

- **A BPO enterprise cannot have a DIR.** Creating a DIR under it is rejected with `400`. DIRs always go under a client enterprise.
- **You create the BPO enterprise once.** Every client's DIR links to the same BPO enterprise.
- **Each client gets its own enterprise.** If Dial Partners also calls for a second client, it creates a second client enterprise and DIR, and links that DIR to the same BPO enterprise.
- **All records live in the same Telnyx account.** A DIR can only be linked to an approved BPO enterprise in your own account. Linking a BPO enterprise from another Telnyx account is rejected with `400`.
- **The type is fixed at creation.** A BPO enterprise cannot be changed into a normal enterprise, or the other way around. If you created the wrong type, create a new enterprise of the right type.

## The whole flow at a glance

Everything below is done from the call center's Telnyx account (Dial Partners in the example). The client (Maple Ridge) only provides information and signs two letters. Each line links to the step with the details.

**Set up the call center (once)**

1. **Create the BPO enterprise** with the call center's own details and `"role_type": "bpo"` (`POST /v2/enterprises`). Keep its `id`. [Step 1](#step-1-create-the-bpo-enterprise)
2. **Verify its contact email**: request a 6-digit code, then confirm it (`POST /v2/enterprises/{id}/verify_email`, then `/confirm`). [Step 2](#step-2-verify-the-bpos-contact-email)
3. **Turn on Branded Calling for the BPO enterprise** (`POST /v2/enterprises/{id}/branded_calling`). Needs the Terms of Service accepted and a US enterprise; it's free. [Step 3](#step-3-enable-branded-calling-on-the-bpo-enterprise)
4. **Wait for Telnyx to approve the BPO enterprise.** Check `bpo_verification_status` until it is `approved`. [Step 4](#step-4-telnyx-approves-the-bpo-enterprise)

**Set up each client (repeat per client)**

5. **Collect the client's information**: company details, brand details (display name, logo, call reasons), and an authorizer. [Checklist](#collect-from-your-client-before-you-start)
6. **Create the client's enterprise** with the client's details, accept the Branded Calling Terms of Service if you haven't yet, and activate Branded Calling on it. [Step 5](#step-5-create-the-clients-enterprise-and-dir)
7. **Create the client's DIR** under the client's enterprise. Do not submit it yet. [Step 5](#step-5-create-the-clients-enterprise-and-dir)
8. **Get the BPO letter signed**: generate it (`POST /v2/dir/{dir_id}/bpo_loa`), have the **client's contact** sign it, and upload it to the Documents API. [Step 6](#step-6-link-the-dir-to-the-bpo-enterprise)
9. **Link the DIR to the BPO enterprise**: send `bpo_authorizations` with your BPO enterprise `id` and the signed letter's `document_id` (`PATCH /v2/dir/{dir_id}`). [Step 6](#step-6-link-the-dir-to-the-bpo-enterprise)
10. **Submit the DIR** (`POST /v2/dir/{dir_id}/submit`). Telnyx reviews the DIR and the link together; approving the DIR approves the link. [Step 7](#step-7-submit-the-dir-then-add-phone-numbers)
11. **Get the phone-number letter signed**: generate it (`POST /v2/dir/{dir_id}/loa`) with your call center as the `agent`, have the **client's contact** sign it, and upload it. [Phone Numbers](/docs/branded-calling/bc-phone-numbers)
12. **Add the phone numbers** to the approved DIR, attaching the signed phone-number letter (`POST /v2/dir/{dir_id}/phone_numbers`). [Phone Numbers](/docs/branded-calling/bc-phone-numbers)

Order matters. Turning on Branded Calling for the BPO enterprise (step 3) is what lets its client DIRs go live: skip it and every linked DIR is held back. The BPO enterprise can't be approved until its email is verified, a DIR can't be linked until the BPO enterprise is approved, a DIR can't be edited (so can't be linked) while it is under review, and phone numbers can only be added once the DIR is approved.

## Step 1: Create the BPO enterprise

The BPO enterprise uses the same fields as any [enterprise](/docs/branded-calling/enterprises), plus `"role_type": "bpo"`. Branded Calling is US-only, so the call center must be a US company (`"country_code": "US"`). Every field describes **the call center itself**. In the example, Dial Partners enters its own legal name, FEIN, website, contact, and address, and nothing about Maple Ridge.

```bash
# Dial Partners (the call center) creates its BPO enterprise.
# Every value below is Dial Partners' own data, never the brand owner's.
curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role_type": "bpo",
    "legal_name": "Dial Partners LLC",
    "doing_business_as": "Dial Partners",
    "organization_type": "commercial",
    "organization_legal_type": "corporation",
    "country_code": "US",
    "jurisdiction_of_incorporation": "Delaware",
    "website": "https://dialpartners.example.com",
    "fein": "98-7654321",
    "industry": "business",
    "number_of_employees": "51-200",
    "organization_contact": {
      "first_name": "Alex",
      "last_name": "Rivera",
      "email": "alex@dialpartners.example.com",
      "job_title": "Operations Manager",
      "phone_number": "+12125559876"
    },
    "billing_contact": {
      "first_name": "Alex",
      "last_name": "Rivera",
      "email": "billing@dialpartners.example.com",
      "phone_number": "+12125559876"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "NY",
      "city": "New York",
      "postal_code": "10001",
      "street_address": "500 Market St"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "NY",
      "city": "New York",
      "postal_code": "10001",
      "street_address": "500 Market St"
    }
  }'
```

The response includes an `id`. This is the BPO enterprise's id, used as `bpo_enterprise_id` in step 6.

Use a mailbox the call center controls for the `organization_contact` email. That is the address verified in the next step, and the BPO enterprise cannot be approved until it is verified.

## Step 2: Verify the BPO's contact email

Before Telnyx can approve the BPO enterprise, the call center has to prove it owns the contact email on it (in the example, Alex Rivera's address at Dial Partners). It asks Telnyx to email a 6-digit code, then sends the code back to confirm. Because a BPO enterprise has no DIR of its own, this happens on the enterprise rather than on a DIR. Use the BPO enterprise's `id` as `{enterprise_id}`.

```bash
# Request a verification code, sent to the BPO enterprise's organization_contact.email.
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/verify_email \
  -H "Authorization: Bearer YOUR_API_KEY"

# Confirm the code from the email.
curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/verify_email/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'
```

Both calls return where the email verification currently stands, so you can see whether the email is now verified. A code is only good for 15 minutes, and asking for a new one voids the old one. If a code is wrong, expired, or already used, you get back the same generic failure either way, so a rejection never tells an attacker which of those it was.

## Step 3: Enable Branded Calling on the BPO enterprise

Branded Calling must be explicitly enabled on the BPO enterprise, just as it is on a client enterprise. The call center is registered for branded calling once its BPO enterprise is both enabled and approved (step 4), in either order.

Before you call it:

- **Accept the Branded Calling Terms of Service** on your account (`POST /v2/terms_of_service/branded_calling/agree`, see [Quickstart step 1](/docs/branded-calling/quickstart#step-1-accept-the-branded-calling-terms-of-service)). Without it, this call returns `403`.
- **The BPO enterprise must be in the US** (`"country_code": "US"`). Branded Calling is US-only; any other country returns `400`.

**Do not skip it.** If you skip this step, any client DIR linked to this BPO enterprise is held back even after it shows `verified`. None of that client's calls show its brand until you enable Branded Calling here, and no error tells you why.

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

The response comes back immediately. Registration of the call center starts only once the BPO enterprise is also approved, so nothing may happen until step 4 is done. The call is idempotent, so it is safe to retry.

Enabling Branded Calling on a BPO enterprise is **free**. Your account must have available credit, or the request is rejected with `400`. The fees that apply are on each client's DIR ($50 one-time plus $50/month per DIR). See [Branded Calling pricing](/docs/branded-calling/pricing).

Reading the BPO enterprise and checking that `branded_calling_enabled` is `true` confirms the enable step only; it does not show that registration has finished. Do both this step and step 4 before you rely on the BPO for live calls.

## Step 4: Telnyx approves the BPO enterprise

Telnyx reviews the BPO enterprise and moves its status from `pending` to `approved` or `rejected`. The email has to be verified before approval goes through, so don't expect a decision until that step is done.

Check where the review stands by reading the BPO enterprise. Its `bpo_verification_status` field is `pending`, `approved`, or `rejected` (it is `null` on normal enterprises):

```bash
curl https://api.telnyx.com/v2/enterprises/{bpo_enterprise_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To find your BPO enterprise among all the enterprises in your account (for example, to look up its `id`), filter the list by type:

```bash
curl "https://api.telnyx.com/v2/enterprises?filter[role_type]=bpo" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Only an `approved` BPO can be authorized on a DIR. If Telnyx later rejects a BPO, every authorization it held is set to `rejected`. Those entries stay in each DIR's authorization list, with a `rejection_reason`, but no longer take effect.

**Editing an approved BPO enterprise resets it.** If you change any identity detail on an approved BPO enterprise (legal name, DBA, website, FEIN, industry, number of employees, physical address, organization contact including its email or phone, D-U-N-S number, legal type, SIC code, corporate registration or professional license number, or jurisdiction), it goes back to `pending` for re-approval. At the same moment, every DIR authorization for that BPO is set to `rejected`.

To recover:
1. If you changed the contact email, verify it again (step 2).
2. Wait for Telnyx to re-approve the BPO enterprise.
3. For each client DIR, generate a new LOA, have the client sign it, upload it, and send it in `bpo_authorizations` with the **new** `loa_document_id`. Resending the old one keeps the authorization `rejected`.

Re-sending a value that is unchanged does not reset anything. If Number Reputation is turned on for the enterprise, most of these fields (legal name, DBA, website, FEIN, industry, number of employees, physical address, organization contact, D-U-N-S number) cannot be edited at all: the update is rejected with `400`, and nothing is reset.

## Step 5: Create the client's enterprise and DIR

Create the client's enterprise and DIR the same way you would for any brand, following the [Quickstart](/docs/branded-calling/quickstart) (activate Branded Calling on the enterprise, then create the DIR). The only difference is whose data you enter: **the client's**.

**Create the DIR, but do not submit it yet.** Link the BPO enterprise first (step 6), then submit (step 7). A DIR that is `submitted` or `in_review` cannot be edited, so if you submit first, you cannot add the link until vetting finishes, and the link then needs its own separate review.

The client enterprise is a normal enterprise. Leave `role_type` out (it defaults to `enterprise`). In the example, it describes Maple Ridge:

```bash
# The client enterprise: Maple Ridge's own details, not Dial Partners'.
curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Maple Ridge Insurance Inc.",
    "doing_business_as": "Maple Ridge Insurance",
    "organization_type": "commercial",
    "organization_legal_type": "corporation",
    "country_code": "US",
    "jurisdiction_of_incorporation": "Illinois",
    "website": "https://mapleridge.example.com",
    "fein": "36-4829105",
    "industry": "insurance",
    "number_of_employees": "201-500",
    "organization_contact": {
      "first_name": "Jordan",
      "last_name": "Lee",
      "email": "jordan.lee@mapleridge.example.com",
      "job_title": "Director of Customer Operations",
      "phone_number": "+13125550100"
    },
    "billing_contact": {
      "first_name": "Jordan",
      "last_name": "Lee",
      "email": "billing@mapleridge.example.com",
      "phone_number": "+13125550100"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "200 Lakeview Ave"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "200 Lakeview Ave"
    }
  }'
```

Then create the DIR under the **client** enterprise's `id` (not the BPO enterprise's). The DIR describes the brand the called person sees, so the display name, logo, call reasons, and authorizer are all Maple Ridge's:

```bash
# The DIR goes under Maple Ridge's enterprise id.
curl -X POST https://api.telnyx.com/v2/enterprises/{client_enterprise_id}/dir \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Maple Ridge Insurance",
    "authorizer_name": "Jordan Lee",
    "authorizer_email": "jordan.lee@mapleridge.example.com",
    "call_reasons": ["Policy renewal", "Claim follow-up"],
    "logo_url": "https://mapleridge.example.com/logo.bmp",
    "certify_brand_is_accurate": true,
    "certify_no_shaft_content": true,
    "certify_ip_ownership": true
  }'
```

See [Display Identity Records (DIRs)](/docs/branded-calling/brands) for every DIR field.

## Step 6: Link the DIR to the BPO enterprise

Once the BPO enterprise is approved, link the client's DIR to it. There are two parts: get the LOA signed, then list the BPO enterprise on the DIR.

Have two things ready before you start. The BPO enterprise has to be `approved` already; linking one that isn't an approved BPO enterprise in your account is rejected with `400`. And the signed LOA has to be uploaded to the [Telnyx Documents API](/api-reference/documents/upload-a-document) so you have its `document_id` on hand.

### Generate and sign the authorization LOA

The Letter of Authorization is the brand owner's written permission for the call center to place calls under its brand. It is generated from your account, but it is **signed by the brand owner**, not by the call center: in the example, Maple Ridge's organization contact (the contact on the Maple Ridge enterprise) is named on it as the authorizing representative and signs it. You then upload the signed letter to your own account.

Generate a pre-filled BPO Authorization LOA for the brand owner's DIR. It is filled in from the two enterprises you created: Maple Ridge as the brand owner, Dial Partners as the BPO. Leave `signature` out to get an unsigned PDF: send it to the client to sign, then upload the signed copy. Or, if the client has given you their drawn signature, include it to embed it directly. Either way the signature must be the client's (Maple Ridge's), never the call center's:

```bash
curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/bpo_loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bpo_enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6" }'
```

- `bpo_enterprise_id`: the `id` of your approved BPO enterprise (from step 1).
- `signature`: optional. An object with `image_base64` (the raw base64 of a PNG image, with no `data:` prefix) and an optional `signer_name`. Include it to embed the client's signature in the letter, or omit `signature` entirely to get an unsigned letter for the client to sign.

The response is the LOA PDF. Have the client sign it, then upload it to the [Telnyx Documents API](/api-reference/documents/upload-a-document), and hold onto the `document_id` it gives back. That is the `loa_document_id` you pass in the next step.

### Link the DIR to the BPO enterprise

List the BPO enterprise, with the signed LOA document, in the `bpo_authorizations` array of the brand owner's DIR. You can do this when you create the DIR or later with an update:

```bash
curl -X PATCH https://api.telnyx.com/v2/dir/{dir_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bpo_authorizations": [
      {
        "bpo_enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
        "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
      }
    ]
  }'
```

Each entry pairs a BPO (`bpo_enterprise_id`) with its signed LOA (`loa_document_id`). The array holds up to 10 authorizations.

The `bpo_authorizations` array **replaces** the DIR's current list on every create or update. To keep an existing authorization, include it again with the same `loa_document_id` (read it from the [authorizations list](#read-back-a-dirs-authorizations)); it then keeps its current review status, so an approved link stays approved. To remove one, leave it out. Leave out any entry whose BPO enterprise is no longer `approved`: including it rejects the whole update with `400`. Sending an empty array (`[]`) clears all authorizations. Omitting the field leaves the list unchanged. Editing this list does not re-vet the DIR itself.

You can change a DIR's authorizations only while the DIR is in an editable status (for example `draft`, `verified`, `rejected`, `suspended`, or `unsuccessful`). While the DIR is being reviewed, the update is rejected; wait until review finishes.

## Step 7: Submit the DIR, then add phone numbers

Once the link is in place, submit the client's DIR:

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

Telnyx reviews the DIR and its pending link together: when the DIR is approved, its pending authorizations are approved with it. After the DIR is `verified`, add the phone numbers that should display the client's brand, as described in [Phone Numbers](/docs/branded-calling/bc-phone-numbers). Adding numbers needs its own signed Letter of Authorization: generate it with `POST /v2/dir/{dir_id}/loa`, passing your call center's details in `agent`. It is filled in from the client's enterprise, so the **client's contact** signs it, not you.

### How links are reviewed

A new authorization starts in `pending`. Telnyx reviews it and moves it to `approved` or `rejected`. Only an `approved` authorization takes effect. Sending a different `loa_document_id` for a BPO (a newly signed and uploaded LOA) sends that authorization back to `pending` for another review. Uploading a document on its own changes nothing until you send its id in `bpo_authorizations`.

If you add or change a link on a DIR that is already `verified`, that link is reviewed on its own, and the DIR stays `verified` meanwhile.

## Read back a DIR's authorizations

Check a DIR's authorized BPOs and their review status at any time:

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

Each returned authorization shows the BPO enterprise it belongs to (`bpo_enterprise_id`), the signed LOA you submitted (`loa_document_id`), its current status (`pending`, `approved`, or `rejected`), and, when rejected, a `rejection_reason`.

## What the link does

An approved link adds the call center to the client DIR's list of authorized callers in the branded calling registry. It applies to that one DIR only. It does not change or merge the records: the BPO enterprise still describes the call center, and the client enterprise and DIR still describe the client.

## Stop working with a BPO

To stop a DIR's calls going through the BPO, update the DIR with a `bpo_authorizations` array that leaves that BPO out. Because the list replaces on every update, the omitted authorization is removed. Sending `[]` removes all of them.

## What's next

- [Quickstart guide](/docs/branded-calling/quickstart), the end-to-end Branded Calling flow.
- [Display Identity Records (DIRs)](/docs/branded-calling/brands), full DIR lifecycle, statuses, editing, deletion.
- [Enterprises](/docs/branded-calling/enterprises), the required fields for any enterprise, including a BPO enterprise and the brand owner's enterprise.

---

### 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](/api-reference/documents/upload-a-document) first and reference the returned `id` as a `document_id`.

Adding phone numbers is **free**. The Branded Calling fees are charged per DIR and per branded call. See [Branded Calling pricing](/docs/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 |

## 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`.

```bash
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](/api-reference/documents/upload-a-document) 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](/api-reference/documents/upload-a-document):

```bash
# 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`:

```bash
# 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.

```bash
# 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

```bash
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

```bash
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`).

```bash
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:

```bash
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](https://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

```bash
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

```bash
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.

For infringement issues, please mail [brand-infringement@telnyx.com](mailto:brand-infringement@telnyx.com).

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

```bash
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

```bash
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.

```bash
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](/api-reference/documents/upload-a-document) 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).

```bash
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](/api-reference/documents/upload-a-document) plus a `document_type`, and re-attaching a document already on the DIR is rejected. See the [Infringement Claims guide](/docs/branded-calling/infringement-claims) 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](https://developers.telnyx.com/api-reference/enterprises/list-enterprises.md): Return the enterprises you own, paginated. The default page size is 20; the maximum is 250.
- [Create an enterprise](https://developers.telnyx.com/api-reference/enterprises/create-an-enterprise.md): Create the legal entity (enterprise) that represents your business on the Telnyx platform.
- [Delete an enterprise](https://developers.telnyx.com/api-reference/enterprises/delete-an-enterprise.md): Soft-delete an enterprise.
- [Get an enterprise](https://developers.telnyx.com/api-reference/enterprises/get-an-enterprise.md): Retrieve a single enterprise by id. Returns `404` if the id does not exist or does not belong to your account.
- [Replace an enterprise](https://developers.telnyx.com/api-reference/enterprises/replace-an-enterprise.md): Replace the enterprise's mutable fields. Only mutable fields may be sent. Server-assigned and immutable fields (`id`, `record_type`, `created_at`, `updated_at`…
- [Activate Branded Calling on an enterprise](https://developers.telnyx.com/api-reference/enterprises/activate-branded-calling-on-an-enterprise.md): Branded Calling must be activated on each enterprise. Activation is idempotent:

### Email Verification

- [Send an email-ownership verification code to an enterprise](https://developers.telnyx.com/api-reference/email-verification/send-an-email-ownership-verification-code-to-an-enterprise.md): Email a 6-digit code to the enterprise account's contact email to confirm ownership of that address.
- [Confirm an enterprise email-ownership verification code](https://developers.telnyx.com/api-reference/email-verification/confirm-an-enterprise-email-ownership-verification-code.md): Submit the 6-digit code that was emailed to the enterprise account's contact email. On success the contact email is marked verified.
- [Send an email-ownership verification code](https://developers.telnyx.com/api-reference/email-verification/send-an-email-ownership-verification-code.md): Email a 6-digit code to the DIR's authorizer email to confirm ownership of that address.
- [Confirm an email-ownership verification code](https://developers.telnyx.com/api-reference/email-verification/confirm-an-email-ownership-verification-code.md): Submit the 6-digit code that was emailed to the DIR's authorizer email. On success the authorizer email is marked verified.
- [Get email-ownership verification status](https://developers.telnyx.com/api-reference/email-verification/get-email-ownership-verification-status.md): Whether the DIR's current authorizer email has been verified.

### Display Identity Records

- [List DIRs in an enterprise](https://developers.telnyx.com/api-reference/display-identity-records/list-dirs-in-an-enterprise.md): 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)](https://developers.telnyx.com/api-reference/display-identity-records/create-a-display-identity-record-dir.md): 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](https://developers.telnyx.com/api-reference/display-identity-records/list-all-dirs-across-your-enterprises.md): 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…
- [Request deletion of a DIR](https://developers.telnyx.com/api-reference/display-identity-records/request-deletion-of-a-dir.md): Request deletion of a DIR. This does not remove the DIR on this call: it records the request, moves the DIR to `delete_requested`, and Telnyx completes the rem…
- [Get a DIR by id](https://developers.telnyx.com/api-reference/display-identity-records/get-a-dir-by-id.md): 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](https://developers.telnyx.com/api-reference/display-identity-records/update-a-dir.md): 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…
- [Submit a DIR for vetting](https://developers.telnyx.com/api-reference/display-identity-records/submit-a-dir-for-vetting.md): 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](https://developers.telnyx.com/api-reference/display-identity-records/render-the-branded-calling-loa-for-a-dir.md): 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…
- [Render the BPO Authorization LOA for a DIR](https://developers.telnyx.com/api-reference/display-identity-records/render-the-bpo-authorization-loa-for-a-dir.md): The Letter of Authorization in which a Brand Owner authorizes an approved BPO (Business Process Outsourcer) to place branded calls that display this DIR on the…
- [List a DIR's authorized BPOs](https://developers.telnyx.com/api-reference/display-identity-records/list-a-dirs-authorized-bpos.md): List the BPO (Business Process Outsourcer) accounts a Brand Owner has authorized on this DIR, together with the review state of each authorization.

### DIR References

- [List a DIR's references](https://developers.telnyx.com/api-reference/dir-references/list-a-dirs-references.md): List the business and financial references submitted for a DIR.
- [Submit a DIR's references](https://developers.telnyx.com/api-reference/dir-references/submit-a-dirs-references.md): Submit the two business references and one financial reference for a DIR.
- [Update a DIR reference](https://developers.telnyx.com/api-reference/dir-references/update-a-dir-reference.md): Partially update one reference, addressed by the DIR id plus the reference's type (business or financial) and slot.

### Reference Data

- [List supported DIR document types](https://developers.telnyx.com/api-reference/reference-data/list-supported-dir-document-types.md): 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](https://developers.telnyx.com/api-reference/reference-data/list-standard-call-reasons.md): 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](https://developers.telnyx.com/api-reference/reference-data/validate-a-list-of-call-reasons.md): 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](https://developers.telnyx.com/api-reference/comments/list-comments-on-a-dir.md): List the comments on a DIR. The enterprise is resolved server-side from the DIR id.
- [Post a comment on a DIR](https://developers.telnyx.com/api-reference/comments/post-a-comment-on-a-dir.md): 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

- [Remove phone numbers from a DIR](https://developers.telnyx.com/api-reference/phone-numbers/remove-phone-numbers-from-a-dir.md): Deregister phone numbers from a DIR. The enterprise is resolved server-side from the DIR id. Returns a partial-success envelope.
- [List phone numbers attached to a DIR](https://developers.telnyx.com/api-reference/phone-numbers/list-phone-numbers-attached-to-a-dir.md): List the phone numbers registered under a DIR. The enterprise is resolved server-side from the DIR id.
- [Add phone numbers to a DIR](https://developers.telnyx.com/api-reference/phone-numbers/add-phone-numbers-to-a-dir.md): Register phone numbers under a DIR. The enterprise is resolved server-side from the DIR id.

### Phone Number Batches

- [List phone-number batches for a DIR](https://developers.telnyx.com/api-reference/phone-number-batches/list-phone-number-batches-for-a-dir.md): List the phone-number batches submitted under a DIR. The enterprise is resolved server-side from the DIR id.
- [Get a phone-number batch](https://developers.telnyx.com/api-reference/phone-number-batches/get-a-phone-number-batch.md): 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](https://developers.telnyx.com/api-reference/infringement-claims/list-infringement-claims-for-a-dir.md): 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](https://developers.telnyx.com/api-reference/infringement-claims/update-a-dir-to-resolve-an-infringement-concern.md): 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](https://developers.telnyx.com/api-reference/infringement-claims/get-an-infringement-claim.md): 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](https://developers.telnyx.com/api-reference/infringement-claims/contest-an-infringement-claim.md): 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](https://developers.telnyx.com/api-reference/terms-of-service/agree-to-the-branded-calling-terms-of-service.md): 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](https://developers.telnyx.com/api-reference/terms-of-service/get-terms-of-service-information.md): 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](https://developers.telnyx.com/api-reference/terms-of-service/get-the-calling-users-terms-of-service-status.md): 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](https://developers.telnyx.com/api-reference/terms-of-service/list-the-calling-users-terms-of-service-agreements.md): 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](https://developers.telnyx.com/api-reference/terms-of-service/get-a-terms-of-service-agreement-by-id.md): Retrieve a single ToS agreement record. Returns `404` if the agreement does not exist or does not belong to the authenticated user.