telnyx 5.126.0 → 5.128.0

data/lib/telnyx/models/dir_update_response.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Models
+    # @see Telnyx::Resources::Dir#update
+    class DirUpdateResponse < Telnyx::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [Telnyx::Models::DirUpdateResponse::Data]
+      required :data, -> { Telnyx::Models::DirUpdateResponse::Data }
+
+      # @!method initialize(data:)
+      #   @param data [Telnyx::Models::DirUpdateResponse::Data]
+
+      # @see Telnyx::Models::DirUpdateResponse#data
+      class Data < Telnyx::Internal::Type::BaseModel
+        # @!attribute authorizer_email
+        #
+        #   @return [String, nil]
+        optional :authorizer_email, String, nil?: true
+
+        # @!attribute authorizer_name
+        #
+        #   @return [String, nil]
+        optional :authorizer_name, String, nil?: true
+
+        # @!attribute call_reasons
+        #
+        #   @return [Array<Telnyx::Models::DirUpdateResponse::Data::CallReason>, nil]
+        optional :call_reasons,
+                 -> { Telnyx::Internal::Type::ArrayOf[Telnyx::Models::DirUpdateResponse::Data::CallReason] }
+
+        # @!attribute certify_brand_is_accurate
+        #
+        #   @return [Boolean, nil]
+        optional :certify_brand_is_accurate, Telnyx::Internal::Type::Boolean
+
+        # @!attribute certify_ip_ownership
+        #
+        #   @return [Boolean, nil]
+        optional :certify_ip_ownership, Telnyx::Internal::Type::Boolean
+
+        # @!attribute certify_no_shaft_content
+        #
+        #   @return [Boolean, nil]
+        optional :certify_no_shaft_content, Telnyx::Internal::Type::Boolean
+
+        # @!attribute display_name
+        #
+        #   @return [String, nil]
+        optional :display_name, String
+
+        # @!attribute documents
+        #
+        #   @return [Array<Telnyx::Models::DirUpdateResponse::Data::Document>, nil]
+        optional :documents,
+                 -> { Telnyx::Internal::Type::ArrayOf[Telnyx::Models::DirUpdateResponse::Data::Document] },
+                 nil?: true
+
+        # @!attribute enterprise_id
+        #
+        #   @return [String, nil]
+        optional :enterprise_id, String
+
+        # @!attribute logo_url
+        #
+        #   @return [String, nil]
+        optional :logo_url, String, nil?: true
+
+        # @!attribute rejection_reasons
+        #   Populated when `status` is `rejected`; cleared on `/submit` or successful
+        #   approval.
+        #
+        #   @return [Array<Telnyx::Models::DirUpdateResponse::Data::RejectionReason>, nil]
+        optional :rejection_reasons,
+                 -> { Telnyx::Internal::Type::ArrayOf[Telnyx::Models::DirUpdateResponse::Data::RejectionReason] },
+                 nil?: true
+
+        # @!attribute reselling
+        #
+        #   @return [Boolean, nil]
+        optional :reselling, Telnyx::Internal::Type::Boolean
+
+        # @!attribute status
+        #   DIR lifecycle status.
+        #
+        #   - `draft` - newly created; editable; not yet submitted.
+        #   - `submitted` / `in_review` - Telnyx is reviewing.
+        #   - `verified` - approved; phone numbers may be attached.
+        #   - `rejected` - Telnyx rejected this submission; `rejection_reasons` is
+        #     populated; customer can edit and resubmit.
+        #   - `unsuccessful` - system-side error during processing; customer can edit and
+        #     resubmit.
+        #   - `suspended` - temporarily disabled (e.g. by an active infringement claim).
+        #   - `expired` - verification expired; customer must resubmit.
+        #   - `infringement_claimed` - a trademark/impersonation claim is open against this
+        #     DIR.
+        #   - `permanently_rejected` - terminal; cannot be resubmitted.
+        #
+        #   @return [Symbol, Telnyx::Models::DirUpdateResponse::Data::Status, nil]
+        optional :status, enum: -> { Telnyx::Models::DirUpdateResponse::Data::Status }
+
+        response_only do
+          # @!attribute id
+          #
+          #   @return [String, nil]
+          optional :id, String
+
+          # @!attribute created_at
+          #
+          #   @return [Time, nil]
+          optional :created_at, Time
+
+          # @!attribute expiring_at
+          #
+          #   @return [Time, nil]
+          optional :expiring_at, Time, nil?: true
+
+          # @!attribute rejected_at
+          #
+          #   @return [Time, nil]
+          optional :rejected_at, Time, nil?: true
+
+          # @!attribute submitted_at
+          #
+          #   @return [Time, nil]
+          optional :submitted_at, Time, nil?: true
+
+          # @!attribute updated_at
+          #
+          #   @return [Time, nil]
+          optional :updated_at, Time
+
+          # @!attribute verified_at
+          #
+          #   @return [Time, nil]
+          optional :verified_at, Time, nil?: true
+        end
+
+        # @!method initialize(id: nil, authorizer_email: nil, authorizer_name: nil, call_reasons: nil, certify_brand_is_accurate: nil, certify_ip_ownership: nil, certify_no_shaft_content: nil, created_at: nil, display_name: nil, documents: nil, enterprise_id: nil, expiring_at: nil, logo_url: nil, rejected_at: nil, rejection_reasons: nil, reselling: nil, status: nil, submitted_at: nil, updated_at: nil, verified_at: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Telnyx::Models::DirUpdateResponse::Data} for more details.
+        #
+        #   @param id [String]
+        #
+        #   @param authorizer_email [String, nil]
+        #
+        #   @param authorizer_name [String, nil]
+        #
+        #   @param call_reasons [Array<Telnyx::Models::DirUpdateResponse::Data::CallReason>]
+        #
+        #   @param certify_brand_is_accurate [Boolean]
+        #
+        #   @param certify_ip_ownership [Boolean]
+        #
+        #   @param certify_no_shaft_content [Boolean]
+        #
+        #   @param created_at [Time]
+        #
+        #   @param display_name [String]
+        #
+        #   @param documents [Array<Telnyx::Models::DirUpdateResponse::Data::Document>, nil]
+        #
+        #   @param enterprise_id [String]
+        #
+        #   @param expiring_at [Time, nil]
+        #
+        #   @param logo_url [String, nil]
+        #
+        #   @param rejected_at [Time, nil]
+        #
+        #   @param rejection_reasons [Array<Telnyx::Models::DirUpdateResponse::Data::RejectionReason>, nil] Populated when `status` is `rejected`; cleared on `/submit` or successful approv
+        #
+        #   @param reselling [Boolean]
+        #
+        #   @param status [Symbol, Telnyx::Models::DirUpdateResponse::Data::Status] DIR lifecycle status.
+        #
+        #   @param submitted_at [Time, nil]
+        #
+        #   @param updated_at [Time]
+        #
+        #   @param verified_at [Time, nil]
+
+        class CallReason < Telnyx::Internal::Type::BaseModel
+          # @!attribute reason
+          #
+          #   @return [String, nil]
+          optional :reason, String
+
+          response_only do
+            # @!attribute created_at
+            #
+            #   @return [Time, nil]
+            optional :created_at, Time
+          end
+
+          # @!method initialize(created_at: nil, reason: nil)
+          #   @param created_at [Time]
+          #   @param reason [String]
+        end
+
+        class Document < Telnyx::Internal::Type::BaseModel
+          # @!attribute document_id
+          #   Id returned by the Telnyx Documents API after you upload the file (upload via
+          #   `POST /v2/documents`; see https://developers.telnyx.com/api/documents).
+          #
+          #   @return [String]
+          required :document_id, String
+
+          # @!attribute document_type
+          #   Type of supporting document. Pick the closest match to what the file actually
+          #   contains; `other` triggers manual vetting and may slow approval. The matching
+          #   short_name reference list is at `GET /v2/dir/document_types`.
+          #
+          #   @return [Symbol, Telnyx::Models::DirUpdateResponse::Data::Document::DocumentType]
+          required :document_type, enum: -> { Telnyx::Models::DirUpdateResponse::Data::Document::DocumentType }
+
+          # @!attribute description
+          #
+          #   @return [String, nil]
+          optional :description, String
+
+          # @!method initialize(document_id:, document_type:, description: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Telnyx::Models::DirUpdateResponse::Data::Document} for more details.
+          #
+          #   @param document_id [String] Id returned by the Telnyx Documents API after you upload the file (upload via `P
+          #
+          #   @param document_type [Symbol, Telnyx::Models::DirUpdateResponse::Data::Document::DocumentType] Type of supporting document. Pick the closest match to what the file actually co
+          #
+          #   @param description [String]
+
+          # Type of supporting document. Pick the closest match to what the file actually
+          # contains; `other` triggers manual vetting and may slow approval. The matching
+          # short_name reference list is at `GET /v2/dir/document_types`.
+          #
+          # @see Telnyx::Models::DirUpdateResponse::Data::Document#document_type
+          module DocumentType
+            extend Telnyx::Internal::Type::Enum
+
+            LETTER_OF_AUTHORIZATION = :letter_of_authorization
+            BUSINESS_REGISTRATION = :business_registration
+            ARTICLES_OF_INCORPORATION = :articles_of_incorporation
+            TAX_DOCUMENT = :tax_document
+            EIN_LETTER = :ein_letter
+            TRADEMARK_REGISTRATION = :trademark_registration
+            WEBSITE_OWNERSHIP = :website_ownership
+            BUSINESS_LICENSE = :business_license
+            PROFESSIONAL_LICENSE = :professional_license
+            GOVERNMENT_ID = :government_id
+            UTILITY_BILL = :utility_bill
+            BANK_STATEMENT = :bank_statement
+            OTHER = :other
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
+        class RejectionReason < Telnyx::Internal::Type::BaseModel
+          # @!attribute code
+          #
+          #   @return [String, nil]
+          optional :code, String
+
+          # @!attribute detail
+          #
+          #   @return [String, nil]
+          optional :detail, String
+
+          # @!attribute message
+          #   Customer-visible free-text comment from the Telnyx vetting team. Only the first
+          #   entry of `rejection_reasons` carries this; the rest are `null`.
+          #
+          #   @return [String, nil]
+          optional :message, String, nil?: true
+
+          # @!attribute title
+          #
+          #   @return [String, nil]
+          optional :title, String
+
+          # @!method initialize(code: nil, detail: nil, message: nil, title: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Telnyx::Models::DirUpdateResponse::Data::RejectionReason} for more details.
+          #
+          #   @param code [String]
+          #
+          #   @param detail [String]
+          #
+          #   @param message [String, nil] Customer-visible free-text comment from the Telnyx vetting team. Only the first
+          #
+          #   @param title [String]
+        end
+
+        # DIR lifecycle status.
+        #
+        # - `draft` - newly created; editable; not yet submitted.
+        # - `submitted` / `in_review` - Telnyx is reviewing.
+        # - `verified` - approved; phone numbers may be attached.
+        # - `rejected` - Telnyx rejected this submission; `rejection_reasons` is
+        #   populated; customer can edit and resubmit.
+        # - `unsuccessful` - system-side error during processing; customer can edit and
+        #   resubmit.
+        # - `suspended` - temporarily disabled (e.g. by an active infringement claim).
+        # - `expired` - verification expired; customer must resubmit.
+        # - `infringement_claimed` - a trademark/impersonation claim is open against this
+        #   DIR.
+        # - `permanently_rejected` - terminal; cannot be resubmitted.
+        #
+        # @see Telnyx::Models::DirUpdateResponse::Data#status
+        module Status
+          extend Telnyx::Internal::Type::Enum
+
+          DRAFT = :draft
+          SUBMITTED = :submitted
+          IN_REVIEW = :in_review
+          VERIFIED = :verified
+          REJECTED = :rejected
+          UNSUCCESSFUL = :unsuccessful
+          SUSPENDED = :suspended
+          EXPIRED = :expired
+          INFRINGEMENT_CLAIMED = :infringement_claimed
+          PERMANENTLY_REJECTED = :permanently_rejected
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+  end
+end

