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` (a business registering its own DIRs, the default and the right choice for almost everyone) or `bpo` (a call center that places calls on behalf of another business and cannot own DIRs). Fixed at creation. 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).

Set role_type to bpo only for the enterprise that describes a call center (a Business Process Outsourcer, or BPO) that places calls on behalf of other businesses. That BPO enterprise holds the call center’s own details and cannot have a DIR. Each client the call center calls for gets its own normal enterprise (leave role_type unset) and a DIR under it, created in the same account. For example, if the call center Dial Partners LLC calls for Maple Ridge Insurance, its BPO enterprise uses "legal_name": "Dial Partners LLC" and Dial Partners’ own FEIN, contact, and address, while Maple Ridge’s company details go on a separate Maple Ridge enterprise, and its display name, logo, and phone numbers go on a DIR under that enterprise. If your calls display your own business’s name, you do not need a BPO enterprise. See BPO (Business Process Outsourcer) support for the full flow.

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": "[email protected]",
      "job_title": "Compliance Lead",
      "phone_number": "+13125550000"
    },
    "billing_contact": {
      "first_name": "Alex",
      "last_name": "Bill",
      "email": "[email protected]",
      "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 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 takes effect immediately, so you can create a DIR right away; your enterprise is registered on the Branded Calling network after its first DIR is approved. The call is idempotent. A 403 here means the Branded Calling Terms of Service hasn’t been accepted yet (back to step 1).

Activating Branded Calling is free. Your account must have available credit, or the request is rejected with 400. The Branded Calling fees are charged per DIR and per branded call. 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