Display Identity Records

Create a Display Identity Record (DIR)

Changed on

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

  • 400 - validation error; errors[].source.pointer names the offending field.
  • 400 - a certification field is not true.
  • 400 - Branded Calling not activated on this enterprise (see POST /enterprises/{id}/branded_calling).
  • 400 - the enterprise is a BPO enterprise (role_type bpo), which cannot own a DIR.
  • 400 - a bpo_authorizations entry is not an approved BPO enterprise in your account, or its loa_document_id could not be validated.
  • 404 - enterprise does not exist or does not belong to your account.
  • 503 - the document check is temporarily unavailable; retry.
post/enterprises/{enterprise_id}/dir

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/enterprises/{enterprise_id}/dir
  • Auth: HTTP bearer

Path parameters

enterprise_idstring uuid required
Example:4a6192a4-573d-446d-b3ce-aff9117272a6

The enterprise id. Lowercase UUID.

Request body

display_namestring required

Name shown to call recipients. No emoji; not whitespace-only.

resellingboolean

Set to true if your organization places calls on behalf of other enterprises (BPO/reseller).

certify_brand_is_accuratetrue required

Certification that the DIR information is accurate. Must be true for the DIR to be submitted for vetting.

certify_no_shaft_contenttrue required

Must be true. Confirms this DIR is not used for SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) where prohibited.

certify_ip_ownershiptrue required

Must be true. Confirms ownership of any logos/trademarks shown.

authorizer_namestring 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).

authorizer_emailstring email required

Contact email of the authorizer. Telnyx may send verification or infringement-notice email here; use a monitored mailbox.

logo_urlstring uri

Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB).

call_reasonsstring[] required

1–10 reasons your business calls customers. Validate phrasing against POST /call_reasons/validate.

webhook_urlstring uri nullable

Optional https:// URL that receives webhook notifications when this DIR's compliance review completes (rejection outcomes include structured rejection reasons). Maximum 2048 characters.

Example request

{
  "display_name": "Acme Plumbing",
  "certify_brand_is_accurate": true,
  "certify_no_shaft_content": true,
  "certify_ip_ownership": true,
  "authorizer_name": "Sam Owner",
  "authorizer_email": "sam@acmeplumbing.example.com",
  "logo_url": "https://acmeplumbing.example.com/logo-256.bmp",
  "call_reasons": [
    "Appointment reminders",
    "Billing inquiries"
  ],
  "documents": [
    {
      "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
      "document_type": "business_registration",
      "description": "Certificate of incorporation."
    }
  ],
  "webhook_url": "https://mapleridge.example.com/webhooks/branded-calling",
  "bpo_authorizations": [
    {
      "bpo_enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
      "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
    }
  ]
}

Response

DIR created in draft status.

Example response

{
  "data": {
    "id": "16635d38-75a6-4481-82e8-69af60e05011",
    "enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "display_name": "Acme Plumbing",
    "certify_brand_is_accurate": true,
    "certify_no_shaft_content": true,
    "certify_ip_ownership": true,
    "authorizer_name": "Sam Owner",
    "authorizer_email": "sam@acmeplumbing.example.com",
    "logo_url": "https://acmeplumbing.example.com/logo-256.bmp",
    "call_reasons": [
      {
        "reason": "Appointment reminders",
        "created_at": "2026-04-26T18:06:51.940749Z"
      }
    ],
    "documents": [
      {
        "document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
        "document_type": "business_registration",
        "description": "Certificate of incorporation."
      }
    ],
    "rejection_reasons": [
      {
        "code": "documentation_incomplete",
        "title": "Documentation incomplete",
        "detail": "Provided documents do not establish business identity.",
        "message": "Please re-upload a clearer scan of the certificate."
      }
    ],
    "created_at": "2026-04-26T18:06:51.940749Z",
    "updated_at": "2026-04-26T18:09:24.785211Z",
    "submitted_at": "2026-04-26T18:07:03.716411Z",
    "verified_at": "2026-04-26T18:07:29.537926Z",
    "expiring_at": "2027-04-26T18:07:29.537981Z",
    "delete_requested_at": "2026-04-27T09:12:44.201820Z",
    "webhook_url": "https://acmehealthcare.example.com/webhooks/branded-calling"
  }
}

Changes

  • 3f89a75a499fRevision changes
    • warning

      added the new bank_reference_letter enum value to the /// response property for the response status

    • warning

      added the new business_credit_report enum value to the /// response property for the response status

    • warning

      added the new certificate_of_good_standing enum value to the /// response property for the response status

    • info

      added the new bank_reference_letter enum value to the request property //

    • info

      added the new business_credit_report enum value to the request property //

    • info

      added the new certificate_of_good_standing enum value to the request property //

  • 27a8076ac294Revision changes
    • warning

      added the new delete_requested enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status