Create and manage Display Identity Records (DIRs)

Create and manage Display Identity Records (DIRs), the display identity shown to call recipients.

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 takes effect immediately.

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}/verify_email	Send (or resend) the authorizer email verification code
POST	/v2/dir/{dir_id}/verify_email/confirm	Confirm the code
GET	/v2/dir/{dir_id}/verify_email	Get the email verification status
POST	/v2/dir/{dir_id}/references	Submit references (only when required)
GET	/v2/dir/{dir_id}/references	List submitted references
POST	/v2/dir/{dir_id}/submit	Submit for vetting

Setting up a DIR, in order

1. Create the DIR. It starts in draft. If you’re a call center, attach your call center here (see the note below).
2. Verify the authorizer email. Telnyx emails a 6-digit code to the DIR’s authorizer_email. Send it back to confirm. Details
3. Submit references, if your documents are not enough. References (two business references and one financial reference) are needed only if the DIR’s documents don’t already prove the business is legitimate and financially stable. Audited or certified financial statements, or a commercial credit report, can prove that instead. Telnyx reviewers decide during vetting whether your documents are enough. Details
4. Submit the DIR for vetting (POST /v2/dir/{dir_id}/submit).

If you’re a call center (BPO) setting up a DIR for a client, attach your call center before step 2. Send bpo_authorizations when you create the DIR, or add it with PATCH /v2/dir/{dir_id} while the DIR is a draft. This needs your approved call-center enterprise on the same account and the client’s signed letter of authorization uploaded to the Documents API. The verification code then lasts 8 hours instead of 15 minutes, which gives the client’s authorizer time to pass it back to you. See Branded Calling for call centers (BPOs).

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.
bpo_authorizations	array	Call centers (BPOs) allowed to call under this brand, each with a signed letter of authorization. See Branded Calling for call centers (BPOs).

Verify the authorizer email

Request a code. Telnyx emails it to the DIR’s authorizer_email:

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

Confirm it:

curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/verify_email/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "482915"}'

• Who gets the code. Only the authorizer email. If the authorizer is someone else (for example a client’s executive), that person has to share the code with whoever is completing setup, before it expires.
• How long it lasts. 15 minutes by default. 8 hours when the DIR has a call center linked through bpo_authorizations and that authorization is pending review or approved (a rejected one does not count). The call center must be linked before you send the code. A code sent before linking keeps 15 minutes; send a new one after linking to get 8 hours. The email states the window, and expires_at in the send response shows the exact expiry.
• Resending. Call the send endpoint again. Each send issues a fresh code, and the previous code stops working. Limits: one send every 60 seconds, and 10 sends per DIR per UTC day. A throttled send returns 429 with retry_after_secs (seconds to wait) and sends_remaining_today in the error meta.
• A failed confirm (wrong, expired, or already-used code) returns the same generic error every time. Request a new code and try again.

Check the current state with GET /v2/dir/{dir_id}/verify_email.

References

References are needed only if the documents uploaded with the DIR don’t already prove the business is legitimate and financially stable. Any one of these is enough proof:

• Audited or certified financial statements, uploaded as other with a description.
• A commercial credit report, uploaded as business_credit_report.
• References: two business references and one financial reference.

Telnyx reviewers decide during vetting whether your documents are enough. If they aren’t, submit references. References can’t be changed while the DIR is verified. Update the DIR first, which returns it to draft.

Send references with POST /v2/dir/{dir_id}/references. Upload documents with the DIR, in the documents field (see Document types).

Who qualifies:

• Business references (2): a senior contact at an organization the business works with, such as a vendor, partner, or client. For example a C-suite executive, an owner or founder, or a senior manager or director.
• Financial reference (1): a licensed CPA the business uses, a contact at a bank or financial institution the business works with, or a reasonable alternative banking or financial reference.

Each reference needs full_name, phone_e164, email, and timezone. See the Quickstart for a full request.

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, certificate_of_good_standing, business_credit_report, bank_reference_letter, other

• certificate_of_good_standing: a state-issued certificate of good standing (also called a certificate of existence or status) showing the business is active and compliant.
• business_credit_report: a business credit report from a recognized bureau (for example Dun & Bradstreet, Experian Business, or Equifax Business).
• bank_reference_letter: a signed letter from the business’s bank confirming an active account in good standing.
• other: anything that fits no other type, such as audited or certified financial statements. Say what it is in description.

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 POST /submit is blocked (400). 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 400 while the claim is still pending or contested (“DIR has N active infringement claim(s). Resolve the claim before making this change.”). 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.