> ## 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. # Render the Branded Calling LOA for a DIR > Generate a pre-filled Letter of Authorization (LOA) PDF for a DIR. Enterprise identity (legal name, DBA, address, contact, website, tax id) and the DIR display name are read server-side; the caller supplies the telephone numbers to authorize, an optional Authorized Agent block, and an optional drawn signature. When `signature` is omitted the PDF is returned unsigned so the customer can sign it externally and upload it via the Documents API. When `signature` is present the PDF embeds the supplied image, printed name, and signed-at date. Returns `application/pdf`. ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/branded-calling/dirs.yml post /dir/{dir_id}/loa 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}/loa: post: tags: - Display Identity Records summary: Render the Branded Calling LOA for a DIR description: >- Generate a pre-filled Letter of Authorization (LOA) PDF for a DIR. Enterprise identity (legal name, DBA, address, contact, website, tax id) and the DIR display name are read server-side; the caller supplies the telephone numbers to authorize, an optional Authorized Agent block, and an optional drawn signature. When `signature` is omitted the PDF is returned unsigned so the customer can sign it externally and upload it via the Documents API. When `signature` is present the PDF embeds the supplied image, printed name, and signed-at date. Returns `application/pdf`. operationId: renderDirLoa parameters: - name: dir_id in: path required: true schema: type: string format: uuid description: The DIR id. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrandLoaRenderRequest' responses: '200': description: The rendered LOA PDF. content: application/pdf: schema: type: string format: binary '400': $ref: '#/components/responses/branded-calling_GenericErrorResponse' '404': $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 response = await client.dir.createLoa('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { phone_numbers: ['+13125550000'], }); console.log(response); const content = await response.blob(); console.log(content); - 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 ) response = client.dir.create_loa( dir_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", phone_numbers=["+13125550000"], ) print(response) content = response.read() print(content) - 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\tresponse, err := client.Dir.NewLoa(\n\t\tcontext.TODO(),\n\t\t\"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e\",\n\t\ttelnyx.DirNewLoaParams{\n\t\t\tPhoneNumbers: []string{\"+13125550000\"},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response)\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.core.http.HttpResponse; import com.telnyx.sdk.models.dir.DirCreateLoaParams; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); DirCreateLoaParams params = DirCreateLoaParams.builder() .dirId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e") .addPhoneNumber("+13125550000") .build(); HttpResponse response = client.dir().createLoa(params); } } - lang: Ruby source: >- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.dir.create_loa("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", phone_numbers: ["+13125550000"]) puts(response) - lang: PHP source: >- dir->createLoa( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', phoneNumbers: ['+13125550000'], agent: [ 'administrativeArea' => 'administrative_area', 'city' => 'city', 'contactEmail' => 'dev@stainless.com', 'contactName' => 'contact_name', 'contactPhone' => '+13125550000', 'contactTitle' => 'contact_title', 'country' => 'US', 'legalName' => 'legal_name', 'postalCode' => 'postal_code', 'streetAddress' => 'street_address', 'dba' => 'dba', 'extendedAddress' => 'extended_address', ], signature: ['imageBase64' => 'x', 'signerName' => 'signer_name'], ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx dir create-loa \ --api-key 'My API Key' \ --dir-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e \ --phone-number "'+13125550000'" components: schemas: BrandLoaRenderRequest: type: object required: - phone_numbers properties: phone_numbers: type: array minItems: 1 maxItems: 15 description: >- Telephone numbers to authorize on the DIR, in `+E164` format (`+` followed by 10-15 digits). Max 15 per request. items: type: string pattern: ^\+[1-9][0-9]{9,14}$ example: '+13125550000' agent: allOf: - $ref: '#/components/schemas/AgentInput' description: >- Optional. The third-party reseller / partner managing the enterprise's phone numbers. Omit when working directly with Telnyx; the LOA marks the Authorized Agent block as N/A. signature: allOf: - $ref: '#/components/schemas/SignaturePayload' description: >- Optional. When provided the rendered PDF embeds the signature image, printed name, and signed-at date. When absent the PDF is returned unsigned so the customer can sign externally and upload it via the Documents API. AgentInput: type: object description: >- Third-party reseller / partner managing the enterprise's phone numbers. Omit when the enterprise works directly with Telnyx. required: - legal_name - street_address - city - administrative_area - postal_code - country - contact_name - contact_title - contact_email - contact_phone properties: legal_name: type: string maxLength: 200 dba: type: string nullable: true maxLength: 200 street_address: type: string maxLength: 255 extended_address: type: string nullable: true maxLength: 255 city: type: string maxLength: 120 administrative_area: type: string maxLength: 120 postal_code: type: string maxLength: 30 country: type: string minLength: 2 maxLength: 2 example: US contact_name: type: string maxLength: 200 contact_title: type: string maxLength: 200 contact_email: type: string format: email contact_phone: type: string maxLength: 30 example: '+13125550000' SignaturePayload: type: object required: - image_base64 properties: image_base64: type: string minLength: 1 maxLength: 60000 description: PNG image, base64-encoded. signer_name: type: string nullable: true maxLength: 200 description: >- Optional. When absent the rendered PDF falls back to the enterprise contact's legal name. 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). 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 ````