# 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://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/calling/trusted-calling.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. 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).

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

| Without Branded Calling | With Branded Calling |
| :--- | :--- |
| +1 (555) 123-4567 | **Acme Healthcare** |
| *or "Spam Likely"* | 🏥 Company Logo |
| | "Appointment Reminder" |

This increases answer rates and builds trust with your customers.

## 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
- [Display Identity Records](/docs/branded-calling/brands/index), create and manage display identities
- [Phone Numbers](/docs/branded-calling/bc-phone-numbers/index), associate numbers with DIRs
- [Call Reasons](/docs/branded-calling/call-reasons/index), configure what recipients see
- [Infringement Claims](/docs/branded-calling/infringement-claims/index), 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/index) 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/index).

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

```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 on an enterprise is **billable**. See [Telnyx pricing](https://telnyx.com/pricing/numbers).

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

## 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 **billable**. See [Telnyx pricing](https://telnyx.com/pricing/numbers).

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/index) 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/index), full DIR lifecycle, statuses, editing, deletion.
- [Phone Numbers](/docs/branded-calling/bc-phone-numbers/index), adding/removing numbers and inspecting batches.
- [Call Reasons](/docs/branded-calling/call-reasons/index), the pre-approved list and the validator.
- [Infringement Claims](/docs/branded-calling/infringement-claims/index), what to do if a claim is filed against your DIR.

---

### 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. Currently `US` and `CA` are supported. |
| `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.

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

```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 **billable**. See [Telnyx pricing](https://telnyx.com/pricing/numbers).

### 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/index) 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}` | 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](/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, 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

```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/index#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` 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](/docs/branded-calling/brands/index). 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"
```

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](/docs/branded-calling/infringement-claims/index) 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](/api-reference/documents/upload-a-document) first and reference the returned `id` as a `document_id`.

Adding phone numbers is **billable**. See [Telnyx pricing](https://telnyx.com/pricing/numbers).

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

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

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."
  }'
```

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. See the [Infringement Claims guide](/docs/branded-calling/infringement-claims/index) 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.
- [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`…
- [Delete an enterprise](https://developers.telnyx.com/api-reference/enterprises/delete-an-enterprise.md): Soft-delete an enterprise.
- [Activate Branded Calling on an enterprise](https://developers.telnyx.com/api-reference/enterprises/activate-branded-calling-on-an-enterprise.md): Branded Calling is a paid product that must be activated on each enterprise. Activation is idempotent:

### 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…
- [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…
- [Delete a DIR](https://developers.telnyx.com/api-reference/display-identity-records/delete-a-dir.md): 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](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…

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

- [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. Same body, failure modes, and batch semantics whichever path form y…
- [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.

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