> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/number-reputation/enterprises.yml post /enterprises openapi: 3.1.0 info: title: Telnyx Number Reputation Enterprises API version: 2.0.0 description: >- Manage enterprises for Number Reputation. An enterprise represents your business entity and is the top-level resource for reputation monitoring. Register your organization once, then enable Number Reputation to start monitoring your phone numbers' spam reputation. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] paths: /enterprises: post: tags: - Enterprises summary: Create an enterprise description: >- 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. operationId: createEnterprise requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EnterpriseCreate' example: legal_name: Run 065 Debug Co organization_type: commercial country_code: US role_type: enterprise website: https://run065.example.com fein: 12-3456789 industry: technology number_of_employees: 51-200 organization_legal_type: llc doing_business_as: Run 065 Debug jurisdiction_of_incorporation: Delaware organization_contact: first_name: Sam last_name: Org email: org@run065.example.com job_title: Compliance Lead phone_number: '+13125550000' billing_contact: first_name: Alex last_name: Bill email: billing@run065.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 responses: '201': description: Enterprise created. content: application/json: schema: $ref: '#/components/schemas/EnterprisePublicWrapped' '400': $ref: '#/components/responses/branded-calling_GenericErrorResponse' '401': $ref: '#/components/responses/branded-calling_GenericErrorResponse' '422': $ref: '#/components/responses/branded-calling_GenericErrorResponse' x-codeSamples: - lang: JavaScript source: |- import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted }); const enterprise = await client.enterprises.create({ billing_address: { country: 'US', administrative_area: 'IL', city: 'Chicago', postal_code: '60601', street_address: '100 Main St', }, billing_contact: { first_name: 'Alex', last_name: 'Bill', email: 'billing@run065.example.com', phone_number: '+13125550001', }, country_code: 'US', doing_business_as: 'Run 065 Debug', fein: '12-3456789', industry: 'technology', jurisdiction_of_incorporation: 'Delaware', legal_name: 'Run 065 Debug Co', number_of_employees: '51-200', organization_contact: { first_name: 'Sam', last_name: 'Org', email: 'org@run065.example.com', job_title: 'Compliance Lead', phone_number: '+13125550000', }, organization_legal_type: 'llc', organization_physical_address: { country: 'US', administrative_area: 'IL', city: 'Chicago', postal_code: '60601', street_address: '100 Main St', }, organization_type: 'commercial', website: 'https://run065.example.com', role_type: 'enterprise', }); console.log(enterprise.data); - lang: Python source: |- import os from telnyx import Telnyx client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted ) enterprise = client.enterprises.create( billing_address={ "country": "US", "administrative_area": "IL", "city": "Chicago", "postal_code": "60601", "street_address": "100 Main St", }, billing_contact={ "first_name": "Alex", "last_name": "Bill", "email": "billing@run065.example.com", "phone_number": "+13125550001", }, country_code="US", doing_business_as="Run 065 Debug", fein="12-3456789", industry="technology", jurisdiction_of_incorporation="Delaware", legal_name="Run 065 Debug Co", number_of_employees="51-200", organization_contact={ "first_name": "Sam", "last_name": "Org", "email": "org@run065.example.com", "job_title": "Compliance Lead", "phone_number": "+13125550000", }, organization_legal_type="llc", organization_physical_address={ "country": "US", "administrative_area": "IL", "city": "Chicago", "postal_code": "60601", "street_address": "100 Main St", }, organization_type="commercial", website="https://run065.example.com", role_type="enterprise", ) print(enterprise.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tenterprise, err := client.Enterprises.New(context.TODO(), telnyx.EnterpriseNewParams{\n\t\tBillingAddress: telnyx.BillingAddressParam{\n\t\t\tCountry: \"US\",\n\t\t\tAdministrativeArea: \"IL\",\n\t\t\tCity: \"Chicago\",\n\t\t\tPostalCode: \"60601\",\n\t\t\tStreetAddress: \"100 Main St\",\n\t\t},\n\t\tBillingContact: telnyx.BillingContactParam{\n\t\t\tFirstName: \"Alex\",\n\t\t\tLastName: \"Bill\",\n\t\t\tEmail: \"billing@run065.example.com\",\n\t\t\tPhoneNumber: \"+13125550001\",\n\t\t},\n\t\tCountryCode: \"US\",\n\t\tDoingBusinessAs: \"Run 065 Debug\",\n\t\tFein: \"12-3456789\",\n\t\tIndustry: telnyx.EnterpriseNewParamsIndustryTechnology,\n\t\tJurisdictionOfIncorporation: \"Delaware\",\n\t\tLegalName: \"Run 065 Debug Co\",\n\t\tNumberOfEmployees: telnyx.EnterpriseNewParamsNumberOfEmployeesNumberOfEmployees51_200,\n\t\tOrganizationContact: telnyx.OrganizationContactParam{\n\t\t\tFirstName: \"Sam\",\n\t\t\tLastName: \"Org\",\n\t\t\tEmail: \"org@run065.example.com\",\n\t\t\tJobTitle: \"Compliance Lead\",\n\t\t\tPhoneNumber: \"+13125550000\",\n\t\t},\n\t\tOrganizationLegalType: telnyx.EnterpriseNewParamsOrganizationLegalTypeLlc,\n\t\tOrganizationPhysicalAddress: telnyx.PhysicalAddressParam{\n\t\t\tCountry: \"US\",\n\t\t\tAdministrativeArea: \"IL\",\n\t\t\tCity: \"Chicago\",\n\t\t\tPostalCode: \"60601\",\n\t\t\tStreetAddress: \"100 Main St\",\n\t\t},\n\t\tOrganizationType: telnyx.EnterpriseNewParamsOrganizationTypeCommercial,\n\t\tWebsite: \"https://run065.example.com\",\n\t\tRoleType: telnyx.EnterpriseNewParamsRoleTypeEnterprise,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", enterprise.Data)\n}\n" - lang: Java source: |- package com.telnyx.sdk.example; import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; import com.telnyx.sdk.models.enterprises.BillingAddress; import com.telnyx.sdk.models.enterprises.BillingContact; import com.telnyx.sdk.models.enterprises.EnterpriseCreateParams; import com.telnyx.sdk.models.enterprises.EnterpriseCreateResponse; import com.telnyx.sdk.models.enterprises.OrganizationContact; import com.telnyx.sdk.models.enterprises.PhysicalAddress; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); EnterpriseCreateParams params = EnterpriseCreateParams.builder() .billingAddress(BillingAddress.builder() .administrativeArea("IL") .city("Chicago") .country("US") .postalCode("60601") .streetAddress("100 Main St") .build()) .billingContact(BillingContact.builder() .email("billing@run065.example.com") .firstName("Alex") .lastName("Bill") .phoneNumber("+13125550001") .build()) .countryCode("US") .doingBusinessAs("Run 065 Debug") .fein("12-3456789") .industry(EnterpriseCreateParams.Industry.TECHNOLOGY) .jurisdictionOfIncorporation("Delaware") .legalName("Run 065 Debug Co") .numberOfEmployees(EnterpriseCreateParams.NumberOfEmployees.NUMBER_OF_EMPLOYEES_51_200) .organizationContact(OrganizationContact.builder() .email("org@run065.example.com") .firstName("Sam") .jobTitle("Compliance Lead") .lastName("Org") .phoneNumber("+13125550000") .build()) .organizationLegalType(EnterpriseCreateParams.OrganizationLegalType.LLC) .organizationPhysicalAddress(PhysicalAddress.builder() .administrativeArea("IL") .city("Chicago") .country("US") .postalCode("60601") .streetAddress("100 Main St") .build()) .organizationType(EnterpriseCreateParams.OrganizationType.COMMERCIAL) .website("https://run065.example.com") .build(); EnterpriseCreateResponse enterprise = client.enterprises().create(params); } } - lang: Ruby source: |- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") enterprise = telnyx.enterprises.create( billing_address: {administrative_area: "IL", city: "Chicago", country: "US", postal_code: "60601", street_address: "100 Main St"}, billing_contact: {email: "billing@run065.example.com", first_name: "Alex", last_name: "Bill", phone_number: "+13125550001"}, country_code: "US", doing_business_as: "Run 065 Debug", fein: "12-3456789", industry: :technology, jurisdiction_of_incorporation: "Delaware", legal_name: "Run 065 Debug Co", number_of_employees: :"51-200", organization_contact: { email: "org@run065.example.com", first_name: "Sam", job_title: "Compliance Lead", last_name: "Org", phone_number: "+13125550000" }, organization_legal_type: :llc, organization_physical_address: {administrative_area: "IL", city: "Chicago", country: "US", postal_code: "60601", street_address: "100 Main St"}, organization_type: :commercial, website: "https://run065.example.com" ) puts(enterprise) - lang: PHP source: >- enterprises->create( billingAddress: [ 'administrativeArea' => 'IL', 'city' => 'Chicago', 'country' => 'US', 'postalCode' => '60601', 'streetAddress' => '100 Main St', 'extendedAddress' => 'Suite 504', ], billingContact: [ 'email' => 'billing@run065.example.com', 'firstName' => 'Alex', 'lastName' => 'Bill', 'phoneNumber' => '+13125550001', ], countryCode: 'US', doingBusinessAs: 'Run 065 Debug', fein: '12-3456789', industry: 'technology', jurisdictionOfIncorporation: 'Delaware', legalName: 'Run 065 Debug Co', numberOfEmployees: '51-200', organizationContact: [ 'email' => 'org@run065.example.com', 'firstName' => 'Sam', 'jobTitle' => 'Compliance Lead', 'lastName' => 'Org', 'phoneNumber' => '+13125550000', ], organizationLegalType: 'llc', organizationPhysicalAddress: [ 'administrativeArea' => 'IL', 'city' => 'Chicago', 'country' => 'US', 'postalCode' => '60601', 'streetAddress' => '100 Main St', 'extendedAddress' => 'Suite 504', ], organizationType: 'commercial', website: 'https://run065.example.com', corporateRegistrationNumber: 'corporate_registration_number', customerReference: 'internal-id-12345', dunBradstreetNumber: 'dun_bradstreet_number', primaryBusinessDomainSicCode: 'primary_business_domain_sic_code', professionalLicenseNumber: 'professional_license_number', roleType: 'enterprise', ); var_dump($enterprise); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx enterprises create \ --api-key 'My API Key' \ --billing-address "{administrative_area: IL, city: Chicago, country: US, postal_code: '60601', street_address: 100 Main St}" \ --billing-contact "{email: billing@run065.example.com, first_name: Alex, last_name: Bill, phone_number: '+13125550001'}" \ --country-code US \ --doing-business-as 'Run 065 Debug' \ --fein 12-3456789 \ --industry technology \ --jurisdiction-of-incorporation Delaware \ --legal-name 'Run 065 Debug Co' \ --number-of-employees 51-200 \ --organization-contact "{email: org@run065.example.com, first_name: Sam, job_title: Compliance Lead, last_name: Org, phone_number: '+13125550000'}" \ --organization-legal-type llc \ --organization-physical-address "{administrative_area: IL, city: Chicago, country: US, postal_code: '60601', street_address: 100 Main St}" \ --organization-type commercial \ --website https://run065.example.com components: schemas: EnterpriseCreate: type: object required: - legal_name - organization_type - country_code - website - fein - industry - number_of_employees - organization_legal_type - doing_business_as - jurisdiction_of_incorporation - organization_contact - billing_contact - organization_physical_address - billing_address properties: legal_name: type: string example: Acme Plumbing LLC description: Legal name of the enterprise. minLength: 3 maxLength: 64 organization_type: type: string enum: - commercial - government - non_profit example: commercial description: >- 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_code: type: string description: >- ISO 3166-1 alpha-2 country code. Currently `US` and `CA` are supported. example: US role_type: type: string enum: - enterprise - bpo description: >- `enterprise` for an organization registering its own DIRs; `bpo` for a Business Process Outsourcer placing calls on behalf of one or more enterprises. example: enterprise default: enterprise website: type: string format: uri maxLength: 255 example: https://acmeplumbing.example.com fein: type: string description: >- US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent. example: 12-3456789 industry: type: string description: Industry classification. example: technology enum: - 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 number_of_employees: type: string enum: - 1-10 - 11-50 - 51-200 - 201-500 - 501-2000 - 2001-10000 - 10001+ example: 51-200 description: >- Approximate headcount range. Used for vetting heuristics; pick the bucket that contains your current employee count. organization_legal_type: type: string enum: - corporation - llc - partnership - nonprofit - other example: llc description: >- 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_as: type: string maxLength: 255 example: Acme Plumbing jurisdiction_of_incorporation: type: string maxLength: 255 example: Delaware customer_reference: type: string maxLength: 255 description: >- Optional free-form string the caller can attach for their own bookkeeping. Telnyx does not interpret it. example: internal-id-12345 primary_business_domain_sic_code: type: string nullable: true description: Optional SIC code for the primary line of business. corporate_registration_number: type: string nullable: true description: Optional corporate-registration / company-number identifier. professional_license_number: type: string nullable: true description: Optional professional-license number for regulated industries. dun_bradstreet_number: type: string nullable: true description: Optional D-U-N-S Number. organization_contact: $ref: '#/components/schemas/OrganizationContact' billing_contact: $ref: '#/components/schemas/BillingContact' organization_physical_address: $ref: '#/components/schemas/PhysicalAddress' billing_address: $ref: '#/components/schemas/PhysicalAddress' EnterprisePublicWrapped: type: object required: - data properties: data: $ref: '#/components/schemas/EnterprisePublic' OrganizationContact: type: object required: - first_name - last_name - email - job_title - phone_number properties: first_name: type: string maxLength: 255 example: Sam last_name: type: string maxLength: 255 example: Org email: type: string format: email example: sam@acmeplumbing.example.com job_title: type: string maxLength: 255 example: Compliance Lead phone_number: type: string description: E.164 format with leading `+`. example: '+13125550000' BillingContact: type: object required: - first_name - last_name - email - phone_number properties: first_name: type: string maxLength: 255 example: Alex last_name: type: string maxLength: 255 example: Bill email: type: string format: email example: billing@acmeplumbing.example.com phone_number: type: string description: E.164 format with leading `+`. example: '+13125550001' PhysicalAddress: type: object required: - country - administrative_area - city - postal_code - street_address properties: country: type: string description: ISO 3166-1 alpha-2 code (currently `US` or `CA`). example: US administrative_area: type: string description: State or province code (e.g. `IL`, `ON`). example: IL city: type: string maxLength: 100 example: Chicago postal_code: type: string maxLength: 20 example: '60601' street_address: type: string maxLength: 255 example: 100 Main St extended_address: type: string maxLength: 255 example: Suite 504 nullable: true EnterprisePublic: type: object properties: id: type: string format: uuid example: 4a6192a4-573d-446d-b3ce-aff9117272a6 readOnly: true legal_name: type: string example: Acme Plumbing LLC organization_type: type: string example: commercial country_code: type: string example: US role_type: type: string example: enterprise website: type: string example: https://acmeplumbing.example.com fein: type: string example: 12-3456789 industry: type: string example: technology number_of_employees: type: string example: 51-200 organization_legal_type: type: string example: llc doing_business_as: type: string example: Acme Plumbing jurisdiction_of_incorporation: type: string example: Delaware customer_reference: type: string example: internal-id-12345 primary_business_domain_sic_code: type: string nullable: true description: Optional SIC code for the primary line of business. example: null corporate_registration_number: type: string nullable: true description: Optional corporate-registration / company-number identifier. example: null professional_license_number: type: string nullable: true description: Optional professional-license number for regulated industries. example: null dun_bradstreet_number: type: string nullable: true description: Optional D-U-N-S Number issued by Dun & Bradstreet. example: null organization_contact: $ref: '#/components/schemas/OrganizationContact' billing_contact: $ref: '#/components/schemas/BillingContact' organization_physical_address: $ref: '#/components/schemas/PhysicalAddress' billing_address: $ref: '#/components/schemas/PhysicalAddress' created_at: type: string format: date-time example: '2026-04-26T18:06:51.940749Z' readOnly: true updated_at: type: string format: date-time example: '2026-04-26T18:09:24.785211Z' readOnly: true branded_calling_enabled: type: boolean description: >- True once Branded Calling has been activated on this enterprise (see `POST /enterprises/{id}/branded_calling`). number_reputation_enabled: type: boolean description: >- True once Phone Number Reputation has been enabled on this enterprise (see `POST /enterprises/{id}/reputation`). branded-calling_Errors: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/branded-calling_Error' description: List of one or more error entries. Order is not significant. description: >- Canonical Telnyx error envelope. Returned on every 4xx and 5xx response from this service. `errors` is non-empty; multiple entries indicate multiple distinct problems with the same request (e.g. one entry per invalid phone number on a bulk operation). branded-calling_Error: type: object required: - code - title - detail - meta properties: code: type: string example: '10005' description: >- Stable numeric Telnyx error catalog id. See `meta.url` for the full catalog entry. title: type: string example: Invalid parameters description: >- Short human-readable category, e.g. `Bad Request`, `Duplicate resource`, `Not Found`, `Forbidden`. Treat as advisory only - the stable identifier is `code`. detail: type: string example: field required description: >- Context-specific message describing what went wrong on this particular request. May embed offending values; do not rely on it for programmatic matching - branch on `code`. meta: type: object required: - url properties: url: type: string format: uri example: https://developers.telnyx.com/docs/overview/errors/10005 pending_check_ids: type: array items: type: string format: uuid description: >- Set on `422 vetting_checks_incomplete` responses from `/admin/dir/{id}/approve` and `/admin/phone-number-batches/approve`. Lists the still-pending vetting check ids. pending_check_codes: type: array items: type: string description: >- Codes of the pending vetting checks (e.g. `loa_signature_valid`). pending_check_labels: type: array items: type: string description: Human-readable labels of the pending vetting checks. description: >- Carries `url` linking to the Telnyx error catalog entry for this `code`. Useful for forwarding the user to documentation. source: type: object description: Optional pointer at the offending field of the request. properties: pointer: type: string example: /body/legal_name parameter: type: string example: page[size] description: >- A single entry in the canonical Telnyx error envelope. `code` is the stable Telnyx error catalog id; the human-readable explanation lives at `meta.url`. `detail` is a context-specific message; `source.pointer` (when present) names the offending field of the request. responses: branded-calling_GenericErrorResponse: description: >- An error occurred. The response carries the standard Telnyx error envelope. content: application/json: schema: $ref: '#/components/schemas/branded-calling_Errors' examples: validation_error: summary: 422 - request body failed validation value: errors: - code: '10005' title: Invalid parameters detail: field required meta: url: https://developers.telnyx.com/docs/overview/errors/10005 source: pointer: /body/legal_name bad_request: summary: 400 - request rejected by a state guard description: >- Returned when the request itself is well-formed but the resource is in a state that disallows this action (e.g. updating a DIR while it is being vetted, or deleting an enterprise that still has DIRs in vetting). value: errors: - code: '10015' title: Bad Request detail: Cannot update DIR in 'verified' status meta: url: https://developers.telnyx.com/docs/overview/errors/10015 not_found: summary: 404 - resource does not exist or is not yours value: errors: - code: '10009' title: Resource not found detail: Enterprise not found. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 conflict: summary: 409 - request conflicts with current resource state value: errors: - code: '10021' title: Resource in use detail: >- DIR has 1 active infringement claim(s). Resolve the claim before making this change. meta: url: https://developers.telnyx.com/docs/overview/errors/10021 securitySchemes: bearerAuth: scheme: bearer type: http ````