Sign in
Enterprises

Create an enterprise

Create the legal entity (enterprise) that represents your business on the Telnyx platform.

The response carries a server-assigned id you use for every subsequent call. An enterprise is created once and reused; the API collects all required fields up front.

Common failure modes:

  • 422 - a required field is missing or malformed (the response errors[].source.pointer names the field).
  • 409 - an enterprise with the same identifying details already exists under your account.
post/enterprises

Request body

legal_namestring required

Legal name of the enterprise.

organization_type'commercial' | 'government' | 'non_profit' required

Organization category for vetting purposes:

  • commercial - for-profit business entities (LLC, corp, partnership, sole proprietorship). Most callers fall here.
  • government - federal/state/local government bodies.
  • non_profit - registered 501(c)(3)/equivalent (incl. educational institutions, charities, religious organisations).
country_codestring required

ISO 3166-1 alpha-2 country code. Currently US and CA are supported.

role_type'enterprise' | 'bpo'

enterprise for an organization registering its own DIRs; bpo for a Business Process Outsourcer placing calls on behalf of one or more enterprises.

websitestring uri required
feinstring required

US Federal Employer Identification Number (NN-NNNNNNN) or Canadian equivalent.

industry'accounting' | 'finance' | 'billing' | 'collections' | 'business' | 'charity' | 'nonprofit' | 'communications' | 'telecom' | 'customer service' | 'support' | 'delivery' | 'shipping' | 'logistics' | 'education' | 'financial' | 'banking' | 'government' | 'public' | 'healthcare' | 'health' | 'pharmacy' | 'medical' | 'insurance' | 'legal' | 'law' | 'notifications' | 'scheduling' | 'real estate' | 'property' | 'retail' | 'ecommerce' | 'sales' | 'marketing' | 'software' | 'technology' | 'tech' | 'media' | 'surveys' | 'market research' | 'travel' | 'hospitality' | 'hotel' required

Industry classification.

number_of_employees'1-10' | '11-50' | '51-200' | '201-500' | '501-2000' | '2001-10000' | '10001+' required

Approximate headcount range. Used for vetting heuristics; pick the bucket that contains your current employee count.

organization_legal_type'corporation' | 'llc' | 'partnership' | 'nonprofit' | 'other' required

Legal-entity form. Pick the form that matches your incorporation documents:

  • corporation - C-corp or S-corp.
  • llc - limited liability company.
  • partnership - general/limited partnership.
  • nonprofit - non-profit corporation, charitable trust, or 501(c)(3)/equivalent.
  • other - anything else (sole proprietorships, government bodies, DBAs, etc.). You may be asked for additional documents during vetting.
doing_business_asstring required
jurisdiction_of_incorporationstring required
customer_referencestring

Optional free-form string the caller can attach for their own bookkeeping. Telnyx does not interpret it.

primary_business_domain_sic_codestring nullable

Optional SIC code for the primary line of business.

corporate_registration_numberstring nullable

Optional corporate-registration / company-number identifier.

professional_license_numberstring nullable

Optional professional-license number for regulated industries.

dun_bradstreet_numberstring nullable

Optional D-U-N-S Number.

Example request

{
  "legal_name": "Acme Plumbing LLC",
  "organization_type": "commercial",
  "country_code": "US",
  "role_type": "enterprise",
  "website": "https://acmeplumbing.example.com",
  "fein": "12-3456789",
  "industry": "technology",
  "number_of_employees": "51-200",
  "organization_legal_type": "llc",
  "doing_business_as": "Acme Plumbing",
  "jurisdiction_of_incorporation": "Delaware",
  "customer_reference": "internal-id-12345",
  "organization_contact": {
    "first_name": "Sam",
    "last_name": "Org",
    "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",
    "extended_address": "Suite 504"
  },
  "billing_address": {
    "country": "US",
    "administrative_area": "IL",
    "city": "Chicago",
    "postal_code": "60601",
    "street_address": "100 Main St",
    "extended_address": "Suite 504"
  }
}

