openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
  title: Telnyx Access Tokens Enterprises API
  version: 2.0.0
  x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
  url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Enterprise management for Branded Calling and Number Reputation services
  name: Enterprises
paths:
  /enterprises:
    get:
      description: Retrieve a paginated list of enterprises associated with your account.
      operationId: ListEnterprises
      parameters:
      - description: Page number (1-indexed)
        in: query
        name: page[number]
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of items per page
        in: query
        name: page[size]
        schema:
          default: 10
          maximum: 100
          minimum: 1
          type: integer
      - description: Filter by legal name (partial match)
        in: query
        name: legal_name
        schema:
          example: Acme
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterpriseListPublic'
          description: List of enterprises
        '401':
          $ref: '#/components/responses/Unauthorized'
      summary: List enterprises
      tags:
      - Enterprises
      x-latency-category: responsive
    post:
      description: 'Create a new enterprise for Branded Calling / Number Reputation services.


        Registers the enterprise in the Branded Calling / Number Reputation services, enabling it to create Display Identity Records (DIRs) or enroll in Number Reputation monitoring.


        **Required Fields:** `legal_name`, `doing_business_as`, `organization_type`, `country_code`, `website`, `fein`, `industry`, `number_of_employees`, `organization_legal_type`, `organization_contact`, `billing_contact`, `organization_physical_address`, `billing_address`'
      operationId: CreateEnterprise
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnterpriseCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterprisePublicWrapped'
          description: Enterprise created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
          description: Bad request — invalid input, validation error, or duplicate legal_name
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      summary: Create an enterprise
      tags:
      - Enterprises
      x-latency-category: responsive
  /enterprises/{enterprise_id}:
    delete:
      description: Delete an enterprise and all associated resources. This action is irreversible.
      operationId: DeleteEnterprise
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      responses:
        '204':
          description: Enterprise deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Delete an enterprise
      tags:
      - Enterprises
      x-latency-category: responsive
    get:
      description: Retrieve details of a specific enterprise by ID.
      operationId: GetEnterprise
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterprisePublicWrapped'
          description: Enterprise details
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Get an enterprise
      tags:
      - Enterprises
      x-latency-category: responsive
    put:
      description: Update enterprise information. All fields are optional — only the provided fields will be updated.
      operationId: UpdateEnterprise
      parameters:
      - $ref: '#/components/parameters/EnterpriseId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnterpriseUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterprisePublicWrapped'
          description: Enterprise updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Update an enterprise
      tags:
      - Enterprises
      x-latency-category: responsive
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Bad request — invalid input or validation error
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Unauthorized — missing or invalid API key
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Resource not found
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/branded-calling_ErrorResponse'
      description: Unprocessable entity — request structure is valid but contains semantic errors
  parameters:
    EnterpriseId:
      description: Unique identifier of the enterprise (UUID)
      in: path
      name: enterprise_id
      required: true
      schema:
        example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
        format: uuid
        type: string
  schemas:
    OrganizationContact:
      description: 'Organization contact information. Note: the response returns this object with the phone field as ''phone'' (not ''phone_number'').'
      properties:
        email:
          description: Contact's email address
          example: jane.smith@acme.com
          format: email
          maxLength: 255
          type: string
        first_name:
          description: Contact's first name
          example: Jane
          maxLength: 255
          type: string
        job_title:
          description: Contact's job title (required)
          example: VP of Engineering
          maxLength: 255
          type: string
        last_name:
          description: Contact's last name
          example: Smith
          maxLength: 255
          type: string
        phone:
          description: Contact's phone number in E.164 format
          example: '+16035551234'
          maxLength: 20
          type: string
      required:
      - first_name
      - last_name
      - email
      - job_title
      - phone
      type: object
    MetaInfo:
      properties:
        page_number:
          description: Current page number
          type: integer
        page_size:
          description: Items per page
          type: integer
        total_pages:
          description: Total number of pages
          type: integer
        total_results:
          description: Total number of results
          type: integer
      type: object
    branded-calling_ErrorResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/TelnyxError'
          type: array
      type: object
    BillingContact:
      properties:
        email:
          description: Contact's email address
          example: billing@acme.com
          format: email
          maxLength: 255
          type: string
        first_name:
          description: Contact's first name
          example: John
          maxLength: 255
          type: string
        last_name:
          description: Contact's last name
          example: Doe
          maxLength: 255
          type: string
        phone_number:
          description: Contact's phone number (10-15 digits)
          example: '15551234568'
          maxLength: 20
          type: string
      required:
      - first_name
      - last_name
      - email
      - phone_number
      type: object
    PhysicalAddress:
      properties:
        administrative_area:
          description: State or province
          example: Illinois
          maxLength: 100
          type: string
        city:
          description: City name
          example: Chicago
          maxLength: 100
          type: string
        country:
          description: Country name (e.g., United States)
          example: United States
          maxLength: 100
          type: string
        extended_address:
          description: Additional address line (suite, apt, etc.)
          example: Suite 400
          maxLength: 255
          nullable: true
          type: string
        postal_code:
          description: ZIP or postal code
          example: '60601'
          maxLength: 20
          type: string
        street_address:
          description: Street address
          example: 123 Main St
          maxLength: 255
          type: string
      required:
      - country
      - administrative_area
      - city
      - postal_code
      - street_address
      type: object
    EnterprisePublicWrapped:
      properties:
        data:
          $ref: '#/components/schemas/EnterprisePublic'
      type: object
    EnterprisePublic:
      properties:
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        billing_contact:
          $ref: '#/components/schemas/BillingContact'
        corporate_registration_number:
          description: Corporate registration number
          nullable: true
          type: string
        country_code:
          description: ISO 3166-1 alpha-2 country code
          example: US
          type: string
        created_at:
          description: When the enterprise was created
          format: date-time
          type: string
        customer_reference:
          description: Customer reference identifier
          nullable: true
          type: string
        doing_business_as:
          description: DBA name
          example: Acme
          type: string
        dun_bradstreet_number:
          description: D-U-N-S Number
          nullable: true
          type: string
        fein:
          description: Federal Employer Identification Number
          nullable: true
          type: string
        id:
          description: Unique identifier of the enterprise
          example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
          format: uuid
          type: string
        industry:
          description: Industry classification
          nullable: true
          type: string
        legal_name:
          description: Legal name of the enterprise
          example: Acme Corp Inc.
          type: string
        number_of_employees:
          description: Employee count range
          enum:
          - 1-10
          - 11-50
          - 51-200
          - 201-500
          - 501-2000
          - 2001-10000
          - 10001+
          nullable: true
          type: string
        organization_contact:
          $ref: '#/components/schemas/OrganizationContact'
        organization_legal_type:
          description: Legal structure type
          enum:
          - corporation
          - llc
          - partnership
          - nonprofit
          - other
          nullable: true
          type: string
        organization_physical_address:
          $ref: '#/components/schemas/PhysicalAddress'
        organization_type:
          description: Type of organization
          enum:
          - commercial
          - government
          - non_profit
          type: string
        primary_business_domain_sic_code:
          description: SIC Code
          nullable: true
          type: string
        professional_license_number:
          description: Professional license number
          nullable: true
          type: string
        role_type:
          description: Role type in Branded Calling / Number Reputation services
          enum:
          - enterprise
          - bpo
          type: string
        updated_at:
          description: When the enterprise was last updated
          format: date-time
          type: string
        website:
          description: Company website URL
          nullable: true
          type: string
      type: object
    EnterpriseUpdate:
      description: All fields are optional. Only provided fields will be updated.
      properties:
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        billing_contact:
          $ref: '#/components/schemas/BillingContact'
        corporate_registration_number:
          description: Corporate registration number
          maxLength: 100
          type: string
        customer_reference:
          description: Customer reference identifier
          maxLength: 255
          type: string
        doing_business_as:
          description: DBA name
          maxLength: 255
          type: string
        dun_bradstreet_number:
          description: D-U-N-S Number
          maxLength: 20
          type: string
        fein:
          description: 'Federal Employer Identification Number. Format: XX-XXXXXXX or XXXXXXXXX'
          maxLength: 20
          type: string
        industry:
          description: Industry classification
          type: string
        legal_name:
          description: Legal name of the enterprise
          maxLength: 64
          minLength: 3
          type: string
        number_of_employees:
          description: Employee count range
          enum:
          - 1-10
          - 11-50
          - 51-200
          - 201-500
          - 501-2000
          - 2001-10000
          - 10001+
          type: string
        organization_contact:
          $ref: '#/components/schemas/OrganizationContact'
        organization_legal_type:
          description: Legal structure type
          enum:
          - corporation
          - llc
          - partnership
          - nonprofit
          - other
          type: string
        organization_physical_address:
          $ref: '#/components/schemas/PhysicalAddress'
        primary_business_domain_sic_code:
          description: SIC Code
          maxLength: 10
          type: string
        professional_license_number:
          description: Professional license number
          maxLength: 100
          type: string
        website:
          description: Company website URL
          maxLength: 255
          type: string
      type: object
    EnterpriseCreate:
      properties:
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        billing_contact:
          $ref: '#/components/schemas/BillingContact'
        corporate_registration_number:
          description: Corporate registration number (optional)
          maxLength: 100
          type: string
        country_code:
          description: Country code. Currently only 'US' is accepted.
          example: US
          maxLength: 2
          minLength: 2
          type: string
        customer_reference:
          description: Optional customer reference identifier for your own tracking
          maxLength: 255
          type: string
        doing_business_as:
          description: Primary business name / DBA name
          example: Acme
          maxLength: 255
          type: string
        dun_bradstreet_number:
          description: D-U-N-S Number (optional)
          maxLength: 20
          type: string
        fein:
          description: 'Federal Employer Identification Number. Format: XX-XXXXXXX or 9-digit number (minimum 9 digits).'
          example: 12-3456789
          maxLength: 20
          type: string
        industry:
          description: 'Industry classification. Case-insensitive. Accepted values: 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'
          example: technology
          type: string
        legal_name:
          description: Legal name of the enterprise
          example: Acme Corp Inc.
          maxLength: 64
          minLength: 3
          type: string
        number_of_employees:
          description: Employee count range
          enum:
          - 1-10
          - 11-50
          - 51-200
          - 201-500
          - 501-2000
          - 2001-10000
          - 10001+
          example: 51-200
          type: string
        organization_contact:
          $ref: '#/components/schemas/OrganizationContact'
        organization_legal_type:
          description: Legal structure type
          enum:
          - corporation
          - llc
          - partnership
          - nonprofit
          - other
          example: corporation
          type: string
        organization_physical_address:
          $ref: '#/components/schemas/PhysicalAddress'
        organization_type:
          description: Type of organization
          enum:
          - commercial
          - government
          - non_profit
          example: commercial
          type: string
        primary_business_domain_sic_code:
          description: SIC Code (optional)
          example: '7372'
          maxLength: 10
          type: string
        professional_license_number:
          description: Professional license number (optional)
          maxLength: 100
          type: string
        role_type:
          default: enterprise
          description: Role type in Branded Calling / Number Reputation services
          enum:
          - enterprise
          - bpo
          type: string
        website:
          description: Enterprise website URL. Accepts any string — no URL format validation enforced.
          example: https://acme.com
          maxLength: 255
          type: string
      required:
      - legal_name
      - doing_business_as
      - organization_type
      - country_code
      - website
      - fein
      - industry
      - number_of_employees
      - organization_legal_type
      - organization_contact
      - billing_contact
      - organization_physical_address
      - billing_address
      type: object
    TelnyxError:
      properties:
        code:
          description: Telnyx error code
          example: '10015'
          type: string
        detail:
          description: Human-readable error detail
          example: User has already agreed to Terms of Service version v1.0.0
          type: string
        meta:
          properties:
            url:
              description: Link to error documentation
              format: uri
              type: string
          type: object
        source:
          description: Reference to the field that caused the error
          properties:
            pointer:
              description: JSON pointer (RFC6901) to the field that caused the error
              example: /body/organization_type
              type: string
          type: object
        title:
          description: Short error title
          example: Bad Request
          type: string
      required:
      - code
      - title
      type: object
    EnterpriseListPublic:
      properties:
        data:
          items:
            $ref: '#/components/schemas/EnterprisePublic'
          type: array
        meta:
          $ref: '#/components/schemas/MetaInfo'
      type: object
    BillingAddress:
      properties:
        administrative_area:
          description: State or province
          example: Illinois
          maxLength: 100
          type: string
        city:
          description: City name
          example: Chicago
          maxLength: 100
          type: string
        country:
          description: Country name (e.g., United States)
          example: United States
          maxLength: 100
          type: string
        extended_address:
          description: Additional address line (suite, apt, etc.)
          example: Suite 400
          maxLength: 255
          nullable: true
          type: string
        postal_code:
          description: ZIP or postal code
          example: '60601'
          maxLength: 20
          type: string
        street_address:
          description: Street address
          example: 123 Main St
          maxLength: 255
          type: string
      required:
      - country
      - administrative_area
      - city
      - postal_code
      - street_address
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    branded-calling_bearerAuth:
      description: API key passed as a Bearer token in the Authorization header
      scheme: bearer
      type: http
    oauthClientAuth:
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
      flows:
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
        clientCredentials:
          scopes:
            admin: Administrative access to Telnyx resources
          tokenUrl: https://api.telnyx.com/v2/oauth/token
      type: oauth2
    outbound-voice-profiles_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
    pronunciation-dicts_bearerAuth:
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
      scheme: bearer
      type: http
    stored-payment-transactions_bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http