telnyx 7.25.0 → 7.27.0

package/src/resources/enterprises/dir.ts

@@ -67,10 +67,16 @@ export class Dir extends APIResource {
    *
    * **Failure modes**
    *
-   * - `422` - validation error; `errors[].source.pointer` names the offending field.
-   * - `403` - Branded Calling not activated on this enterprise (see
+   * - `400` - validation error; `errors[].source.pointer` names the offending field.
+   * - `400` - a certification field is not `true`.
+   * - `400` - Branded Calling not activated on this enterprise (see
    *   `POST /enterprises/{id}/branded_calling`).
+   * - `400` - the enterprise is a BPO enterprise (`role_type` `bpo`), which cannot
+   *   own a DIR.
+   * - `400` - a `bpo_authorizations` entry is not an approved BPO enterprise in your
+   *   account, or its `loa_document_id` could not be validated.
    * - `404` - enterprise does not exist or does not belong to your account.
+   * - `503` - the document check is temporarily unavailable; retry.
    *
    * @example
    * ```ts

package/src/resources/enterprises/enterprises.ts

@@ -17,6 +17,7 @@ import {
   ReputationCheckFrequency,
   ReputationEnableParams,
   ReputationUpdateFrequencyParams,
+  ReputationUpdateWebhookParams,
 } from './reputation/reputation';
 import { APIPromise } from '../../core/api-promise';
 import { DefaultFlatPagination, type DefaultFlatPaginationParams, PagePromise } from '../../core/pagination';
@@ -237,11 +238,13 @@ export class Enterprises extends APIResource {
   /**
    * 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
@@ -885,6 +888,7 @@ export declare namespace Enterprises {
     type ReputationCheckFrequency as ReputationCheckFrequency,
     type ReputationEnableParams as ReputationEnableParams,
     type ReputationUpdateFrequencyParams as ReputationUpdateFrequencyParams,
+    type ReputationUpdateWebhookParams as ReputationUpdateWebhookParams,
   };
 
   export { Dir as Dir, type DirListParams as DirListParams, type DirCreateParams as DirCreateParams };

package/src/resources/enterprises/index.ts

@@ -21,6 +21,7 @@ export {
   type ReputationCheckFrequency,
   type ReputationEnableParams,
   type ReputationUpdateFrequencyParams,
+  type ReputationUpdateWebhookParams,
 } from './reputation/index';
 export {
   VerifyEmail,

package/src/resources/enterprises/reputation/external-verification.ts

@@ -0,0 +1,125 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ExternalVerificationAPI from './external-verification';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Phone-number reputation monitoring (spam-score lookup and tracking).
+ */
+export class ExternalVerification extends APIResource {
+  /**
+   * Get the review status of the enterprise's ownership proof for phone numbers
+   * hosted with another provider. Returns 404 when no proof has been submitted.
+   *
+   * @example
+   * ```ts
+   * const externalVerificationWrapped =
+   *   await client.enterprises.reputation.externalVerification.list(
+   *     '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *   );
+   * ```
+   */
+  list(enterpriseID: string, options?: RequestOptions): APIPromise<ExternalVerificationWrapped> {
+    return this._client.get(path`/enterprises/${enterpriseID}/reputation/external_verification`, options);
+  }
+
+  /**
+   * Request permission to add phone numbers that the enterprise owns but that are
+   * hosted with another provider. Submit one or more uploaded documents proving
+   * ownership, such as a carrier invoice or account statement. The request is
+   * reviewed once per enterprise. While it is `pending` or `rejected` you can submit
+   * again to replace the documents; once `approved` it cannot be changed.
+   *
+   * @example
+   * ```ts
+   * const externalVerificationWrapped =
+   *   await client.enterprises.reputation.externalVerification.create(
+   *     '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *     {
+   *       document_ids: [
+   *         '2a7e8337-e803-4057-a4ae-26c40eb0bc6c',
+   *       ],
+   *     },
+   *   );
+   * ```
+   */
+  create(
+    enterpriseID: string,
+    body: ExternalVerificationCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<ExternalVerificationWrapped> {
+    return this._client.post(path`/enterprises/${enterpriseID}/reputation/external_verification`, {
+      body,
+      ...options,
+    });
+  }
+}
+
+/**
+ * Review state of the ownership proof that allows adding phone numbers hosted with
+ * another provider.
+ */
+export type ExternalVerificationStatus = 'pending' | 'approved' | 'rejected';
+
+export interface ExternalVerificationWrapped {
+  data: ExternalVerificationWrapped.Data;
+}
+
+export namespace ExternalVerificationWrapped {
+  export interface Data {
+    /**
+     * The ownership-proof documents on file.
+     */
+    document_ids?: Array<string>;
+
+    enterprise_id?: string;
+
+    /**
+     * The phone numbers you listed with the documents.
+     */
+    phone_numbers?: Array<string>;
+
+    /**
+     * Why the proof was rejected. Set only when `status` is `rejected`.
+     */
+    rejection_reason?: string | null;
+
+    reviewed_at?: string | null;
+
+    /**
+     * Review state of the ownership proof that allows adding phone numbers hosted with
+     * another provider.
+     */
+    status?: ExternalVerificationAPI.ExternalVerificationStatus;
+
+    submitted_at?: string | null;
+  }
+}
+
+export interface ExternalVerificationCreateParams {
+  /**
+   * Ids of uploaded documents (Documents API) proving the enterprise owns its phone
+   * numbers hosted with another provider, for example a carrier invoice or account
+   * statement.
+   */
+  document_ids: Array<string>;
+
+  /**
+   * Optional. The phone numbers hosted with another provider that the documents
+   * cover, in E.164 format. Shown to the reviewer to match the documents to your
+   * numbers; you can still add numbers that are not listed here, and each is checked
+   * on its own.
+   */
+  phone_numbers?: Array<string>;
+}
+
+export declare namespace ExternalVerification {
+  export {
+    type ExternalVerificationStatus as ExternalVerificationStatus,
+    type ExternalVerificationWrapped as ExternalVerificationWrapped,
+    type ExternalVerificationCreateParams as ExternalVerificationCreateParams,
+  };
+}

package/src/resources/enterprises/reputation/index.ts

@@ -1,18 +1,29 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  ExternalVerification,
+  type ExternalVerificationStatus,
+  type ExternalVerificationWrapped,
+  type ExternalVerificationCreateParams,
+} from './external-verification';
 export { Loa, type AgentInput, type LoaUpdateParams, type LoaRenderParams } from './loa';
 export {
   Numbers,
+  type ReputationNumberSource,
+  type ReputationOwnershipStatus,
   type ReputationPhoneNumber,
   type ReputationPhoneNumberList,
   type ReputationPhoneNumberListWithReputation,
   type ReputationPhoneNumberWithReputation,
   type NumberRefreshResponse,
+  type NumberRetrieveOwnershipResponse,
   type NumberListParams,
   type NumberAssociateParams,
   type NumberDisassociateParams,
   type NumberRetrieveParams,
   type NumberRefreshParams,
+  type NumberRetrieveOwnershipParams,
+  type NumberOwnershipConfirmParams,
   type ReputationPhoneNumbersDefaultFlatPagination,
 } from './numbers';
 export {
@@ -34,4 +45,5 @@ export {
   type ReputationCheckFrequency,
   type ReputationEnableParams,
   type ReputationUpdateFrequencyParams,
+  type ReputationUpdateWebhookParams,
 } from './reputation';

package/src/resources/enterprises/reputation/loa.ts

@@ -71,8 +71,9 @@ export class Loa extends APIResource {
 }
 
 /**
- * Third-party reseller / partner managing the enterprise's phone numbers. Omit
- * when the enterprise works directly with Telnyx.
+ * Third-party reseller / partner managing the enterprise's phone numbers on its
+ * behalf, such as a call center (BPO) acting for a client. Omit when the
+ * enterprise manages its own numbers.
  */
 export interface AgentInput {
   /**

package/src/resources/enterprises/reputation/numbers.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../core/resource';
+import * as NumbersAPI from './numbers';
 import * as Shared from '../../shared';
 import * as EnterprisesAPI from '../enterprises';
 import { APIPromise } from '../../../core/api-promise';
@@ -46,8 +47,9 @@ export class Numbers extends APIResource {
 
   /**
    * 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`).
@@ -55,6 +57,14 @@ export class Numbers extends APIResource {
    * **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.
+   *
    * @example
    * ```ts
    * const reputationPhoneNumberList =
@@ -152,27 +162,161 @@ export class Numbers extends APIResource {
       ...options,
     });
   }
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.enterprises.reputation.numbers.retrieveOwnership(
+   *     '+19493253498',
+   *     {
+   *       enterprise_id: '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *     },
+   *   );
+   * ```
+   */
+  retrieveOwnership(
+    phoneNumber: string,
+    params: NumberRetrieveOwnershipParams,
+    options?: RequestOptions,
+  ): APIPromise<NumberRetrieveOwnershipResponse> {
+    const { enterprise_id } = params;
+    return this._client.get(
+      path`/enterprises/${enterprise_id}/reputation/numbers/${phoneNumber}/ownership`,
+      options,
+    );
+  }
+
+  /**
+   * 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`.
+   *
+   * @example
+   * ```ts
+   * const reputationPhoneNumberWithReputation =
+   *   await client.enterprises.reputation.numbers.ownershipConfirm(
+   *     '+19493253498',
+   *     {
+   *       enterprise_id: '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *       still_own: true,
+   *     },
+   *   );
+   * ```
+   */
+  ownershipConfirm(
+    phoneNumber: string,
+    params: NumberOwnershipConfirmParams,
+    options?: RequestOptions,
+  ): APIPromise<ReputationPhoneNumberWithReputation> {
+    const { enterprise_id, ...body } = params;
+    return this._client.post(
+      path`/enterprises/${enterprise_id}/reputation/numbers/${phoneNumber}/ownership_confirm`,
+      { body, ...options },
+    );
+  }
 }
 
 export type ReputationPhoneNumbersDefaultFlatPagination = DefaultFlatPagination<ReputationPhoneNumber>;
 
+/**
+ * Where the phone number is hosted. `telnyx`: in your Telnyx inventory.
+ * `external`: a number you own that is hosted with another provider.
+ */
+export type ReputationNumberSource = 'telnyx' | 'external';
+
+/**
+ * Result of ongoing ownership checks. `verified`: the number is with the carrier
+ * on record. `pending_confirmation`: the number's carrier changed, or a periodic
+ * ownership re-verification is due; confirm you still own it before `confirm_by`.
+ * `flagged`: a periodic re-verification went unanswered; the number stays
+ * monitored and is not removed, but confirm ownership
+ * (`POST .../ownership_confirm`) to return it to `verified`. `removed`: the number
+ * is no longer monitored; returned by `POST .../ownership_confirm` with
+ * `still_own: false`, and when listing numbers with
+ * `filter[ownership_status]=removed`.
+ */
+export type ReputationOwnershipStatus = 'verified' | 'flagged' | 'pending_confirmation' | 'removed';
+
 export interface ReputationPhoneNumber {
   id?: string;
 
+  /**
+   * Deadline to confirm you still own the number. Set only while `ownership_status`
+   * is `pending_confirmation`.
+   */
+  confirm_by?: string | null;
+
   created_at?: string;
 
   enterprise_id?: string;
 
+  /**
+   * Why the number's ownership was flagged. `carrier_changed` when an ownership
+   * check found the number with a different carrier.
+   */
+  flag_reason?: string | null;
+
+  /**
+   * Result of ongoing ownership checks. `verified`: the number is with the carrier
+   * on record. `pending_confirmation`: the number's carrier changed, or a periodic
+   * ownership re-verification is due; confirm you still own it before `confirm_by`.
+   * `flagged`: a periodic re-verification went unanswered; the number stays
+   * monitored and is not removed, but confirm ownership
+   * (`POST .../ownership_confirm`) to return it to `verified`. `removed`: the number
+   * is no longer monitored; returned by `POST .../ownership_confirm` with
+   * `still_own: false`, and when listing numbers with
+   * `filter[ownership_status]=removed`.
+   */
+  ownership_status?: ReputationOwnershipStatus;
+
   /**
    * E.164 with leading `+`.
    */
   phone_number?: string;
 
   /**
-   * `null` until the first refresh has been collected for this number.
+   * Why a number was removed. `ported_away`: you confirmed the number left your
+   * control after a carrier change. `unconfirmed_ownership`: a carrier change was
+   * not confirmed before the deadline. `reassigned`: the number was reported as
+   * permanently disconnected. `customer_reported`: you reported that you no longer
+   * own the number. `customer_removed`: you removed the number.
+   */
+  removal_reason?:
+    | 'ported_away'
+    | 'unconfirmed_ownership'
+    | 'reassigned'
+    | 'customer_reported'
+    | 'customer_removed'
+    | null;
+
+  /**
+   * When the number was removed. Set only for removed numbers.
+   */
+  removed_at?: string | null;
+
+  /**
+   * Reputation snapshot for a phone number. Each metric is a 0–100 score;
+   * `spam_risk` is a coarse bucket. Field set may grow over time - read by key.
    */
   reputation_data?: Shared.ReputationData | null;
 
+  /**
+   * Where the phone number is hosted. `telnyx`: in your Telnyx inventory.
+   * `external`: a number you own that is hosted with another provider.
+   */
+  source?: ReputationNumberSource;
+
   updated_at?: string;
 }
 
@@ -240,7 +384,81 @@ export namespace NumberRefreshResponse {
   }
 }
 