data/lib/telnyx/models/enterprise_activate_branded_calling_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Models
+    # @see Telnyx::Resources::Enterprises#activate_branded_calling
+    class EnterpriseActivateBrandedCallingParams < Telnyx::Internal::Type::BaseModel
+      extend Telnyx::Internal::Type::RequestParameters::Converter
+      include Telnyx::Internal::Type::RequestParameters
+
+      # @!attribute enterprise_id
+      #
+      #   @return [String]
+      required :enterprise_id, String
+
+      # @!method initialize(enterprise_id:, request_options: {})
+      #   @param enterprise_id [String]
+      #   @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/telnyx/models/enterprise_activate_branded_calling_response.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Telnyx
+  module Models
+    # @see Telnyx::Resources::Enterprises#activate_branded_calling
+    class EnterpriseActivateBrandedCallingResponse < Telnyx::Internal::Type::BaseModel
+      # @!attribute data
+      #
+      #   @return [Telnyx::Models::EnterprisePublic]
+      required :data, -> { Telnyx::EnterprisePublic }
+
+      # @!method initialize(data:)
+      #   @param data [Telnyx::Models::EnterprisePublic]
+    end
+  end
+end

data/lib/telnyx/models/enterprise_create_params.rb

@@ -18,57 +18,61 @@ module Telnyx
       required :billing_contact, -> { Telnyx::BillingContact }
 
       # @!attribute country_code
