Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.

Path Parameters

enterprise_id
string<uuid>
required

The enterprise id. Lowercase UUID.

Example:

"4a6192a4-573d-446d-b3ce-aff9117272a6"

Body

application/json
display_name
string
required

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

Required string length: 1 - 35
Example:

"Acme Plumbing"

certify_brand_is_accurate
enum<boolean>
required

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

Available options:
true
Example:

true

certify_no_shaft_content
enum<boolean>
required

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

Available options:
true
Example:

true

certify_ip_ownership
enum<boolean>
required

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

Available options:
true
Example:

true

authorizer_name
string
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).

Maximum string length: 255
Example:

"Sam Owner"

authorizer_email
string<email>
required

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

call_reasons
string[]
required

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

Required array length: 1 - 10 elements
Maximum string length: 64
Example:
reselling
boolean
default:false

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

Example:

false

logo_url
string<uri>

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

Maximum string length: 128
Example:

"https://acmeplumbing.example.com/logo-256.bmp"

documents
object[]

Supporting documents. Each document_id may appear at most once on a DIR.

Maximum array length: 20
webhook_url
string<uri> | null

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

Maximum string length: 2048
Example:

"https://mapleridge.example.com/webhooks/branded-calling"

bpo_authorizations
object[]

Optional. Approved BPO (Business Process Outsourcer) accounts on your organization authorized to place branded calls for this DIR, each with the signed Letter of Authorization the Brand Owner granted it. Each authorization starts pending and takes effect only after an admin reviews its Letter of Authorization. Omit or send an empty list to authorize no BPO on this DIR. Maximum 10.

Maximum array length: 10

Response

DIR created in draft status.

data
object
required