Display Identity Records

Overview

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

Prerequisites

Before creating a DIR:

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

API endpoints

Method	Path	Description
`POST`	`/v2/enterprises/{enterprise_id}/dir`	Create a new DIR under an enterprise
`GET`	`/v2/dir`	List DIRs across the account
`GET`	`/v2/enterprises/{enterprise_id}/dir`	List DIRs under one enterprise
`GET`	`/v2/dir/{dir_id}`	Get a DIR
`PATCH`	`/v2/dir/{dir_id}`	Update a DIR
`DELETE`	`/v2/dir/{dir_id}`	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.
`reselling`	boolean	`true` if you resell calling services on behalf of others. Defaults to `false`.

Logo requirements

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

Document types

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

Display Identity Record statuses

Status	Meaning
`draft`	Initial state. You’re still preparing the DIR. Editable.
`submitted`	Vetting requested. Editing 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

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

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

For draft / rejected / unsuccessful, PATCH is a pure edit. The status doesn’t change. Call POST /submit to re-vet when ready.
suspended means an infringement claim is attached. PATCH itself is allowed and leaves the status unchanged, but POST /submit is blocked with a 409 while the claim is still pending or contested (the no_active_claims gate). To revise content and re-vet during an open claim, use PUT /v2/dir/{dir_id}/infringement_update instead - see Infringement Claims. The plain PATCH + POST /submit flow only works once the claim is resolved (e.g. resolution = modified, which leaves the DIR suspended with the claim closed).
For verified, a PATCH that actually changes a field flips the DIR back to draft. 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. Read both. Fix the issues with PATCH, then submit again:

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

Deleting a DIR

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

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.

{ "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 the claim, Telnyx adjudicates resolution.

​Overview

​Prerequisites

​API endpoints

​Required fields

​Optional fields

​Logo requirements

​Document types

​Display Identity Record statuses

​Updating a DIR

​Resubmitting after rejection

​Deleting a DIR

Overview

Prerequisites

API endpoints

Required fields

Optional fields

Logo requirements

Document types

Display Identity Record statuses

Updating a DIR

Resubmitting after rejection

Deleting a DIR