-      #   Country code. Currently only 'US' is accepted.
+      #   ISO 3166-1 alpha-2 country code. Currently `US` and `CA` are supported.
       #
       #   @return [String]
       required :country_code, String
 
       # @!attribute doing_business_as
-      #   Primary business name / DBA name
       #
       #   @return [String]
       required :doing_business_as, String
 
       # @!attribute fein
-      #   Federal Employer Identification Number. Format: XX-XXXXXXX or 9-digit number
-      #   (minimum 9 digits).
+      #   US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent.
       #
       #   @return [String]
       required :fein, String
 
       # @!attribute industry
-      #   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
+      #   Industry classification.
+      #
+      #   @return [Symbol, Telnyx::Models::EnterpriseCreateParams::Industry]
+      required :industry, enum: -> { Telnyx::EnterpriseCreateParams::Industry }
+
+      # @!attribute jurisdiction_of_incorporation
       #
       #   @return [String]
-      required :industry, String
+      required :jurisdiction_of_incorporation, String
 
       # @!attribute legal_name
-      #   Legal name of the enterprise
+      #   Legal name of the enterprise.
       #
       #   @return [String]
       required :legal_name, String
 
       # @!attribute number_of_employees
-      #   Employee count range
+      #   Approximate headcount range. Used for vetting heuristics; pick the bucket that
+      #   contains your current employee count.
       #
       #   @return [Symbol, Telnyx::Models::EnterpriseCreateParams::NumberOfEmployees]
       required :number_of_employees, enum: -> { Telnyx::EnterpriseCreateParams::NumberOfEmployees }
 
       # @!attribute organization_contact
