> ## 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. # List all DIRs across your enterprises > 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]`, max 250). Supports `filter[]` query params: `filter[enterprise_id]`, `filter[status]`, `filter[display_name][contains]`, `filter[call_reason][contains]`, plus the renewal-window filters `filter[expiring_at][gte]` / `filter[expiring_at][lte]`. Sortable by `created_at`, `updated_at`, `display_name`, `status` (prefix `-` for descending; default `-created_at`). ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/branded-calling/dirs.yml get /dir openapi: 3.1.0 info: title: Telnyx Branded Calling Display Identity Records API version: 2.0.0 description: >- Create and manage Display Identity Records (DIRs) — your branded caller identity — and submit them for vetting. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] paths: /dir: get: tags: - Display Identity Records summary: List all DIRs across your enterprises description: >- 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]`, max 250). Supports `filter[]` query params: `filter[enterprise_id]`, `filter[status]`, `filter[display_name][contains]`, `filter[call_reason][contains]`, plus the renewal-window filters `filter[expiring_at][gte]` / `filter[expiring_at][lte]`. Sortable by `created_at`, `updated_at`, `display_name`, `status` (prefix `-` for descending; default `-created_at`). operationId: listAllDirs parameters: - $ref: '#/components/parameters/BcPageNumber' - $ref: '#/components/parameters/BcPageSize' - name: sort in: query required: false description: >- Sort field. Allowed values: `created_at`, `updated_at`, `display_name`, `status`. Prefix with `-` for descending. Default `-created_at`. schema: type: string default: '-created_at' enum: - created_at - '-created_at' - updated_at - '-updated_at' - display_name - '-display_name' - status - '-status' - name: filter[expiring_at][gte] in: query required: false description: >- Return only DIRs whose `expiring_at` is at or after this ISO-8601 timestamp. Pairs with the `[lte]` variant to build renewal-window dashboards. schema: type: string format: date-time - name: filter[expiring_at][lte] in: query required: false description: >- Return only DIRs whose `expiring_at` is at or before this ISO-8601 timestamp. schema: type: string format: date-time - name: filter[enterprise_id] in: query required: false description: Filter by enterprise ID. schema: type: string format: uuid - name: filter[status] in: query required: false description: Filter by DIR status. schema: $ref: '#/components/schemas/DirStatus' - name: filter[display_name][contains] in: query required: false description: Case-insensitive partial match on display name. schema: type: string - name: filter[call_reason][contains] in: query required: false description: Case-insensitive partial match on call reason. schema: type: string responses: '200': description: Paginated list of DIRs across all your enterprises. content: application/json: schema: $ref: '#/components/schemas/DirList' default: $ref: '#/components/responses/branded-calling_GenericErrorResponse' 4XX: $ref: '#/components/responses/branded-calling_GenericErrorResponse' x-codeSamples: - lang: JavaScript source: |- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const dirListResponse of client.dir.list()) { console.log(dirListResponse.id); } - lang: Python source: |- import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) page = client.dir.list() page = page.data[0] print(page.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Dir.List(context.TODO(), telnyx.DirListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.dir.DirListPage; import com.telnyx.sdk.models.dir.DirListParams; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); DirListPage page = client.dir().list(); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") page = telnyx.dir.list puts(page) - lang: PHP source: >- dir->list( filterCallReasonContains: 'filter[call_reason][contains]', filterDisplayNameContains: 'filter[display_name][contains]', filterEnterpriseID: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', filterExpiringAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), filterExpiringAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), filterStatus: 'draft', pageNumber: 1, pageSize: 20, sort: 'created_at', ); var_dump($page); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx dir list \ --api-key 'My API Key' components: parameters: BcPageNumber: name: page[number] in: query description: >- 1-based page number. Out-of-range values return an empty page with correct meta. required: false schema: type: integer minimum: 1 default: 1 example: 1 BcPageSize: name: page[size] in: query description: Items per page. Maximum 250; values above are clamped to 250. required: false schema: type: integer minimum: 1 maximum: 250 default: 20 example: 20 schemas: DirStatus: type: string enum: - draft - submitted - in_review - verified - rejected - unsuccessful - suspended - expired - infringement_claimed - permanently_rejected description: >- 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. DirList: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/Dir' meta: $ref: '#/components/schemas/branded-calling_PaginationMeta' Dir: type: object properties: id: type: string format: uuid example: 16635d38-75a6-4481-82e8-69af60e05011 readOnly: true enterprise_id: type: string format: uuid example: 4a6192a4-573d-446d-b3ce-aff9117272a6 display_name: type: string example: Acme Plumbing reselling: type: boolean example: false certify_brand_is_accurate: type: boolean example: true certify_no_shaft_content: type: boolean example: true certify_ip_ownership: type: boolean example: true authorizer_name: type: string nullable: true example: Sam Owner authorizer_email: type: string format: email nullable: true example: sam@acmeplumbing.example.com logo_url: type: string format: uri nullable: true example: https://acmeplumbing.example.com/logo-256.bmp call_reasons: type: array items: $ref: '#/components/schemas/CallReason' documents: type: array items: $ref: '#/components/schemas/Document' nullable: true status: $ref: '#/components/schemas/DirStatus' rejection_reasons: type: array items: $ref: '#/components/schemas/RejectionReason' nullable: true description: >- Populated when `status` is `rejected`; cleared on `/submit` or successful approval. rejected_at: type: string format: date-time nullable: true readOnly: true created_at: type: string format: date-time example: '2026-04-26T18:06:51.940749Z' readOnly: true updated_at: type: string format: date-time example: '2026-04-26T18:09:24.785211Z' readOnly: true submitted_at: type: string format: date-time nullable: true example: '2026-04-26T18:07:03.716411Z' readOnly: true verified_at: type: string format: date-time nullable: true example: '2026-04-26T18:07:29.537926Z' readOnly: true expiring_at: type: string format: date-time nullable: true example: '2027-04-26T18:07:29.537981Z' readOnly: true branded-calling_PaginationMeta: type: object required: - total_pages - total_results - page_number - page_size properties: total_pages: type: integer example: 3 description: Total number of pages available given the current `page_size`. total_results: type: integer example: 42 description: Total number of items across all pages (excludes soft-deleted rows). page_number: type: integer example: 1 description: >- 1-based index of this page. Echoes the `page[number]` query parameter (default `1`). page_size: type: integer example: 20 description: Number of items returned in this page's `data` array. Capped at 250. description: >- JSON:API pagination metadata returned with every paginated list response. Page numbering is 1-based. `page_size` reports the number of items actually returned in `data` for this page; the requested size is taken from the `page[size]` query parameter. branded-calling_Errors: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/branded-calling_Error' description: List of one or more error entries. Order is not significant. description: >- Canonical Telnyx error envelope. Returned on every 4xx and 5xx response from this service. `errors` is non-empty; multiple entries indicate multiple distinct problems with the same request (e.g. one entry per invalid phone number on a bulk operation). CallReason: type: object properties: reason: type: string maxLength: 64 example: Appointment reminders created_at: type: string format: date-time example: '2026-04-26T18:06:51.940749Z' readOnly: true Document: type: object required: - document_id - document_type properties: document_id: type: string format: uuid description: >- Id returned by the Telnyx Documents API after you upload the file (upload via `POST /v2/documents`; see https://developers.telnyx.com/api/documents). example: 2a7e8337-e803-4057-a4ae-26c40eb0bc6c document_type: type: string enum: - 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 example: business_registration description: >- 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`. description: type: string maxLength: 255 example: Certificate of incorporation. RejectionReason: type: object properties: code: type: string example: documentation_incomplete title: type: string example: Documentation incomplete detail: type: string example: Provided documents do not establish business identity. message: type: string nullable: true description: >- Customer-visible free-text comment from the Telnyx vetting team. Only the first entry of `rejection_reasons` carries this; the rest are `null`. example: Please re-upload a clearer scan of the certificate. branded-calling_Error: type: object required: - code - title - detail - meta properties: code: type: string example: '10005' description: >- Stable numeric Telnyx error catalog id. See `meta.url` for the full catalog entry. title: type: string example: Invalid parameters description: >- Short human-readable category, e.g. `Bad Request`, `Duplicate resource`, `Not Found`, `Forbidden`. Treat as advisory only - the stable identifier is `code`. detail: type: string example: field required description: >- Context-specific message describing what went wrong on this particular request. May embed offending values; do not rely on it for programmatic matching - branch on `code`. meta: type: object required: - url properties: url: type: string format: uri example: https://developers.telnyx.com/docs/overview/errors/10005 pending_check_ids: type: array items: type: string format: uuid description: >- Set on `422 vetting_checks_incomplete` responses from `/admin/dir/{id}/approve` and `/admin/phone-number-batches/approve`. Lists the still-pending vetting check ids. pending_check_codes: type: array items: type: string description: >- Codes of the pending vetting checks (e.g. `loa_signature_valid`). pending_check_labels: type: array items: type: string description: Human-readable labels of the pending vetting checks. description: >- Carries `url` linking to the Telnyx error catalog entry for this `code`. Useful for forwarding the user to documentation. source: type: object description: Optional pointer at the offending field of the request. properties: pointer: type: string example: /body/legal_name parameter: type: string example: page[size] description: >- A single entry in the canonical Telnyx error envelope. `code` is the stable Telnyx error catalog id; the human-readable explanation lives at `meta.url`. `detail` is a context-specific message; `source.pointer` (when present) names the offending field of the request. responses: branded-calling_GenericErrorResponse: description: >- An error occurred. The response carries the standard Telnyx error envelope. content: application/json: schema: $ref: '#/components/schemas/branded-calling_Errors' examples: validation_error: summary: 422 - request body failed validation value: errors: - code: '10005' title: Invalid parameters detail: field required meta: url: https://developers.telnyx.com/docs/overview/errors/10005 source: pointer: /body/legal_name bad_request: summary: 400 - request rejected by a state guard description: >- Returned when the request itself is well-formed but the resource is in a state that disallows this action (e.g. updating a DIR while it is being vetted, or deleting an enterprise that still has DIRs in vetting). value: errors: - code: '10015' title: Bad Request detail: Cannot update DIR in 'verified' status meta: url: https://developers.telnyx.com/docs/overview/errors/10015 not_found: summary: 404 - resource does not exist or is not yours value: errors: - code: '10009' title: Resource not found detail: Enterprise not found. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 conflict: summary: 409 - request conflicts with current resource state value: errors: - code: '10021' title: Resource in use detail: >- DIR has 1 active infringement claim(s). Resolve the claim before making this change. meta: url: https://developers.telnyx.com/docs/overview/errors/10021 securitySchemes: bearerAuth: scheme: bearer type: http ````