> ## 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. # Submit a DIR's references > Submit the two business references and one financial reference for a DIR. The DIR's authorizer email must be verified first (see the email-verification endpoint). Until it is, this returns `409` and no references are stored. The request body carries exactly two business references plus one financial reference. The first submission stores them and returns `201`. Resubmitting returns `200`: identical values are simply confirmed and nothing is written, while changed values replace those references. Replacing a reference is allowed only while the DIR itself is still editable, the same window in which a single reference may be updated; once the DIR has been submitted for vetting this returns `400`. A replaced reference's pending verification call is cancelled and its dial-in code stops working, and the replacement contact is emailed fresh scheduling details. References whose details did not change keep their existing call, code, and the notice already sent to them. The response always echoes the stored references in the same shape as the GET. Who qualifies: the two business references confirm the company's reputation and operations. Each should be a senior contact at an organization the business works with, such as a vendor, partner, or client: a C-suite executive (CEO, CFO, CTO, COO), an owner or founder as reflected in the company's corporate records, or a senior manager, director, or executive. The financial reference confirms the company pays its bills and should be a licensed certified public accountant (CPA) the company uses, a contact at a bank or financial institution that has a relationship with the company, or a reasonable alternative banking or financial reference. ## OpenAPI ````yaml /openapi/source/external/branded-calling/branded-calling.json post /dir/{dir_id}/references openapi: 3.0.0 info: x-latency-category: responsive version: 2.0.0 title: Telnyx Branded Calling API description: >- The Telnyx Branded Calling API lets you register your business identity as Display Identity Records (DIRs) and associate phone numbers so your verified caller identity is shown on outbound calls. Flow: create an enterprise → activate Branded Calling → create a DIR → submit it for vetting → after approval, attach phone numbers and submit them in a batch for vetting. Branded Calling fees are charged per DIR and per branded call; activating an enterprise and adding phone numbers are free. See https://telnyx.com/pricing/branded-calling for current pricing. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 description: Telnyx API v2 (production) security: - bearerAuth: [] tags: - name: Enterprises description: Manage the legal-entity record that owns your DIRs and phone numbers. - name: Display Identity Records description: >- A Display Identity Record (DIR) is the verified calling identity (display name, logo, call reasons) shown to recipients on outbound calls. - name: DIR References description: >- Submit and manage the two business references and one financial reference that vouch for a DIR. References are contacted to confirm the business identity during vetting. - name: Email Verification description: >- Verify ownership of a DIR's authorizer email. A short code is emailed and confirmed; the email must be verified before references can be submitted. - name: Phone Numbers description: >- Associate phone numbers with a verified DIR so calls from those numbers carry the DIR's display identity. - name: Phone Number Batches description: >- Phone numbers are submitted to Telnyx for vetting in batches. Batches group all numbers added in a single request under the same Letter of Authorization. - name: Comments description: >- Read messages from the Telnyx vetting team and reply with clarifying information. - name: Infringement Claims description: >- Trademark or impersonation claims filed against your DIR. Customers may contest a claim with supporting evidence. - name: Reference Data description: >- Static reference values the API accepts: call reasons, document types, rejection types. - name: Terms of Service description: >- Accept and review the Branded Calling and Phone Number Reputation terms of service. paths: /dir/{dir_id}/references: post: tags: - DIR References summary: Submit a DIR's references description: >- Submit the two business references and one financial reference for a DIR. The DIR's authorizer email must be verified first (see the email-verification endpoint). Until it is, this returns `409` and no references are stored. The request body carries exactly two business references plus one financial reference. The first submission stores them and returns `201`. Resubmitting returns `200`: identical values are simply confirmed and nothing is written, while changed values replace those references. Replacing a reference is allowed only while the DIR itself is still editable, the same window in which a single reference may be updated; once the DIR has been submitted for vetting this returns `400`. A replaced reference's pending verification call is cancelled and its dial-in code stops working, and the replacement contact is emailed fresh scheduling details. References whose details did not change keep their existing call, code, and the notice already sent to them. The response always echoes the stored references in the same shape as the GET. Who qualifies: the two business references confirm the company's reputation and operations. Each should be a senior contact at an organization the business works with, such as a vendor, partner, or client: a C-suite executive (CEO, CFO, CTO, COO), an owner or founder as reflected in the company's corporate records, or a senior manager, director, or executive. The financial reference confirms the company pays its bills and should be a licensed certified public accountant (CPA) the company uses, a contact at a bank or financial institution that has a relationship with the company, or a reasonable alternative banking or financial reference. operationId: submitDirReferences parameters: - $ref: '#/components/parameters/DirId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReferenceSubmissionRequest' responses: '200': description: >- Resubmit accepted. Identical values were confirmed unchanged, or changed values replaced those references. content: application/json: schema: $ref: '#/components/schemas/ReferenceList' '201': description: The stored references. content: application/json: schema: $ref: '#/components/schemas/ReferenceList' '400': $ref: '#/components/responses/GenericErrorResponse' '404': $ref: '#/components/responses/GenericErrorResponse' '409': $ref: '#/components/responses/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 Reference = await client.dir.references.create('dir_id', { business_references: [], financial_reference: 'financial_reference', }); console.log(Reference.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 ) reference = client.dir.references.create( dir_id="dir_id", business_references=[], financial_reference="financial_reference", ) print(reference.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\treference, err := client.Dir.References.New(\n\t\tcontext.TODO(),\n\t\t\"dir_id\",\n\t\ttelnyx.DirReferenceNewParams{\n\t\t\tBusinessReferences: \"business_references\",\n\t\t\tFinancialReference: \"financial_reference\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", reference.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.references.ReferenceCreateParams; import java.util.List; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); ReferenceCreateParams params = ReferenceCreateParams.builder() .businessReferences(List.of()) .financialReference("financial_reference") .build(); var response = client.dir().references().create("dir_id", params); } } - lang: Ruby source: >- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") reference = telnyx.dir.references.create("dir_id", business_references: [], financial_reference: "financial_reference") puts(reference) - lang: PHP source: >- dir->references->create( 'dir_id', business_references: [], financial_reference: 'financial_reference', ); var_dump($reference); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx dir:references create \ --api-key 'My API Key' \ --dir-id 16635d38-75a6-4481-82e8-69af60e05011 \ --business-references business_references \ --financial-reference financial_reference 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: ReferenceSubmissionRequest: type: object description: >- Exactly two business references plus one financial reference. The DIR's authorizer email must be verified before this is accepted. required: - business_references - financial_reference properties: business_references: type: array minItems: 2 maxItems: 2 description: >- Exactly two business references. Array order determines each one's slot: the first entry becomes slot 1 and the second becomes slot 2. Those slots are what you pass when updating a single reference later. Each should be a senior contact who can speak to your company's reputation and operations: a C-suite executive (CEO, CFO, CTO, COO), an owner or founder as reflected in your corporate records, or a senior manager, director, or executive at an organization you work with, such as a vendor, partner, or client. items: $ref: '#/components/schemas/ReferenceInput' financial_reference: description: >- One financial reference who can confirm the company pays its bills: a licensed certified public accountant (CPA) the company uses, a contact at a bank or financial institution that has a relationship with the company, or a reasonable alternative banking or financial reference. allOf: - $ref: '#/components/schemas/ReferenceInput' ReferenceList: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Reference' ReferenceInput: type: object description: >- One reference supplied at submit. The reference type is implied by the field that carries it (business_references vs financial_reference). required: - full_name - phone_e164 - email - timezone properties: full_name: type: string minLength: 1 maxLength: 255 description: Full name of the reference contact. example: Dana Reyes job_title: type: string maxLength: 255 nullable: true description: Job title of the reference contact. example: VP of Operations organization: type: string maxLength: 255 nullable: true description: Organization the reference contact belongs to. example: Acme Logistics relationship_to_registrant: type: string maxLength: 255 nullable: true description: How the reference contact is related to the registering business. example: Supplier phone_e164: type: string pattern: ^\+[1-9]\d{1,14}$ description: Reference phone number in E.164 format, e.g. +14155550123. example: '+14155550123' email: type: string format: email description: >- Reference contact email address. Required: the reference is emailed scheduling and dial-in notices. example: dana.reyes@example.com timezone: type: string description: >- IANA timezone id for the reference (e.g. America/New_York). Required: calls are only placed within the reference's local 8am-9pm window. example: America/New_York Reference: type: object description: >- A reference (business or financial) on a DIR, in the customer-facing shape. No internal identifiers are exposed. required: - record_type - ref_type - slot - full_name - phone_e164 - timezone properties: record_type: type: string enum: - dir_reference description: Always `dir_reference`. example: dir_reference readOnly: true ref_type: type: string enum: - business - financial description: Whether this is a business reference or the financial reference. example: business slot: type: integer minimum: 1 maximum: 2 description: >- Position within the reference type, counting from 1. Business references occupy slots 1 and 2, in the order they were sent in the `business_references` array; the financial reference occupies slot 1. Use this value together with `ref_type` to address the reference when updating it. example: 1 full_name: type: string maxLength: 255 description: Full name of the reference contact. example: Dana Reyes job_title: type: string maxLength: 255 nullable: true description: Job title of the reference contact. example: VP of Operations organization: type: string maxLength: 255 nullable: true description: Organization the reference contact belongs to. example: Acme Logistics relationship_to_registrant: type: string maxLength: 255 nullable: true description: How the reference contact is related to the registering business. example: Supplier phone_e164: type: string description: Reference phone number in E.164 format. example: '+14155550123' email: type: string format: email nullable: true description: Reference contact email address. example: dana.reyes@example.com timezone: type: string description: >- IANA timezone id for the reference. Calls are only placed within the reference's local 8am-9pm window. example: America/New_York Errors: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/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). 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: GenericErrorResponse: description: >- An error occurred. The response carries the standard Telnyx error envelope. content: application/json: schema: $ref: '#/components/schemas/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: type: http scheme: bearer description: >- Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys. ````