-      #   Organization contact information. Note: the response returns this object with
-      #   the phone field as 'phone' (not 'phone_number').
       #
       #   @return [Telnyx::Models::OrganizationContact]
       required :organization_contact, -> { Telnyx::OrganizationContact }
 
       # @!attribute organization_legal_type
-      #   Legal structure type
+      #   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.
       #
       #   @return [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationLegalType]
       required :organization_legal_type, enum: -> { Telnyx::EnterpriseCreateParams::OrganizationLegalType }
@@ -79,54 +83,61 @@ module Telnyx
       required :organization_physical_address, -> { Telnyx::PhysicalAddress }
 
       # @!attribute organization_type
-      #   Type of organization
+      #   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).
       #
       #   @return [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationType]
       required :organization_type, enum: -> { Telnyx::EnterpriseCreateParams::OrganizationType }
 
       # @!attribute website
-      #   Enterprise website URL. Accepts any string — no URL format validation enforced.
       #
       #   @return [String]
       required :website, String
 
       # @!attribute corporate_registration_number
-      #   Corporate registration number (optional)
+      #   Optional corporate-registration / company-number identifier.
       #
       #   @return [String, nil]
-      optional :corporate_registration_number, String
+      optional :corporate_registration_number, String, nil?: true
 
       # @!attribute customer_reference
-      #   Optional customer reference identifier for your own tracking
+      #   Optional free-form string the caller can attach for their own bookkeeping.
+      #   Telnyx does not interpret it.
       #
       #   @return [String, nil]
       optional :customer_reference, String
 
       # @!attribute dun_bradstreet_number
