---
title: "Create a Display Identity Record (DIR)"
method: POST
path: "/enterprises/{enterprise_id}/dir"
tags: ["Display Identity Records"]
---

# Create a Display Identity Record (DIR)

`POST /enterprises/{enterprise_id}/dir`

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 number can be attached.

**Field rules**
- `display_name`: 1–35 characters, no emoji or whitespace-only strings; this is the name shown to recipients.
- `call_reasons`: 1–10 strings, each ≤64 characters; describe why your business calls customers (e.g. 'Appointment reminders', 'Billing inquiries'). Validate the wording against `POST /call_reasons/validate`.
- `logo_url`: HTTPS URL (max 128 chars) to a 256×256 BMP (max 1 MB). The image is downloaded and hashed at submission time.
- `documents`: up to 20 entries; each `document_id` must be obtained by uploading the file via the Telnyx Documents API first. Within one DIR a `document_id` may only appear once.
- `certify_brand_is_accurate`, `certify_no_shaft_content`, `certify_ip_ownership` MUST all be `true`.

**Failure modes**
- `422` - validation error; `errors[].source.pointer` names the offending field.
- `403` - Branded Calling not activated on this enterprise (see `POST /enterprises/{id}/branded_calling`).
- `404` - enterprise does not exist or does not belong to your account.

## Path parameters

- `enterprise_id` string, uuid, required

## Request body

- DirCreateRequest
  - `authorizer_email` string, email, required — Contact email of the authorizer. Telnyx may send verification or infringement-notice email here; use a monitored mailbox.
  - `authorizer_name` string, required — Name of the person at your enterprise who is authorizing this DIR registration. Must be a real individual (used for audit and trademark-claim contests).
  - `call_reasons` string[], required — 1–10 reasons your business calls customers. Validate phrasing against `POST /call_reasons/validate`.
  - `certify_brand_is_accurate` true, required — Must be `true`.
  - `certify_ip_ownership` true, required — Must be `true`. Confirms ownership of any logos/trademarks shown.
  - `certify_no_shaft_content` true, required — Must be `true`. Confirms this DIR is not used for SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) where prohibited.
  - `display_name` string, required — Name shown to call recipients. No emoji; not whitespace-only.
  - `documents` Document[] — Supporting documents. Each `document_id` may appear at most once on a DIR.
    - `description` string
    - `document_id` string, uuid, required — Id returned by the Telnyx Documents API after you upload the file (upload via `POST /v2/documents`; see https://developers.telnyx.com/api/documents).
    - `document_type` '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', required — Type of supporting document. Pick the closest match to what the file actually contains; `other` triggers manual vetting and may slow approval. The matching short_name reference list is at `GET /v2/dir/document_types`.
  - `logo_url` string, uri — Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB).
  - `reselling` boolean — Set to true if your organization places calls on behalf of other enterprises (BPO/reseller).

## Response `201`

DIR created in `draft` status.

- DirWrapped
  - `data` Dir, required
    - `authorizer_email` string, email, nullable
    - `authorizer_name` string, nullable
    - `call_reasons` CallReason[]
      - `created_at` string, date-time
      - `reason` string
    - `certify_brand_is_accurate` boolean
    - `certify_ip_ownership` boolean
    - `certify_no_shaft_content` boolean
    - `created_at` string, date-time
    - `display_name` string
    - `documents` Document[], nullable
      - `description` string
      - `document_id` string, uuid, required — Id returned by the Telnyx Documents API after you upload the file (upload via `POST /v2/documents`; see https://developers.telnyx.com/api/documents).
      - `document_type` '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', required — Type of supporting document. Pick the closest match to what the file actually contains; `other` triggers manual vetting and may slow approval. The matching short_name reference list is at `GET /v2/dir/document_types`.
    - `enterprise_id` string, uuid
    - `expiring_at` string, date-time, nullable
    - `id` string, uuid
    - `logo_url` string, uri, nullable
    - `rejected_at` string, date-time, nullable
    - `rejection_reasons` RejectionReason[], nullable — Populated when `status` is `rejected`; cleared on `/submit` or successful approval.
      - `code` string
      - `detail` string
      - `message` string, nullable — Customer-visible free-text comment from the Telnyx vetting team. Only the first entry of `rejection_reasons` carries this; the rest are `null`.
      - `title` string
    - `reselling` boolean
    - `status` 'draft' | 'submitted' | 'in_review' | 'verified' | 'rejected' | 'unsuccessful' | 'suspended' | 'expired' | 'infringement_claimed' | 'permanently_rejected' — DIR lifecycle status. - `draft` - newly created; editable; not yet submitted. - `submitted` / `in_review` - Telnyx is reviewing. - `verified` - approved; phone numbers may be attached. - `rejected` - Telnyx rejected this submission; `rejection_reasons` is populated; customer can edit and resubmit. - `unsuccessful` - system-side error during processing; customer can edit and resubmit. - `suspended` - temporarily disabled (e.g. by an active infringement claim). - `expired` - verification expired; customer must resubmit. - `infringement_claimed` - a trademark/impersonation claim is open against this DIR. - `permanently_rejected` - terminal; cannot be resubmitted.
    - `submitted_at` string, date-time, nullable
    - `updated_at` string, date-time
    - `verified_at` string, date-time, nullable

## Other responses

- `4XX` — An error occurred. The response carries the standard Telnyx error envelope.
- `default` — An error occurred. The response carries the standard Telnyx error envelope.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)