Response

Enterprise created.

Example response

{
  "data": {
    "id": "4a6192a4-573d-446d-b3ce-aff9117272a6",
    "legal_name": "Acme Plumbing LLC",
    "organization_type": "commercial",
    "country_code": "US",
    "role_type": "enterprise",
    "website": "https://acmeplumbing.example.com",
    "fein": "12-3456789",
    "industry": "technology",
    "number_of_employees": "51-200",
    "organization_legal_type": "llc",
    "doing_business_as": "Acme Plumbing",
    "jurisdiction_of_incorporation": "Delaware",
    "customer_reference": "internal-id-12345",
    "organization_contact": {
      "first_name": "Sam",
      "last_name": "Org",
      "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",
      "extended_address": "Suite 504"
    },
    "billing_address": {
      "country": "US",
      "administrative_area": "IL",
      "city": "Chicago",
      "postal_code": "60601",
      "street_address": "100 Main St",
      "extended_address": "Suite 504"
    },
    "created_at": "2026-04-26T18:06:51.940749Z",
    "updated_at": "2026-04-26T18:09:24.785211Z"
  }
}

Changes

Changed in 1 of the 47 revisions of this API.17898

  • 8a8c40f458c517898See the full diff
    • ▲

      added the new required request property jurisdiction_of_incorporation

      new-required-request-property

    • ▲

      added the new required request property organization_contact/phone_number

      new-required-request-property

    • ▲

      request property industry was restricted to a list of enum values

      request-property-became-enum

    • ▲

      the billing_address request property type/format changed from object/ to /

      request-property-type-changed

    • ▲

      the website request property type/format changed from string/ to string/uri

      request-property-type-changed

    • ▲

      the data/billing_contact/email response property's maxLength was unset from 255 for the response status 201

      response-property-max-length-unset

    • ▲

      the data/billing_contact/phone_number response property's maxLength was unset from 20 for the response status 201

      response-property-max-length-unset

    • ▲

      the data/organization_contact/email response property's maxLength was unset from 255 for the response status 201

      response-property-max-length-unset

    • ▲

      the data/organization_physical_address/administrative_area response property's maxLength was unset from 100 for the response status 201

      response-property-max-length-unset

    • ▲

      the data/organization_physical_address/country response property's maxLength was unset from 100 for the response status 201

      response-property-max-length-unset

    • ▲

      the data/billing_address response's property type/format changed from object/ to / for status 201

      response-property-type-changed

    • ▲

      removed the required property data/billing_address/administrative_area from the response with the 201 status

      response-required-property-removed

    • ▲

      removed the required property data/billing_address/city from the response with the 201 status

      response-required-property-removed

    • ▲

      removed the required property data/billing_address/country from the response with the 201 status

      response-required-property-removed

    • ▲

      removed the required property data/billing_address/postal_code from the response with the 201 status

      response-required-property-removed

    • ▲

      removed the required property data/billing_address/street_address from the response with the 201 status

      response-required-property-removed

    • ▲

      removed the required property data/organization_contact/phone from the response with the 201 status

      response-required-property-removed

    • ●

      removed the request property billing_address/administrative_area

      request-property-removed

    • ●

      removed the request property billing_address/city

      request-property-removed

    • ●

      removed the request property billing_address/country

      request-property-removed

    • ●

      removed the request property billing_address/extended_address

      request-property-removed

    • ●

      removed the request property billing_address/postal_code

      request-property-removed

    • ●

      removed the request property billing_address/street_address

      request-property-removed

    • ●

      removed the request property organization_contact/phone

      request-property-removed

    • ●

      removed the optional property data/billing_address/extended_address from the response with the 201 status

      response-optional-property-removed

    • ○

      api operation id CreateEnterprise removed and replaced with createEnterprise

      api-operation-id-removed

    • ○

      the request property corporate_registration_number became nullable

      request-property-became-nullable

    • ○

      the request property dun_bradstreet_number became nullable

      request-property-became-nullable

    • ○

      the request property primary_business_domain_sic_code became nullable

      request-property-became-nullable

    • ○

      the request property professional_license_number became nullable

      request-property-became-nullable

    • ○

      added the new accounting enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new banking enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new billing enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new business enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new charity enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new collections enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new communications enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new customer service enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new delivery enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new ecommerce enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new education enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new finance enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new financial enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new government enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new health enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new healthcare enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new hospitality enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new hotel enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new insurance enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new law enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new legal enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new logistics enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new market research enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new marketing enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new media enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new medical enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new nonprofit enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new notifications enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new pharmacy enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new property enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new public enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new real estate enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new retail enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new sales enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new scheduling enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new shipping enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new software enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new support enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new surveys enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new tech enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new technology enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new telecom enum value to the request property industry

      request-property-enum-value-added

    • ○

      added the new travel enum value to the request property industry

      request-property-enum-value-added

    • ○

      the country_code request property's minLength was decreased from 2 to 0

      request-property-min-length-decreased

    • ○

      added the optional property data/branded_calling_enabled to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property data/jurisdiction_of_incorporation to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property data/number_reputation_enabled to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_codes to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_codes to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_codes to the response with the 422 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_ids to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_ids to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_ids to the response with the 422 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_labels to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_labels to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property errors/items/meta/pending_check_labels to the response with the 422 status

      response-optional-property-added

    • ○

      added the optional property errors/items/source/parameter to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property errors/items/source/parameter to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property errors/items/source/parameter to the response with the 422 status

      response-optional-property-added

    • ○

      the response optional property data/created_at became read-only for the status 201

      response-optional-property-became-read-only

    • ○

      the response optional property data/id became read-only for the status 201

      response-optional-property-became-read-only

    • ○

      the response optional property data/updated_at became read-only for the status 201

      response-optional-property-became-read-only

    • ○

      the response property data became required for the status 201

      response-property-became-required

    • ○

      the response property errors became required for the status 400

      response-property-became-required

    • ○

      the response property errors became required for the status 401

      response-property-became-required

    • ○

      the response property errors became required for the status 422

      response-property-became-required

    • ○

      the response property errors/items/detail became required for the status 400

      response-property-became-required

    • ○

      the response property errors/items/detail became required for the status 401

      response-property-became-required

    • ○

      the response property errors/items/detail became required for the status 422

      response-property-became-required

    • ○

      the response property errors/items/meta became required for the status 400

      response-property-became-required

    • ○

      the response property errors/items/meta became required for the status 401

      response-property-became-required

    • ○

      the response property errors/items/meta became required for the status 422

      response-property-became-required

    • ○

      the response property errors/items/meta/url became required for the status 400

      response-property-became-required

    • ○

      the response property errors/items/meta/url became required for the status 401

      response-property-became-required

    • ○

      the response property errors/items/meta/url became required for the status 422

      response-property-became-required

    • ○

      removed the 1-10 enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the 10001+ enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the 11-50 enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the 2001-10000 enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the 201-500 enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the 501-2000 enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the 51-200 enum value from the data/number_of_employees response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the bpo enum value from the data/role_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the commercial enum value from the data/organization_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the corporation enum value from the data/organization_legal_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the enterprise enum value from the data/role_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the government enum value from the data/organization_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the llc enum value from the data/organization_legal_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the non_profit enum value from the data/organization_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the nonprofit enum value from the data/organization_legal_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the other enum value from the data/organization_legal_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      removed the partnership enum value from the data/organization_legal_type response property for the response status 201

      response-property-enum-value-removed

    • ○

      added the required property data/organization_contact/phone_number to the response with the 201 status

      response-required-property-added

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog