> ## 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. # Update a DIR > Edit a DIR. DIRs in `draft`, `rejected`, `unsuccessful`, or `suspended` can be edited freely: PATCH is a pure edit, `status` is never changed, and you re-vet by calling `POST /v2/dir/{dir_id}/submit` explicitly. A `verified` DIR can also be edited in place: a PATCH that changes any value returns the DIR to `draft` and branded delivery stops until you re-submit and the DIR is approved again, while a PATCH that changes nothing (an empty body or values identical to the current ones) leaves the DIR `verified`, so idempotent retries are safe. DIRs in any other status (`submitted`, `in_review`, `expired`, `infringement_claimed`, `permanently_rejected`) cannot be edited. ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/branded-calling/dirs.yml patch /dir/{dir_id} 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/{dir_id}: patch: tags: - Display Identity Records summary: Update a DIR description: >- Edit a DIR. DIRs in `draft`, `rejected`, `unsuccessful`, or `suspended` can be edited freely: PATCH is a pure edit, `status` is never changed, and you re-vet by calling `POST /v2/dir/{dir_id}/submit` explicitly. A `verified` DIR can also be edited in place: a PATCH that changes any value returns the DIR to `draft` and branded delivery stops until you re-submit and the DIR is approved again, while a PATCH that changes nothing (an empty body or values identical to the current ones) leaves the DIR `verified`, so idempotent retries are safe. DIRs in any other status (`submitted`, `in_review`, `expired`, `infringement_claimed`, `permanently_rejected`) cannot be edited. operationId: updateDirSimple parameters: - $ref: '#/components/parameters/DirId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DirUpdateRequest' example: display_name: Acme Plumbing & Wellness call_reasons: - Appointment reminders - Billing inquiries - Lab results logo_url: https://acmeplumbing.example.com/logo-v2-256.bmp responses: '200': description: DIR updated. content: application/json: schema: $ref: '#/components/schemas/DirWrapped' 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 }); const dir = await client.dir.update('16635d38-75a6-4481-82e8-69af60e05011', { call_reasons: ['Appointment reminders', 'Billing inquiries', 'Lab results'], display_name: 'Acme Plumbing & Wellness', logo_url: 'https://acmeplumbing.example.com/logo-v2-256.bmp', }); console.log(dir.data); - 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 ) dir = client.dir.update( dir_id="16635d38-75a6-4481-82e8-69af60e05011", call_reasons=["Appointment reminders", "Billing inquiries", "Lab results"], display_name="Acme Plumbing & Wellness", logo_url="https://acmeplumbing.example.com/logo-v2-256.bmp", ) print(dir.data) - 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\tdir, err := client.Dir.Update(\n\t\tcontext.TODO(),\n\t\t\"16635d38-75a6-4481-82e8-69af60e05011\",\n\t\ttelnyx.DirUpdateParams{\n\t\t\tCallReasons: []string{\"Appointment reminders\", \"Billing inquiries\", \"Lab results\"},\n\t\t\tDisplayName: telnyx.String(\"Acme Plumbing & Wellness\"),\n\t\t\tLogoURL: telnyx.String(\"https://acmeplumbing.example.com/logo-v2-256.bmp\"),\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", dir.Data)\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.DirUpdateParams; import com.telnyx.sdk.models.dir.DirUpdateResponse; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); DirUpdateResponse dir = client.dir().update("16635d38-75a6-4481-82e8-69af60e05011"); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") dir = telnyx.dir.update("16635d38-75a6-4481-82e8-69af60e05011") puts(dir) - lang: PHP source: >- dir->update( '16635d38-75a6-4481-82e8-69af60e05011', authorizerEmail: 'dev@stainless.com', authorizerName: 'authorizer_name', callReasons: ['Appointment reminders', 'Billing inquiries', 'Lab results'], certifyBrandIsAccurate: true, certifyIPOwnership: true, certifyNoShaftContent: true, displayName: 'Acme Plumbing & Wellness', documents: [ [ 'documentID' => '2a7e8337-e803-4057-a4ae-26c40eb0bc6c', 'documentType' => 'business_registration', 'description' => 'Certificate of incorporation.', ], ], logoURL: 'https://acmeplumbing.example.com/logo-v2-256.bmp', reselling: true, ); var_dump($dir); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx dir update \ --api-key 'My API Key' \ --dir-id 16635d38-75a6-4481-82e8-69af60e05011 components: parameters: DirId: name: dir_id in: path description: The DIR id. Lowercase UUID. required: true schema: type: string format: uuid example: 16635d38-75a6-4481-82e8-69af60e05011 schemas: DirUpdateRequest: type: object description: >- All fields are optional; only those supplied are updated. Same per-field rules as `DirCreateRequest`. properties: display_name: type: string minLength: 1 maxLength: 35 description: >- Name shown to call recipients. 1–35 characters, no emoji, not whitespace-only. reselling: type: boolean description: >- Set to true if your organization places calls on behalf of other enterprises (BPO/reseller). Updating this triggers re-vetting on next submit. authorizer_name: type: string maxLength: 255 description: >- Name of the person at your enterprise authorizing this DIR. Must be a real individual. authorizer_email: type: string format: email description: >- Contact email of the authorizer. Telnyx may send verification or infringement notices here. logo_url: type: string format: uri maxLength: 128 description: >- Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB). call_reasons: type: array items: type: string maxLength: 64 minItems: 1 maxItems: 10 description: >- 1–10 reasons your business calls customers. Validate phrasing against `POST /call_reasons/validate`. certify_brand_is_accurate: type: boolean description: >- Certification that the DIR information is accurate. Must be `true` for the DIR to be submitted for vetting. example: true certify_no_shaft_content: type: boolean description: >- Certification that this DIR is not used for SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) where prohibited. Must be `true` for the DIR to be submitted for vetting. example: true certify_ip_ownership: type: boolean description: >- Certification of ownership of any logos/trademarks shown. Must be `true` for the DIR to be submitted for vetting. example: true documents: type: array items: $ref: '#/components/schemas/Document' maxItems: 20 description: >- Additional supporting documents to attach. Append-only: existing documents are never removed or replaced, and an empty or omitted list is a no-op. Each `document_id` may appear at most once on a DIR. DirWrapped: type: object required: - data properties: data: $ref: '#/components/schemas/Dir' 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. 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_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 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. 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 ````