Create a Display Identity Record (DIR)
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 againstPOST /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; eachdocument_idmust be obtained by uploading the file via the Telnyx Documents API first. Within one DIR adocument_idmay only appear once.certify_brand_is_accurate,certify_no_shaft_content,certify_ip_ownershipMUST all betrue.
Failure modes
422- validation error;errors[].source.pointernames the offending field.403- Branded Calling not activated on this enterprise (seePOST /enterprises/{id}/branded_calling).404- enterprise does not exist or does not belong to your account.
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.enterprises.dir.create('4a6192a4-573d-446d-b3ce-aff9117272a6', {
authorizer_email: '[email protected]',
authorizer_name: 'Sam Owner',
certify_brand_is_accurate: true,
certify_ip_ownership: true,
certify_no_shaft_content: true,
display_name: 'Acme Plumbing',
call_reasons: ['Appointment reminders', 'Billing inquiries'],
});
console.log(dir.data);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.enterprises.dir.create(
enterprise_id="4a6192a4-573d-446d-b3ce-aff9117272a6",
authorizer_email="[email protected]",
authorizer_name="Sam Owner",
certify_brand_is_accurate=True,
certify_ip_ownership=True,
certify_no_shaft_content=True,
display_name="Acme Plumbing",
call_reasons=["Appointment reminders", "Billing inquiries"],
reselling=False,
)
print(dir.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
dir, err := client.Enterprises.Dir.New(
context.TODO(),
"4a6192a4-573d-446d-b3ce-aff9117272a6",
telnyx.EnterpriseDirNewParams{
AuthorizerEmail: "[email protected]",
AuthorizerName: "Sam Owner",
CertifyBrandIsAccurate: true,
CertifyIPOwnership: true,
CertifyNoShaftContent: true,
DisplayName: "Acme Plumbing",
CallReasons: []string{"Appointment reminders", "Billing inquiries"},
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", dir.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.enterprises.dir.DirCreateParams;
import com.telnyx.sdk.models.enterprises.dir.DirCreateResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
DirCreateParams params = DirCreateParams.builder()
.enterpriseId("4a6192a4-573d-446d-b3ce-aff9117272a6")
.authorizerEmail("[email protected]")
.authorizerName("Sam Owner")
.certifyBrandIsAccurate(DirCreateParams.CertifyBrandIsAccurate.TRUE)
.certifyIpOwnership(DirCreateParams.CertifyIpOwnership.TRUE)
.certifyNoShaftContent(DirCreateParams.CertifyNoShaftContent.TRUE)
.displayName("Acme Plumbing")
.build();
DirCreateResponse dir = client.enterprises().dir().create(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
dir = telnyx.enterprises.dir.create(
"4a6192a4-573d-446d-b3ce-aff9117272a6",
authorizer_email: "[email protected]",
authorizer_name: "Sam Owner",
certify_brand_is_accurate: true,
certify_ip_ownership: true,
certify_no_shaft_content: true,
display_name: "Acme Plumbing"
)
puts(dir)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$dir = $client->enterprises->dir->create(
'4a6192a4-573d-446d-b3ce-aff9117272a6',
authorizerEmail: '[email protected]',
authorizerName: 'Sam Owner',
certifyBrandIsAccurate: true,
certifyIPOwnership: true,
certifyNoShaftContent: true,
displayName: 'Acme Plumbing',
callReasons: ['Appointment reminders', 'Billing inquiries'],
documents: [
[
'documentID' => '2a7e8337-e803-4057-a4ae-26c40eb0bc6c',
'documentType' => 'business_registration',
'description' => 'Certificate of incorporation.',
],
],
logoURL: 'https://acmeplumbing.example.com/logo-256.bmp',
reselling: false,
);
var_dump($dir);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx enterprises:dir create \
--api-key 'My API Key' \
--enterprise-id 4a6192a4-573d-446d-b3ce-aff9117272a6 \
--authorizer-email [email protected] \
--authorizer-name 'Sam Owner' \
--certify-brand-is-accurate true \
--certify-ip-ownership true \
--certify-no-shaft-content true \
--display-name 'Acme Plumbing'curl --request POST \
--url https://api.telnyx.com/v2/enterprises/{enterprise_id}/dir \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"display_name": "Acme Plumbing",
"reselling": false,
"certify_brand_is_accurate": true,
"certify_no_shaft_content": true,
"certify_ip_ownership": true,
"authorizer_name": "Sam Owner",
"authorizer_email": "[email protected]",
"call_reasons": [
"Appointment reminders",
"Billing inquiries"
]
}
'{
"data": {
"id": "16635d38-75a6-4481-82e8-69af60e05011",
"enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
"display_name": "Acme Plumbing",
"reselling": false,
"certify_brand_is_accurate": true,
"certify_no_shaft_content": true,
"certify_ip_ownership": true,
"authorizer_name": "Sam Owner",
"authorizer_email": "[email protected]",
"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."
}
],
"status": "draft",
"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."
}
],
"rejected_at": "2023-11-07T05:31:56Z",
"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"
}
}Authorizations
Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
Path Parameters
The enterprise id. Lowercase UUID.
"4a6192a4-573d-446d-b3ce-aff9117272a6"
Body
Name shown to call recipients. No emoji; not whitespace-only.
1 - 35"Acme Plumbing"
Certification that the DIR information is accurate. Must be true for the DIR to be submitted for vetting.
true true
Must be true. Confirms this DIR is not used for SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) where prohibited.
true true
Must be true. Confirms ownership of any logos/trademarks shown.
true true
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).
255"Sam Owner"
Contact email of the authorizer. Telnyx may send verification or infringement-notice email here; use a monitored mailbox.
1–10 reasons your business calls customers. Validate phrasing against POST /call_reasons/validate.
1 - 10 elements64[
"Appointment reminders",
"Billing inquiries"
]
Set to true if your organization places calls on behalf of other enterprises (BPO/reseller).
false
Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB).
128"https://acmeplumbing.example.com/logo-256.bmp"
Supporting documents. Each document_id may appear at most once on a DIR.
20Show child attributes
Show child attributes
Optional https:// URL that receives webhook notifications when this DIR's compliance review completes (rejection outcomes include structured rejection reasons). Maximum 2048 characters.
2048"https://mapleridge.example.com/webhooks/branded-calling"
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.
10Show child attributes
Show child attributes
Response
DIR created in draft status.
Show child attributes
Show child attributes
Was this page helpful?
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.enterprises.dir.create('4a6192a4-573d-446d-b3ce-aff9117272a6', {
authorizer_email: '[email protected]',
authorizer_name: 'Sam Owner',
certify_brand_is_accurate: true,
certify_ip_ownership: true,
certify_no_shaft_content: true,
display_name: 'Acme Plumbing',
call_reasons: ['Appointment reminders', 'Billing inquiries'],
});
console.log(dir.data);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.enterprises.dir.create(
enterprise_id="4a6192a4-573d-446d-b3ce-aff9117272a6",
authorizer_email="[email protected]",
authorizer_name="Sam Owner",
certify_brand_is_accurate=True,
certify_ip_ownership=True,
certify_no_shaft_content=True,
display_name="Acme Plumbing",
call_reasons=["Appointment reminders", "Billing inquiries"],
reselling=False,
)
print(dir.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
dir, err := client.Enterprises.Dir.New(
context.TODO(),
"4a6192a4-573d-446d-b3ce-aff9117272a6",
telnyx.EnterpriseDirNewParams{
AuthorizerEmail: "[email protected]",
AuthorizerName: "Sam Owner",
CertifyBrandIsAccurate: true,
CertifyIPOwnership: true,
CertifyNoShaftContent: true,
DisplayName: "Acme Plumbing",
CallReasons: []string{"Appointment reminders", "Billing inquiries"},
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", dir.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.enterprises.dir.DirCreateParams;
import com.telnyx.sdk.models.enterprises.dir.DirCreateResponse;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
DirCreateParams params = DirCreateParams.builder()
.enterpriseId("4a6192a4-573d-446d-b3ce-aff9117272a6")
.authorizerEmail("[email protected]")
.authorizerName("Sam Owner")
.certifyBrandIsAccurate(DirCreateParams.CertifyBrandIsAccurate.TRUE)
.certifyIpOwnership(DirCreateParams.CertifyIpOwnership.TRUE)
.certifyNoShaftContent(DirCreateParams.CertifyNoShaftContent.TRUE)
.displayName("Acme Plumbing")
.build();
DirCreateResponse dir = client.enterprises().dir().create(params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
dir = telnyx.enterprises.dir.create(
"4a6192a4-573d-446d-b3ce-aff9117272a6",
authorizer_email: "[email protected]",
authorizer_name: "Sam Owner",
certify_brand_is_accurate: true,
certify_ip_ownership: true,
certify_no_shaft_content: true,
display_name: "Acme Plumbing"
)
puts(dir)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$dir = $client->enterprises->dir->create(
'4a6192a4-573d-446d-b3ce-aff9117272a6',
authorizerEmail: '[email protected]',
authorizerName: 'Sam Owner',
certifyBrandIsAccurate: true,
certifyIPOwnership: true,
certifyNoShaftContent: true,
displayName: 'Acme Plumbing',
callReasons: ['Appointment reminders', 'Billing inquiries'],
documents: [
[
'documentID' => '2a7e8337-e803-4057-a4ae-26c40eb0bc6c',
'documentType' => 'business_registration',
'description' => 'Certificate of incorporation.',
],
],
logoURL: 'https://acmeplumbing.example.com/logo-256.bmp',
reselling: false,
);
var_dump($dir);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx enterprises:dir create \
--api-key 'My API Key' \
--enterprise-id 4a6192a4-573d-446d-b3ce-aff9117272a6 \
--authorizer-email [email protected] \
--authorizer-name 'Sam Owner' \
--certify-brand-is-accurate true \
--certify-ip-ownership true \
--certify-no-shaft-content true \
--display-name 'Acme Plumbing'curl --request POST \
--url https://api.telnyx.com/v2/enterprises/{enterprise_id}/dir \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"display_name": "Acme Plumbing",
"reselling": false,
"certify_brand_is_accurate": true,
"certify_no_shaft_content": true,
"certify_ip_ownership": true,
"authorizer_name": "Sam Owner",
"authorizer_email": "[email protected]",
"call_reasons": [
"Appointment reminders",
"Billing inquiries"
]
}
'{
"data": {
"id": "16635d38-75a6-4481-82e8-69af60e05011",
"enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
"display_name": "Acme Plumbing",
"reselling": false,
"certify_brand_is_accurate": true,
"certify_no_shaft_content": true,
"certify_ip_ownership": true,
"authorizer_name": "Sam Owner",
"authorizer_email": "[email protected]",
"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."
}
],
"status": "draft",
"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."
}
],
"rejected_at": "2023-11-07T05:31:56Z",
"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"
}
}