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.

POST

dir

{dir_id}

references

JavaScript

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

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)

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"),
	)
	reference, err := client.Dir.References.New(
		context.TODO(),
		"dir_id",
		telnyx.DirReferenceNewParams{
			BusinessReferences: "business_references",
			FinancialReference: "financial_reference",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", reference.Data)
}

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);
    }
}

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)

<?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 {
  $reference = $client->dir->references->create(
    'dir_id',
    business_references: [],
    financial_reference: 'financial_reference',
  );

  var_dump($reference);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/dir/{dir_id}/references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_references": [
    {
      "full_name": "Dana Reyes",
      "phone_e164": "+14155550123",
      "email": "dana.reyes@example.com",
      "timezone": "America/New_York",
      "job_title": "VP of Operations",
      "organization": "Acme Logistics",
      "relationship_to_registrant": "Supplier"
    }
  ],
  "financial_reference": {
    "full_name": "Dana Reyes",
    "phone_e164": "+14155550123",
    "email": "dana.reyes@example.com",
    "timezone": "America/New_York",
    "job_title": "VP of Operations",
    "organization": "Acme Logistics",
    "relationship_to_registrant": "Supplier"
  }
}
'

{
  "data": [
    {
      "record_type": "dir_reference",
      "ref_type": "business",
      "slot": 1,
      "full_name": "Dana Reyes",
      "phone_e164": "+14155550123",
      "timezone": "America/New_York",
      "job_title": "VP of Operations",
      "organization": "Acme Logistics",
      "relationship_to_registrant": "Supplier",
      "email": "dana.reyes@example.com"
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Path Parameters

dir_id

string<uuid>

required

The DIR id. Lowercase UUID.

Example:

"16635d38-75a6-4481-82e8-69af60e05011"

Body

application/json

Exactly two business references plus one financial reference. The DIR's authorizer email must be verified before this is accepted.

business_references

object[]

required

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.

Required array length: 2 elements

Show child attributes

financial_reference

object

required

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.

Show child attributes

Response

Resubmit accepted. Identical values were confirmed unchanged, or changed values replaced those references.

data

object[]

required

Show child attributes

JavaScript

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

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)

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"),
	)
	reference, err := client.Dir.References.New(
		context.TODO(),
		"dir_id",
		telnyx.DirReferenceNewParams{
			BusinessReferences: "business_references",
			FinancialReference: "financial_reference",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", reference.Data)
}

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);
    }
}

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)

<?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 {
  $reference = $client->dir->references->create(
    'dir_id',
    business_references: [],
    financial_reference: 'financial_reference',
  );

  var_dump($reference);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/dir/{dir_id}/references \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_references": [
    {
      "full_name": "Dana Reyes",
      "phone_e164": "+14155550123",
      "email": "dana.reyes@example.com",
      "timezone": "America/New_York",
      "job_title": "VP of Operations",
      "organization": "Acme Logistics",
      "relationship_to_registrant": "Supplier"
    }
  ],
  "financial_reference": {
    "full_name": "Dana Reyes",
    "phone_e164": "+14155550123",
    "email": "dana.reyes@example.com",
    "timezone": "America/New_York",
    "job_title": "VP of Operations",
    "organization": "Acme Logistics",
    "relationship_to_registrant": "Supplier"
  }
}
'

{
  "data": [
    {
      "record_type": "dir_reference",
      "ref_type": "business",
      "slot": 1,
      "full_name": "Dana Reyes",
      "phone_e164": "+14155550123",
      "timezone": "America/New_York",
      "job_title": "VP of Operations",
      "organization": "Acme Logistics",
      "relationship_to_registrant": "Supplier",
      "email": "dana.reyes@example.com"
    }
  ]
}

Branded Calling

For AI Agents

Submit a DIR's references

Authorizations

Path Parameters

Body

Response