> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Display Identity Records > 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 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 theme={null} 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 theme={null} curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/submit \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Deleting a DIR ```bash theme={null} 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.