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 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

422 - validation error; errors[].source.pointer names the offending field.
403 - Branded Calling not activated on this enterprise (see POST /enterprises/{id}/branded_calling).
404 - enterprise does not exist or does not belong to your account.

POST

enterprises

{enterprise_id}

dir

JavaScript

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: 'sam@acmeplumbing.example.com',
  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="sam@acmeplumbing.example.com",
    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:        "sam@acmeplumbing.example.com",
			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("sam@acmeplumbing.example.com")
            .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: "sam@acmeplumbing.example.com",
  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: 'sam@acmeplumbing.example.com',
    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 sam@acmeplumbing.example.com \
  --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": "sam@acmeplumbing.example.com",
  "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": "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."
      }
    ],
    "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"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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

Must be true.

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.

Example:

"sam@acmeplumbing.example.com"

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:

[
  "Appointment reminders",
  "Billing inquiries"
]

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

Show child attributes

Response

DIR created in draft status.

data

object

required

Show child attributes

List DIRs in an enterprise

List all DIRs across your enterprises

⌘I

JavaScript

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: 'sam@acmeplumbing.example.com',
  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="sam@acmeplumbing.example.com",
    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:        "sam@acmeplumbing.example.com",
			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("sam@acmeplumbing.example.com")
            .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: "sam@acmeplumbing.example.com",
  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: 'sam@acmeplumbing.example.com',
    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 sam@acmeplumbing.example.com \
  --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": "sam@acmeplumbing.example.com",
  "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": "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."
      }
    ],
    "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"
  }
}