+export interface NumberRetrieveOwnershipResponse {
+  data: NumberRetrieveOwnershipResponse.Data;
+}
+
+export namespace NumberRetrieveOwnershipResponse {
+  export interface Data {
+    /**
+     * Service provider ID (SPID) of the carrier that held the number when its
+     * ownership was last established.
+     */
+    baseline_carrier?: string | null;
+
+    baseline_recorded_at?: string | null;
+
+    confirm_by?: string | null;
+
+    flag_reason?: string | null;
+
+    /**
+     * Ownership events, most recent first.
+     */
+    history?: Array<Data.History>;
+
+    /**
+     * When ownership of the number was last checked.
+     */
+    last_checked_at?: string | null;
+
+    /**
+     * Result of ongoing ownership checks. `verified`: the number is with the carrier
+     * on record. `pending_confirmation`: the number's carrier changed, or a periodic
+     * ownership re-verification is due; confirm you still own it before `confirm_by`.
+     * `flagged`: a periodic re-verification went unanswered; the number stays
+     * monitored and is not removed, but confirm ownership
+     * (`POST .../ownership_confirm`) to return it to `verified`. `removed`: the number
+     * is no longer monitored; returned by `POST .../ownership_confirm` with
+     * `still_own: false`, and when listing numbers with
+     * `filter[ownership_status]=removed`.
+     */
+    ownership_status?: NumbersAPI.ReputationOwnershipStatus;
+
+    phone_number?: string;
+
+    /**
+     * Where the phone number is hosted. `telnyx`: in your Telnyx inventory.
+     * `external`: a number you own that is hosted with another provider.
+     */
+    source?: NumbersAPI.ReputationNumberSource;
+  }
+
+  export namespace Data {
+    export interface History {
+      /**
+       * `added`, `check`, `flag`, `confirm` or `removed`.
+       */
+      event_type?: string;
+
+      occurred_at?: string;
+
+      /**
+       * What the event found or did, for example `unchanged` or `carrier_changed`.
+       */
+      outcome?: string | null;
+    }
+  }
+}
+
 export interface NumberListParams extends DefaultFlatPaginationParams {
+  /**
+   * 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]'?: ReputationOwnershipStatus;
+
   /**
    * Partial match on phone number. Must contain at least 5 digits.
    */
@@ -250,6 +468,11 @@ export interface NumberListParams extends DefaultFlatPaginationParams {
    * Exact phone-number match (E.164).
    */
   'filter[phone_number][eq]'?: string;
+
+  /**
+   * Only numbers with this source.
+   */
+  'filter[source]'?: ReputationNumberSource;
 }
 
 export interface NumberAssociateParams {
@@ -287,18 +510,48 @@ export interface NumberRefreshParams {
   phone_numbers: Array<string>;
 }
 
+export interface NumberRetrieveOwnershipParams {
+  /**
+   * The enterprise id. Lowercase UUID.
+   */
+  enterprise_id: string;
+}
+
+export interface NumberOwnershipConfirmParams {
+  /**
+   * Path param: The enterprise id. Lowercase UUID.
+   */
+  enterprise_id: string;
+
+  /**
+   * 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: boolean;
+
+  /**
+   * Body param: Optional id of an uploaded document supporting the confirmation.
+   */
+  evidence_document_id?: string;
+}
+
 export declare namespace Numbers {
   export {
+    type ReputationNumberSource as ReputationNumberSource,
+    type ReputationOwnershipStatus as ReputationOwnershipStatus,
     type ReputationPhoneNumber as ReputationPhoneNumber,
     type ReputationPhoneNumberList as ReputationPhoneNumberList,
     type ReputationPhoneNumberListWithReputation as ReputationPhoneNumberListWithReputation,
     type ReputationPhoneNumberWithReputation as ReputationPhoneNumberWithReputation,
     type NumberRefreshResponse as NumberRefreshResponse,
+    type NumberRetrieveOwnershipResponse as NumberRetrieveOwnershipResponse,
     type ReputationPhoneNumbersDefaultFlatPagination as ReputationPhoneNumbersDefaultFlatPagination,
     type NumberListParams as NumberListParams,
     type NumberAssociateParams as NumberAssociateParams,
     type NumberDisassociateParams as NumberDisassociateParams,
     type NumberRetrieveParams as NumberRetrieveParams,
     type NumberRefreshParams as NumberRefreshParams,
+    type NumberRetrieveOwnershipParams as NumberRetrieveOwnershipParams,
+    type NumberOwnershipConfirmParams as NumberOwnershipConfirmParams,
   };
 }

package/src/resources/enterprises/reputation/remediation.ts

@@ -160,8 +160,9 @@ export interface RemediationRequest {
   contact_email?: string | null;
 
   /**
-   * Per-category buckets. Populated once results are available. Null while the
-   * request is still pending.
+   * Per-category buckets of phone numbers, populated once results are available.
+   * Empty lists are kept (not omitted) so consumers can iterate without
+   * null-checking each key.
    */
   results?: RemediationPerNumberResults | null;