-      #   D-U-N-S Number (optional)
+      #   Optional D-U-N-S Number.
       #
       #   @return [String, nil]
-      optional :dun_bradstreet_number, String
+      optional :dun_bradstreet_number, String, nil?: true
 
       # @!attribute primary_business_domain_sic_code
-      #   SIC Code (optional)
+      #   Optional SIC code for the primary line of business.
       #
       #   @return [String, nil]
-      optional :primary_business_domain_sic_code, String
+      optional :primary_business_domain_sic_code, String, nil?: true
 
       # @!attribute professional_license_number
-      #   Professional license number (optional)
+      #   Optional professional-license number for regulated industries.
       #
       #   @return [String, nil]
-      optional :professional_license_number, String
+      optional :professional_license_number, String, nil?: true
 
       # @!attribute role_type
-      #   Role type in Branded Calling / Number Reputation services
+      #   `enterprise` for an organization registering its own DIRs; `bpo` for a Business
+      #   Process Outsourcer placing calls on behalf of one or more enterprises.
       #
       #   @return [Symbol, Telnyx::Models::EnterpriseCreateParams::RoleType, nil]
       optional :role_type, enum: -> { Telnyx::EnterpriseCreateParams::RoleType }
 
-      # @!method initialize(billing_address:, billing_contact:, country_code:, doing_business_as:, fein:, industry:, legal_name:, number_of_employees:, organization_contact:, organization_legal_type:, organization_physical_address:, organization_type:, website:, corporate_registration_number: nil, customer_reference: nil, dun_bradstreet_number: nil, primary_business_domain_sic_code: nil, professional_license_number: nil, role_type: nil, request_options: {})
+      # @!method initialize(billing_address:, billing_contact:, country_code:, doing_business_as:, fein:, industry:, jurisdiction_of_incorporation:, legal_name:, number_of_employees:, organization_contact:, organization_legal_type:, organization_physical_address:, organization_type:, website:, corporate_registration_number: nil, customer_reference: nil, dun_bradstreet_number: nil, primary_business_domain_sic_code: nil, professional_license_number: nil, role_type: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {Telnyx::Models::EnterpriseCreateParams} for more details.
       #
@@ -134,43 +145,98 @@ module Telnyx
       #
       #   @param billing_contact [Telnyx::Models::BillingContact]
       #
-      #   @param country_code [String] Country code. Currently only 'US' is accepted.
+      #   @param country_code [String] ISO 3166-1 alpha-2 country code. Currently `US` and `CA` are supported.
       #
-      #   @param doing_business_as [String] Primary business name / DBA name
+      #   @param doing_business_as [String]
       #
-      #   @param fein [String] Federal Employer Identification Number. Format: XX-XXXXXXX or 9-digit number (mi
+      #   @param fein [String] US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent.
       #
-      #   @param industry [String] Industry classification. Case-insensitive. Accepted values: accounting, finance,
+      #   @param industry [Symbol, Telnyx::Models::EnterpriseCreateParams::Industry] Industry classification.
       #
-      #   @param legal_name [String] Legal name of the enterprise
+      #   @param jurisdiction_of_incorporation [String]
       #
-      #   @param number_of_employees [Symbol, Telnyx::Models::EnterpriseCreateParams::NumberOfEmployees] Employee count range
+      #   @param legal_name [String] Legal name of the enterprise.
       #
-      #   @param organization_contact [Telnyx::Models::OrganizationContact] Organization contact information. Note: the response returns this object with th
+      #   @param number_of_employees [Symbol, Telnyx::Models::EnterpriseCreateParams::NumberOfEmployees] Approximate headcount range. Used for vetting heuristics; pick the bucket that c
       #
-      #   @param organization_legal_type [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationLegalType] Legal structure type
+      #   @param organization_contact [Telnyx::Models::OrganizationContact]
+      #
+      #   @param organization_legal_type [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationLegalType] Legal-entity form. Pick the form that matches your incorporation documents:
       #
       #   @param organization_physical_address [Telnyx::Models::PhysicalAddress]
       #
