telnyx 5.170.0 → 5.171.0

data/rbi/telnyx/resources/enterprises/reputation/numbers.rbi

@@ -38,8 +38,12 @@ module Telnyx
           sig do
             params(
               enterprise_id: String,
+              filter_ownership_status:
+                Telnyx::Enterprises::Reputation::ReputationOwnershipStatus::OrSymbol,
               filter_phone_number_contains: String,
               filter_phone_number_eq: String,
+              filter_source:
+                Telnyx::Enterprises::Reputation::ReputationNumberSource::OrSymbol,
               page_number: Integer,
               page_size: Integer,
               request_options: Telnyx::RequestOptions::OrHash
@@ -52,10 +56,16 @@ module Telnyx
           def list(
             # The enterprise id. Lowercase UUID.
             enterprise_id,
+            # Only numbers with this ownership status. `removed` lists the numbers that were
+            # removed, each with its `removal_reason` and `removed_at`; removed numbers are
+            # not returned otherwise.
+            filter_ownership_status: nil,
             # Partial match on phone number. Must contain at least 5 digits.
             filter_phone_number_contains: nil,
             # Exact phone-number match (E.164).
             filter_phone_number_eq: nil,
+            # Only numbers with this source.
+            filter_source: nil,
             # 1-based page number. Out-of-range values return an empty page with correct meta.
             page_number: nil,
             # Items per page. Default 10. Maximum 250; values above are clamped to 250.
@@ -65,14 +75,23 @@ module Telnyx
           end
 
           # Add up to 100 phone numbers to reputation monitoring on this enterprise. Each
-          # must be in E.164 format (`+1NPANXXXXXX` for US/CA) and belong to your Telnyx
-          # phone-number inventory.
+          # must be in E.164 format (`+1NPANXXXXXX` for US/CA). A number in your Telnyx
+          # phone-number inventory is accepted as `source: telnyx`; a number that is not is
+          # treated as hosted with another provider and must meet the requirements below.
           #
           # **Prerequisite**: reputation must already be enabled on this enterprise (see
           # `POST .../reputation`).
           #
           # **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
           # for current pricing.
+          #
+          # A phone number that is not in your Telnyx inventory is treated as a number
+          # hosted with another provider (`source: external`). It must be a US local number,
+          # and the enterprise's ownership proof must be approved first
+          # (`POST /enterprises/{enterprise_id}/reputation/external_verification`);
+          # otherwise the request fails with a 400 whose `detail` contains
+          # `external_verification_required`. Ownership of such numbers is checked every
+          # day.
           sig do
             params(
               enterprise_id: String,
@@ -110,6 +129,42 @@ module Telnyx
           )
           end
 
+          # Answer an ownership question about a phone number hosted with another provider.
+          #
+          # Send `still_own: true` to confirm you still own a number whose
+          # `ownership_status` is `pending_confirmation` or `flagged`; its status returns to
+          # `verified` and, after a carrier change, the new carrier becomes the one on
+          # record.
+          #
+          # Send `still_own: false` to report that you no longer own the number. It is
+          # removed from Number Reputation immediately, whatever its current status, and the
+          # response shows it with `ownership_status: removed`.
+          sig do
+            params(
+              phone_number: String,
+              enterprise_id: String,
+              still_own: T::Boolean,
+              evidence_document_id: String,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Enterprises::Reputation::ReputationPhoneNumberWithReputation
+            )
+          end
+          def ownership_confirm(
+            # Path param: Phone number in E.164 format (`+1NPANXXXXXX` for US/CA). The leading
+            # `+` MUST be URL-encoded as `%2B` (e.g. `%2B19493253498`).
+            phone_number,
+            # Path param: The enterprise id. Lowercase UUID.
+            enterprise_id:,
+            # Body param: `true` confirms you still own the number. `false` reports that you
+            # no longer own it and removes it from Number Reputation.
+            still_own:,
+            # Body param: Optional id of an uploaded document supporting the confirmation.
+            evidence_document_id: nil,
+            request_options: {}
+          )
+          end
+
           # Immediately refresh the stored reputation data for the listed numbers. This is
           # in addition to the periodic refresh determined by `check_frequency`. Up to 100
           # numbers per call. The response carries the kicked-off jobs; the actual refresh
@@ -136,6 +191,27 @@ module Telnyx
           )
           end
 
+          # Get the ownership status of a phone number, when it was last checked, the
+          # carrier recorded as its baseline, and the history of ownership events.
+          sig do
+            params(
+              phone_number: String,
+              enterprise_id: String,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Models::Enterprises::Reputation::NumberRetrieveOwnershipResponse
+            )
+          end
+          def retrieve_ownership(
+            # Phone number in E.164 format (`+1NPANXXXXXX` for US/CA). The leading `+` MUST be
+            # URL-encoded as `%2B` (e.g. `%2B19493253498`).
+            phone_number,
+            # The enterprise id. Lowercase UUID.
+            enterprise_id:,
+            request_options: {}
+          )
+          end
+
           # @api private
           sig { params(client: Telnyx::Client).returns(T.attached_class) }
           def self.new(client:)

data/rbi/telnyx/resources/enterprises/reputation.rbi

@@ -17,6 +17,14 @@ module Telnyx
         sig { returns(Telnyx::Resources::Enterprises::Reputation::Remediation) }
         attr_reader :remediation
 
+        # Phone-number reputation monitoring (spam-score lookup and tracking).
+        sig do
+          returns(
+            Telnyx::Resources::Enterprises::Reputation::ExternalVerification
+          )
+        end
+        attr_reader :external_verification
+
         # Phone Number Reputation tracks how your outbound caller-IDs are perceived (spam
         # risk, engagement, etc.) across the call-screening ecosystem. This endpoint reads
         # the enterprise-level settings: whether the product is enabled, the refresh
@@ -116,6 +124,27 @@ module Telnyx
         )
         end
 
