Enterprises - Telnyx

Overview

An Enterprise represents your business entity on the Telnyx platform. It’s the top-level resource you must register before you can use Branded Calling to display your verified business identity (display name, logo, call reason) on outbound calls.

What you need

To create an enterprise, you’ll need:

Field	Required	Description
`legal_name`	yes	Registered legal name (3-64 chars).
`doing_business_as`	yes	DBA name (max 255 chars).
`organization_type`	yes	One of `commercial`, `government`, `non_profit`.
`organization_legal_type`	yes	One of `corporation`, `llc`, `partnership`, `nonprofit`, `other`.
`country_code`	yes	ISO 3166-1 alpha-2 code. `US` and `CA` are accepted (`CA` applies to Number Reputation). Branded Calling itself is currently US-only.
`role_type`	no	One of `enterprise` (registers its own DIRs) or `bpo` (Business Process Outsourcer calling on behalf of others). Defaults to `enterprise`.
`jurisdiction_of_incorporation`	yes	State/province/country of registration (e.g. `Delaware`).
`website`	yes	Your business website.
`fein`	yes	Federal Employer Identification Number (`XX-XXXXXXX` or `XXXXXXXXX`).
`industry`	yes	Industry classification. Must be one of a fixed set of values (e.g. `technology`, `healthcare`, `retail`, `finance`, `legal`, `insurance`); an unrecognized value returns `400`.
`number_of_employees`	yes	One of `1-10`, `11-50`, `51-200`, `201-500`, `501-2000`, `2001-10000`, `10001+`.
`organization_contact`	yes	Object with `first_name`, `last_name`, `email`, `job_title`, `phone_number`.
`billing_contact`	yes	Object with `first_name`, `last_name`, `email`, `phone_number`.
`organization_physical_address`	yes	Physical business address.
`billing_address`	yes	Billing address.
`customer_reference`	no	Optional free-form identifier you can attach for your own bookkeeping (max 255 chars).

Quick start

1. Accept the Branded Calling Terms of Service

You must agree to the Branded Calling ToS before activating the product.

curl -X POST https://api.telnyx.com/v2/terms_of_service/branded_calling/agree \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Create an enterprise

curl -X POST https://api.telnyx.com/v2/enterprises \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Plumbing LLC",
    "doing_business_as": "Acme Plumbing",
    "organization_type": "commercial",
    "organization_legal_type": "llc",
    "country_code": "US",
    "role_type": "enterprise",
    "jurisdiction_of_incorporation": "Delaware",
    "website": "https://acmeplumbing.example.com",
    "fein": "12-3456789",
    "industry": "technology",
    "number_of_employees": "51-200",
    "organization_contact": {
      "first_name": "Sam",
      "last_name": "Owner",
      "email": "sam@acmeplumbing.example.com",
      "job_title": "Compliance Lead",
      "phone_number": "+13125550000"
    },
    "billing_contact": {
      "first_name": "Alex",
      "last_name": "Bill",
      "email": "billing@acmeplumbing.example.com",
      "phone_number": "+13125550001"
    },
    "organization_physical_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St"
    }
  }'

The response includes an id, use this enterprise ID for all subsequent API calls.

3. Activate Branded Calling on the enterprise

Branded Calling is a paid product that must be explicitly activated per enterprise. Without this step, DIR creation returns 400 with code=10015 and a detail pointing back to this endpoint.

curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/branded_calling \
  -H "Authorization: Bearer YOUR_API_KEY"

The HTTP response returns with the enterprise body. Activation completes asynchronously; if DIR creation returns 400 right after activation, wait a moment and retry. Both endpoints are idempotent. A 403 here means the Branded Calling Terms of Service hasn’t been accepted yet (back to step 1).

Activating Branded Calling is billable. See Branded Calling pricing.

4. Next steps

Create your first Display Identity Record (DIR) and submit it for vetting.

Reusing the enterprise

Register the enterprise once and reuse it for all of your Branded Calling work. The API collects all required fields up front so you don’t need to update them later.

Access requirements

All Branded Calling endpoints require a verified or enterprise-level Telnyx account. Trial and standard paid accounts cannot access these features. See Account Levels and Capabilities for details on upgrading.

​Overview

​What you need

​Quick start

​1. Accept the Branded Calling Terms of Service

​2. Create an enterprise

​3. Activate Branded Calling on the enterprise

​4. Next steps

​Reusing the enterprise

​Access requirements

Overview

What you need

Quick start

1. Accept the Branded Calling Terms of Service

2. Create an enterprise

3. Activate Branded Calling on the enterprise

4. Next steps

Reusing the enterprise

Access requirements