-      #   @param organization_type [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationType] Type of organization
+      #   @param organization_type [Symbol, Telnyx::Models::EnterpriseCreateParams::OrganizationType] Organization category for vetting purposes:
       #
-      #   @param website [String] Enterprise website URL. Accepts any string — no URL format validation enforced.
+      #   @param website [String]
       #
-      #   @param corporate_registration_number [String] Corporate registration number (optional)
+      #   @param corporate_registration_number [String, nil] Optional corporate-registration / company-number identifier.
       #
-      #   @param customer_reference [String] Optional customer reference identifier for your own tracking
+      #   @param customer_reference [String] Optional free-form string the caller can attach for their own bookkeeping. Telny
       #
-      #   @param dun_bradstreet_number [String] D-U-N-S Number (optional)
+      #   @param dun_bradstreet_number [String, nil] Optional D-U-N-S Number.
       #
-      #   @param primary_business_domain_sic_code [String] SIC Code (optional)
+      #   @param primary_business_domain_sic_code [String, nil] Optional SIC code for the primary line of business.
       #
-      #   @param professional_license_number [String] Professional license number (optional)
+      #   @param professional_license_number [String, nil] Optional professional-license number for regulated industries.
       #
-      #   @param role_type [Symbol, Telnyx::Models::EnterpriseCreateParams::RoleType] Role type in Branded Calling / Number Reputation services
+      #   @param role_type [Symbol, Telnyx::Models::EnterpriseCreateParams::RoleType] `enterprise` for an organization registering its own DIRs; `bpo` for a Business
       #
       #   @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}]
 
-      # Employee count range
+      # Industry classification.
+      module Industry
+        extend Telnyx::Internal::Type::Enum
+
+        ACCOUNTING = :accounting
+        FINANCE = :finance
+        BILLING = :billing
+        COLLECTIONS = :collections
+        BUSINESS = :business
+        CHARITY = :charity
+        NONPROFIT = :nonprofit
+        COMMUNICATIONS = :communications
+        TELECOM = :telecom
+        CUSTOMER_SERVICE = :"customer service"
+        SUPPORT = :support
+        DELIVERY = :delivery
+        SHIPPING = :shipping
+        LOGISTICS = :logistics
+        EDUCATION = :education
+        FINANCIAL = :financial
+        BANKING = :banking
+        GOVERNMENT = :government
+        PUBLIC = :public
+        HEALTHCARE = :healthcare
+        HEALTH = :health
+        PHARMACY = :pharmacy
+        MEDICAL = :medical
+        INSURANCE = :insurance
+        LEGAL = :legal
+        LAW = :law
+        NOTIFICATIONS = :notifications
+        SCHEDULING = :scheduling
+        REAL_ESTATE = :"real estate"
+        PROPERTY = :property
+        RETAIL = :retail
+        ECOMMERCE = :ecommerce
+        SALES = :sales
+        MARKETING = :marketing
+        SOFTWARE = :software
+        TECHNOLOGY = :technology
+        TECH = :tech
+        MEDIA = :media
+        SURVEYS = :surveys
+        MARKET_RESEARCH = :"market research"
+        TRAVEL = :travel
+        HOSPITALITY = :hospitality
+        HOTEL = :hotel
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # Approximate headcount range. Used for vetting heuristics; pick the bucket that
+      # contains your current employee count.
       module NumberOfEmployees
         extend Telnyx::Internal::Type::Enum
 
@@ -186,7 +252,15 @@ module Telnyx
         #   @return [Array<Symbol>]
       end
 
-      # Legal structure type
+      # 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.
       module OrganizationLegalType
         extend Telnyx::Internal::Type::Enum
 
@@ -200,7 +274,13 @@ module Telnyx
         #   @return [Array<Symbol>]
       end
 
-      # Type of organization
+      # 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).
       module OrganizationType
         extend Telnyx::Internal::Type::Enum
 
@@ -212,7 +292,8 @@ module Telnyx
         #   @return [Array<Symbol>]
       end
 
-      # Role type in Branded Calling / Number Reputation services
+      # `enterprise` for an organization registering its own DIRs; `bpo` for a Business
+      # Process Outsourcer placing calls on behalf of one or more enterprises.
       module RoleType
         extend Telnyx::Internal::Type::Enum