+        # Set the HTTPS URL that receives number-ownership events for this enterprise:
+        # `number_reputation.number.flagged`, `number_reputation.number.removed` and
+        # `number_reputation.external_verification.status_changed`. Send
+        # `webhook_url: null` to stop receiving them.
+        sig do
+          params(
+            enterprise_id: String,
+            webhook_url: T.nilable(String),
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Enterprises::EnterpriseReputationPublicWrapped)
+        end
+        def update_webhook(
+          # The enterprise id. Lowercase UUID.
+          enterprise_id,
+          # HTTPS URL on a publicly routable host. Send `null` to stop receiving
+          # number-ownership events.
+          webhook_url:,
+          request_options: {}
+        )
+        end
+
         # @api private
         sig { params(client: Telnyx::Client).returns(T.attached_class) }
         def self.new(client:)

data/rbi/telnyx/resources/enterprises/verify_email.rbi

@@ -0,0 +1,64 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class Enterprises
+      # Verify ownership of a DIR's authorizer email. A short code is emailed and
+      # confirmed; the email must be verified before references can be submitted.
+      class VerifyEmail
+        # Email a 6-digit code to the enterprise account's contact email to confirm
+        # ownership of that address.
+        #
+        # A BPO (Business Process Outsourcer) account has no DIR, so it proves ownership
+        # of its own contact email here rather than through a DIR. A BPO account cannot be
+        # approved for use until this contact email is verified.
+        #
+        # The code expires in 15 minutes. Requesting a new code invalidates any previous
+        # one. Resends are rate limited (a short cooldown plus a daily cap). Submit the
+        # code to `POST /enterprises/{enterprise_id}/verify_email/confirm`.
+        sig do
+          params(
+            enterprise_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(
+            Telnyx::Enterprises::EnterpriseEmailVerificationStatusWrapped
+          )
+        end
+        def create(
+          # The enterprise id. Lowercase UUID.
+          enterprise_id,
+          request_options: {}
+        )
+        end
+
+        # Submit the 6-digit code that was emailed to the enterprise account's contact
+        # email. On success the contact email is marked verified.
+        #
+        # For security, any failure (wrong, expired, already-used, or too many attempts)
+        # returns the same generic message.
+        sig do
+          params(
+            enterprise_id: String,
+            code: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(
+            Telnyx::Enterprises::EnterpriseEmailVerificationStatusWrapped
+          )
+        end
+        def confirm(
+          # The enterprise id. Lowercase UUID.
+          enterprise_id,
+          # The 6-digit code sent to the enterprise account's contact email.
+          code:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/enterprises.rbi

@@ -13,6 +13,11 @@ module Telnyx
       sig { returns(Telnyx::Resources::Enterprises::Dir) }
       attr_reader :dir
 
+      # Verify ownership of a DIR's authorizer email. A short code is emailed and
+      # confirmed; the email must be verified before references can be submitted.
+      sig { returns(Telnyx::Resources::Enterprises::VerifyEmail) }
+      attr_reader :verify_email
+
       # Create the legal entity (enterprise) that represents your business on the Telnyx
       # platform.
       #
@@ -59,13 +64,20 @@ module Telnyx
         billing_contact:,
         # ISO 3166-1 alpha-2 country code. Currently `US` and `CA` are supported.
         country_code:,
+        # The trade name your business operates under if it is different from your legal
+        # name, also called a Doing Business As (DBA) name. Leave blank if you only use
+        # your legal name.
         doing_business_as:,
         # US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent.
         fein:,
-        # Industry classification.
+        # The industry your business operates in. Choose the closest match from the list;
+        # if your value is not accepted, pick the nearest category.
         industry:,
+        # The state, province, or country where your business was legally incorporated,
+        # for example Delaware.
         jurisdiction_of_incorporation:,
-        # Legal name of the enterprise.
+        # Your business's full registered legal name, exactly as it appears on your
+        # incorporation or tax documents, 3 to 64 characters.
         legal_name:,
         # Approximate headcount range. Used for vetting heuristics; pick the bucket that
         # contains your current employee count.
@@ -90,20 +102,35 @@ module Telnyx
         # - `non_profit` - registered 501(c)(3)/equivalent (incl. educational
         #   institutions, charities, religious organisations).
         organization_type:,
+        # Your business's public website address, including https://. Leave blank if your
+        # business has no website.
         website:,
-        # Optional corporate-registration / company-number identifier.
+        # The official number your company received when it was legally registered or
+        # incorporated (for example from your state or national business registry). It is
+        # on your certificate of incorporation.
         corporate_registration_number: nil,
-        # Optional free-form string the caller can attach for their own bookkeeping.
-        # Telnyx does not interpret it.
+        # Your own label for this account. Enter any reference that helps you find it in
+        # your records. Telnyx does not use it during vetting.
         customer_reference: nil,
-        # Optional D-U-N-S Number.
+        # Your optional 9-digit D-U-N-S Number issued by Dun & Bradstreet, a unique
+        # identifier for your business. Leave blank if you do not have one.
         dun_bradstreet_number: nil,
-        # Optional SIC code for the primary line of business.
+        # The 4-digit Standard Industrial Classification code for your main line of
+        # business, which tells us what industry you operate in. Look it up in the SIC
+        # code directory if you are unsure.
         primary_business_domain_sic_code: nil,
-        # Optional professional-license number for regulated industries.
+        # If your business operates under a professional license (for example legal,
+        # medical, or financial services), enter the license number issued by the
+        # licensing authority. Leave blank if it does not apply.
         professional_license_number: nil,
-        # `enterprise` for an organization registering its own DIRs; `bpo` for a Business
-        # Process Outsourcer placing calls on behalf of one or more enterprises.
+        # `enterprise` for an organization registering its own DIRs (the default, and the
+        # right choice when the calls display your own brand). `bpo` for a Business
+        # Process Outsourcer: a call center that places calls on behalf of other
+        # enterprises and displays their brand. A `bpo` enterprise describes the call
+        # center itself and cannot own a DIR. Each client the call center calls for gets
+        # its own `enterprise` in the same account, with the client's DIR under it; that
+        # DIR is then linked to the `bpo` enterprise through `bpo_authorizations`. Fixed
+        # at creation.
         role_type: nil,
         request_options: {}
       )
@@ -129,6 +156,21 @@ module Telnyx
       # `updated_at`, status fields, `organization_type`, `country_code`, `role_type`)
       # cannot be changed: including any of them in the body is rejected with
       # `400 Bad Request` (`Field 'X' is not allowed in this request`).
+      #
+      # For an approved BPO enterprise (`role_type` `bpo`), changing any identity field
+      # (legal name, DBA, website, FEIN, industry, number of employees, physical
+      # address, organization contact, D-U-N-S number, legal type, SIC code, corporate
+      # registration number, professional license number, or jurisdiction of
+      # incorporation) resets `bpo_verification_status` to `pending` for re-approval and
+      # sets every DIR authorization for that BPO to `rejected`. After re-approval, link
+      # it again with a newly signed LOA (a new `loa_document_id`); resending the old
+      # one keeps the authorization `rejected`. Re-sending an unchanged value does not
+      # reset anything.
+      #
+      # If Number Reputation is enabled on the enterprise, `legal_name`,
+      # `doing_business_as`, `website`, `fein`, `industry`, `number_of_employees`,
+      # `organization_physical_address`, `organization_contact`, and
+      # `dun_bradstreet_number` cannot be changed: the request is rejected with `400`.
       sig do
         params(
           enterprise_id: String,
@@ -157,22 +199,56 @@ module Telnyx
         enterprise_id,
         billing_address: nil,
         billing_contact: nil,
+        # The official number your company received when it was legally registered or
+        # incorporated (for example from your state or national business registry). It is
+        # on your certificate of incorporation.
         corporate_registration_number: nil,
+        # Your own label for this account. Enter any reference that helps you find it in
+        # your records. Telnyx does not use it during vetting.
         customer_reference: nil,
+        # The trade name your business operates under if it is different from your legal
+        # name, also called a Doing Business As (DBA) name. Leave blank if you only use
+        # your legal name.
         doing_business_as: nil,
+        # Your optional 9-digit D-U-N-S Number issued by Dun & Bradstreet, a unique
+        # identifier for your business. Leave blank if you do not have one.
         dun_bradstreet_number: nil,
+        # US Federal Employer Identification Number (`NN-NNNNNNN`) or Canadian equivalent.
         fein: nil,
+        # The industry your business operates in. Choose the closest match from the list;
+        # if your value is not accepted, pick the nearest category.
         industry: nil,
-        # Updated state/province/country of incorporation. Optional on update.
+        # The state, province, or country where your business was legally incorporated,
+        # for example Delaware.
         jurisdiction_of_incorporation: nil,
-        # Legal name of the enterprise.
+        # Your business's full registered legal name, exactly as it appears on your
+        # incorporation or tax documents, 3 to 64 characters.
         legal_name: nil,
+        # Approximate headcount range. Used for vetting heuristics; pick the bucket that
+        # contains your current employee count.
         number_of_employees: nil,
         organization_contact: nil,
+        # 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.
         organization_legal_type: nil,
         organization_physical_address: nil,
+        # The 4-digit Standard Industrial Classification code for your main line of
+        # business, which tells us what industry you operate in. Look it up in the SIC
+        # code directory if you are unsure.
         primary_business_domain_sic_code: nil,
+        # If your business operates under a professional license (for example legal,
+        # medical, or financial services), enter the license number issued by the
+        # licensing authority. Leave blank if it does not apply.
         professional_license_number: nil,
+        # Your business's public website address, including https://. Leave blank if your
+        # business has no website.
         website: nil,
         request_options: {}
       )
@@ -183,6 +259,8 @@ module Telnyx
       sig do
         params(
           filter_legal_name_contains: String,
+          filter_role_type:
+            Telnyx::EnterpriseListParams::FilterRoleType::OrSymbol,
           legal_name: String,
           page_number: Integer,
           page_size: Integer,
@@ -194,6 +272,9 @@ module Telnyx
       def list(
         # Case-insensitive partial match on legal name.
         filter_legal_name_contains: nil,
+        # Only return enterprises of this type: `bpo` for call-center (BPO) enterprises,
+        # `enterprise` for normal enterprises. Omit to return both.
+        filter_role_type: nil,
         # Filter by legal name (partial match).
         legal_name: nil,
         # 1-based page number. Out-of-range values return an empty page with correct meta.
@@ -227,14 +308,15 @@ module Telnyx
       )
       end
 
-      # Branded Calling is a paid product that must be activated on each enterprise.
-      # Activation is idempotent:
+      # Branded Calling must be activated on each enterprise. Activation is idempotent:
       #
-      # - First call: marks the enterprise as activated and begins onboarding it with
-      #   the Branded Calling platform asynchronously. Returns `200` with
+      # - First call: marks the enterprise as activated, effective immediately; you can
+      #   create a DIR right away. The enterprise is registered with the Branded Calling
+      #   platform later, after its first DIR is approved. Returns `200` with
       #   `branded_calling_enabled: true`.
       # - Re-call after success: no-op, returns the same enterprise body.
-      # - Re-call after a prior failure: re-queues onboarding, returns `200`.
+      # - Re-call after a failed registration: re-queues the registration, returns
+      #   `200`.
       #
       # Prerequisite: the calling user must have agreed to the Branded Calling Terms of
       # Service (`POST /terms_of_service/branded_calling/agree`). Without that, this
@@ -242,11 +324,15 @@ module Telnyx
       #
       # Failure modes:
       #
+      # - `400` - the account has no available credit. Add funds and retry.
+      # - `400` - the enterprise is not in the United States. Branded Calling is
+      #   currently available only to US enterprises.
       # - `403` - Branded Calling Terms of Service not accepted.
       # - `404` - enterprise does not exist or does not belong to your account.
       #
-      # **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
-      # for current pricing.
+      # **Pricing:** Activation itself is free, but the account must have available
+      # credit. Branded Calling fees are charged per DIR and per branded call. See
+      # https://telnyx.com/pricing/branded-calling for current pricing.
       sig do
         params(
           enterprise_id: String,

data/rbi/telnyx/resources/llm_token_gateway/spend.rbi

@@ -0,0 +1,116 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class LlmTokenGateway
+      # Manage and report AI Gateway usage.
+      class Spend
+        # Return request-level usage history for the authenticated account. Supply both
+        # UTC dates or neither; omitting both returns the previous full UTC day. Dates use
+        # a half-open range [start_date, end_date) of at most 31 days. Cost reflects
+        # budget reference rates, not invoice charges. Unknown spend is excluded and
+        # reported separately. The report snapshot supports at most 10,000 matching
+        # requests, independently of page size. Exceeding this bound returns HTTP 503
+        # without partial results. Narrow the date range or resource filters before
+        # retrying. A failed report must not be interpreted as zero usage. Request tags
+        # can filter either report and metadata:<key> can group the summary.
+        sig do
+          params(
+            end_date: Date,
+            end_user_id: String,
+            metadata: T::Hash[Symbol, String],
+            page_number: Integer,
+            page_size: Integer,
+            page_snapshot: String,
+            start_date: Date,
+            token_group_id: String,
+            token_key_id: String,
+            token_user_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(
+            Telnyx::Models::LlmTokenGateway::SpendRetrieveEventsResponse
+          )
+        end
+        def retrieve_events(
+          end_date: nil,
+          end_user_id: nil,
+          # Request tag filters as metadata[<key>]=<value>, at most 5, combined with AND. A
+          # value matches the tag's text form exactly (booleans as true/false, integers in
+          # decimal), so metadata[flag]=true matches both boolean true and the string
+          # "true". Keys are case-sensitive; reserved-prefix keys are rejected. Unindexed:
+          # bounded by the account, the date range and the report timeout.
+          metadata: nil,
+          page_number: nil,
+          page_size: nil,
+          # Required after page 1; account/filter-bound 15-minute stable snapshot;
+          # expired/mismatch 409.
+          page_snapshot: nil,
+          start_date: nil,
+          token_group_id: nil,
+          token_key_id: nil,
+          token_user_id: nil,
+          request_options: {}
+        )
+        end
+
+        # Return request counts, token counts and reference spend grouped by one
+        # attribution dimension. Both UTC dates and group_by are required. Dates use a
+        # half-open range [start_date, end_date) of at most 31 days. Cost reflects budget
+        # reference rates, not invoice charges. Unknown spend is excluded and reported
+        # separately. The report snapshot supports at most 10,000 matching requests,
+        # independently of page size. Exceeding this bound returns HTTP 503 without
+        # partial results. Narrow the date range or resource filters before retrying. A
+        # failed report must not be interpreted as zero usage. Request tags can filter
+        # either report and metadata:<key> can group the summary.
+        sig do
+          params(
+            end_date: Date,
+            group_by:
+              T.any(Telnyx::LlmTokenGateway::SpendGroupBy::OrSymbol, String),
+            start_date: Date,
+            end_user_id: String,
+            metadata: T::Hash[Symbol, String],
+            page_number: Integer,
+            page_size: Integer,
+            page_snapshot: String,
+            token_group_id: String,
+            token_key_id: String,
+            token_user_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(
+            Telnyx::Models::LlmTokenGateway::SpendRetrieveSummaryResponse
+          )
+        end
+        def retrieve_summary(
+          end_date:,
+          # A scope, or metadata:<key> to group by one request tag's text-form value;
+          # requests without the key form one group with a null dimension_id.
+          group_by:,
+          start_date:,
+          end_user_id: nil,
+          # Request tag filters as metadata[<key>]=<value>, at most 5, combined with AND. A
+          # value matches the tag's text form exactly (booleans as true/false, integers in
+          # decimal), so metadata[flag]=true matches both boolean true and the string
+          # "true". Keys are case-sensitive; reserved-prefix keys are rejected. Unindexed:
+          # bounded by the account, the date range and the report timeout.
+          metadata: nil,
+          page_number: nil,
+          page_size: nil,
+          # Required after page 1; account/filter-bound 15-minute stable snapshot;
+          # expired/mismatch 409.
+          page_snapshot: nil,
+          token_group_id: nil,
+          token_key_id: nil,
+          token_user_id: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end