telnyx 7.23.0 → 7.25.0

package/src/resources/dir/dir.ts

@@ -110,22 +110,23 @@ export class DirResource extends APIResource {
   }
 
   /**
-   * Delete a DIR. Failure modes: `400` if a child phone number is in a non-deletable
-   * status, `409` if the DIR has an unresolved infringement claim, `404` if the DIR
-   * is not yours.
+   * Request deletion of a DIR. This does not remove the DIR on this call: it records
+   * the request, moves the DIR to `delete_requested`, and Telnyx completes the
+   * removal (de-registration and cleanup) shortly after. A verified DIR keeps
+   * serving its branded identity, and keeps billing, until the removal is executed.
+   * Failure modes: `400` if a child phone number is still attached or the DIR is
+   * `in_review` (wait for the review to finish), `409` if the DIR has an unresolved
+   * infringement claim, `404` if the DIR is not yours.
    *
    * @example
    * ```ts
-   * await client.dir.delete(
+   * const dir = await client.dir.delete(
    *   '16635d38-75a6-4481-82e8-69af60e05011',
    * );
    * ```
    */
-  delete(dirID: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.delete(path`/dir/${dirID}`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  delete(dirID: string, options?: RequestOptions): APIPromise<DirDeleteResponse> {
+    return this._client.delete(path`/dir/${dirID}`, options);
   }
 
   /**
@@ -147,11 +148,14 @@ export class DirResource extends APIResource {
    * Edit a DIR. DIRs in `draft`, `rejected`, `unsuccessful`, or `suspended` can be
    * edited freely: PATCH is a pure edit, `status` is never changed, and you re-vet
    * by calling `POST /v2/dir/{dir_id}/submit` explicitly. A `verified` DIR can also
-   * be edited in place: a PATCH that changes any value returns the DIR to `draft`
-   * and branded delivery stops until you re-submit and the DIR is approved again,
-   * while a PATCH that changes nothing (an empty body or values identical to the
-   * current ones) leaves the DIR `verified`, so idempotent retries are safe. DIRs in
-   * any other status (`submitted`, `in_review`, `expired`, `infringement_claimed`,
+   * be edited in place: a PATCH that changes any value returns the DIR to `draft`;
+   * the currently approved identity keeps displaying, and the edited content goes
+   * live only after you re-submit and the DIR is approved again. A PATCH that
+   * changes nothing (an empty body or values identical to the current ones) leaves
+   * the DIR `verified`, so idempotent retries are safe. Changing only
+   * `bpo_authorizations` or `webhook_url` is the exception: the DIR stays
+   * `verified`. Each BPO authorization is reviewed on its own instead. DIRs in any
+   * other status (`submitted`, `in_review`, `expired`, `infringement_claimed`,
    * `permanently_rejected`) cannot be edited.
    *
    * @example
@@ -289,10 +293,95 @@ export class DirResource extends APIResource {
       __binaryResponse: true,
     });
   }
+
+  /**
+   * List the BPO (Business Process Outsourcer) accounts a Brand Owner has authorized
+   * on this DIR, together with the review state of each authorization.
+   *
+   * Authorizations are supplied as the `bpo_authorizations` array when creating or
+   * updating a DIR, and each one is reviewed on its own. Only an `approved`
+   * authorization adds that BPO to this DIR's authorized callers in the branded
+   * calling registry; `pending` and `rejected` authorizations do not. Each entry
+   * includes the `loa_document_id` you submitted: because `bpo_authorizations`
+   * replaces the whole list on every DIR update, send each entry you want to keep
+   * back with its `loa_document_id` unchanged, and it keeps its review state. A
+   * rejected entry carries a `rejection_reason`. Returns an empty list when the DIR
+   * has authorized no BPOs.
+   *
+   * @example
+   * ```ts
+   * const response = await client.dir.retrieveBpoAuthorizations(
+   *   '16635d38-75a6-4481-82e8-69af60e05011',
+   * );
+   * ```
+   */
+  retrieveBpoAuthorizations(
+    dirID: string,
+    query: DirRetrieveBpoAuthorizationsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DirRetrieveBpoAuthorizationsResponse> {
+    return this._client.get(path`/dir/${dirID}/bpo_authorizations`, { query, ...options });
+  }
+
+  /**
+   * The Letter of Authorization in which a Brand Owner authorizes an approved BPO
+   * (Business Process Outsourcer) to place branded calls that display this DIR on
+   * the owner's behalf. Both parties are read from the caller's account: the Brand
+   * Owner is the enterprise that owns the DIR, and the BPO is `bpo_enterprise_id`.
+   * No business identity is accepted in the body.
+   *
+   * When `signature` is omitted the PDF is returned unsigned so the Brand Owner can
+   * sign it externally and the BPO can upload it via the Documents API. When
+   * `signature` is present the PDF embeds the supplied image, printed name, and
+   * signed-at date.
+   *
+   * Returns `application/pdf`.
+   *
+   * @example
+   * ```ts
+   * const response = await client.dir.bpoLoa(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   {
+   *     bpo_enterprise_id:
+   *       '4a6192a4-573d-446d-b3ce-aff9117272a6',
+   *   },
+   * );
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
+   */
+  bpoLoa(dirID: string, body: DirBpoLoaParams, options?: RequestOptions): APIPromise<Response> {
+    return this._client.post(path`/dir/${dirID}/bpo_loa`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/pdf' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
 }
 
 export type DirsDefaultFlatPagination = DefaultFlatPagination<Dir>;
 
+/**
+ * One authorization to include when creating or updating a DIR: an approved BPO
+ * (Business Process Outsourcer) account plus the signed Letter of Authorization
+ * the Brand Owner granted it.
+ */
+export interface BpoAuthorizationInput {
+  /**
+   * Enterprise id of an approved BPO (Business Process Outsourcer) account on your
+   * organization to authorize for this DIR.
+   */
+  bpo_enterprise_id: string;
+
+  /**
+   * Id of the signed Letter of Authorization document (uploaded via the Telnyx
+   * Documents API) in which the Brand Owner authorizes this BPO.
+   */
+  loa_document_id: string;
+}
+
 export interface Dir {
   id?: string;
 
@@ -310,6 +399,12 @@ export interface Dir {
 
   created_at?: string;
 
+  /**
+   * When deletion was requested. Set once the DIR enters `delete_requested`; `null`
+   * otherwise.
+   */
+  delete_requested_at?: string | null;
+
   display_name?: string;
 
   documents?: Array<Document> | null;
@@ -345,6 +440,10 @@ export interface Dir {
    * - `infringement_claimed` - a trademark/impersonation claim is open against this
    *   DIR.
    * - `permanently_rejected` - terminal; cannot be resubmitted.
+   * - `delete_requested` - you have requested deletion; the DIR still exists and
+   *   Telnyx is completing the removal (de-registration and cleanup). A verified DIR
+   *   keeps serving its branded identity, and keeps billing, until the removal
+   *   finishes.
    */
   status?: DirStatus;
 
@@ -353,6 +452,12 @@ export interface Dir {
   updated_at?: string;
 
   verified_at?: string | null;
+
+  /**
+   * `https://` URL that receives webhook notifications for this DIR's
+   * compliance-review outcomes. `null` when not subscribed.
+   */
+  webhook_url?: string | null;
 }
 
 export namespace Dir {
@@ -390,6 +495,10 @@ export interface DirList {
  * - `infringement_claimed` - a trademark/impersonation claim is open against this
  *   DIR.
  * - `permanently_rejected` - terminal; cannot be resubmitted.
+ * - `delete_requested` - you have requested deletion; the DIR still exists and
+ *   Telnyx is completing the removal (de-registration and cleanup). A verified DIR
+ *   keeps serving its branded identity, and keeps billing, until the removal
+ *   finishes.
  */
 export type DirStatus =
   | 'draft'
@@ -401,7 +510,8 @@ export type DirStatus =
   | 'suspended'
   | 'expired'
   | 'infringement_claimed'
-  | 'permanently_rejected';
+  | 'permanently_rejected'
+  | 'delete_requested';
 
 export interface DirWrapped {
   data: Dir;
@@ -434,9 +544,43 @@ export interface Document {
     | 'bank_statement'
     | 'other';
 
+  /**
+   * An optional note describing this document, for example what it proves.
+   */
   description?: string;
 }
 
+export interface SignaturePayload {
+  /**
+   * PNG image, base64-encoded.
+   */
+  image_base64: string;
+
+  /**
+   * Optional. When absent the rendered PDF falls back to the enterprise contact's
+   * legal name.
+   */
+  signer_name?: string | null;
+}
+
+export interface DirDeleteResponse {
+  data: DirDeleteResponse.Data;
+}
+
+export namespace DirDeleteResponse {
+  export interface Data {
+    /**
+     * Id of the DIR whose deletion was requested.
+     */
+    id: string;
+
+    /**
+     * Always `delete_requested`: the DIR has been queued for removal, not yet removed.
+     */
+    status: 'delete_requested';
+  }
+}
+
 export interface DirListDocumentTypesResponse {
   data: Array<DirListDocumentTypesResponse.Data>;
 
@@ -463,6 +607,58 @@ export namespace DirListDocumentTypesResponse {
   }
 }
 
+/**
+ * Paginated list of a DIR's BPO authorizations.
+ */
+export interface DirRetrieveBpoAuthorizationsResponse {
+  data: Array<DirRetrieveBpoAuthorizationsResponse.Data>;
+
+  /**
+   * JSON:API pagination metadata returned with every paginated list response. Page
+   * numbering is 1-based. `page_size` reports the number of items actually returned
+   * in `data` for this page; the requested size is taken from the `page[size]` query
+   * parameter.
+   */
+  meta: CallReasonsAPI.BrandedCallingPaginationMeta;
+}
+
+export namespace DirRetrieveBpoAuthorizationsResponse {
+  /**
+   * A single authorization of a BPO (Business Process Outsourcer) account on a DIR.
+   */
+  export interface Data {
+    /**
+     * The authorized BPO account's enterprise id.
+     */
+    bpo_enterprise_id: string;
+
+    /**
+     * Id of the signed Letter of Authorization document submitted for this BPO. Send
+     * it back unchanged in `bpo_authorizations` when updating the DIR to keep this
+     * authorization and its review state.
+     */
+    loa_document_id: string;
+
+    /**
+     * Always `bpo_authorization`.
+     */
+    record_type: 'bpo_authorization';
+
+    /**
+     * Review state of this authorization. `pending` on create or when the Letter of
+     * Authorization is re-uploaded; an admin moves it to `approved` or `rejected`.
+     * Only an `approved` authorization adds the BPO to this DIR's authorized callers
+     * in the branded calling registry.
+     */
+    status: 'pending' | 'approved' | 'rejected';
+
+    /**
+     * Why the authorization was rejected. `null` unless `status` is `rejected`.
+     */
+    rejection_reason?: string | null;
+  }
+}
+
 export interface DirListParams extends DefaultFlatPaginationParams {
   /**
    * Case-insensitive partial match on call reason.
@@ -523,6 +719,16 @@ export interface DirUpdateParams {
    */
   authorizer_name?: string;
 
+  /**
+   * Optional. Replace this DIR's authorized BPO (Business Process Outsourcer)
+   * accounts with these, each with its signed Letter of Authorization. The supplied
+   * list replaces the current one: a BPO left out has its authorization removed, and
+   * a new BPO (or a changed Letter of Authorization) is created `pending` admin
+   * review. Send an empty list to clear all authorizations; omit the field to leave
+   * them unchanged. Editing this list does not re-vet the DIR. Maximum 10.
+   */
+  bpo_authorizations?: Array<BpoAuthorizationInput>;
+
   /**
    * 1–10 reasons your business calls customers. Validate phrasing against
    * `POST /call_reasons/validate`.
@@ -570,6 +776,13 @@ export interface DirUpdateParams {
    * (BPO/reseller). Updating this triggers re-vetting on next submit.
    */
   reselling?: boolean;
+
+  /**
+   * Optional `https://` URL that receives webhook notifications when this DIR's
+   * compliance review completes. Send `null` to clear. Changing only this field on a
+   * `verified` DIR does not re-vet it. Maximum 2048 characters.
+   */
+  webhook_url?: string | null;
 }
 
 export interface DirListInfringementClaimsParams extends DefaultFlatPaginationParams {}
@@ -586,7 +799,8 @@ export interface DirUpdateInfringementParams {
   certify_ip_ownership: true;
 
   /**
-   * Must be `true`.
+   * Check to certify that the brand no longer infringes anyone else's trademark or
+   * intellectual property.
    */
   certify_no_infringement: true;
 
@@ -602,6 +816,10 @@ export interface DirUpdateInfringementParams {
 
   call_reasons?: Array<string> | null;
 
+  /**
+   * The business name shown to call recipients, 1 to 35 characters, no emoji, not
+   * blank.
+   */
   display_name?: string | null;
 
   /**
@@ -634,27 +852,34 @@ export interface DirNewLoaParams {
    * name, and signed-at date. When absent the PDF is returned unsigned so the
    * customer can sign externally and upload it via the Documents API.
    */
-  signature?: DirNewLoaParams.Signature;
+  signature?: SignaturePayload;
 }
 
-export namespace DirNewLoaParams {
+export interface DirRetrieveBpoAuthorizationsParams {
   /**
-   * Optional. When provided the rendered PDF embeds the signature image, printed
-   * name, and signed-at date. When absent the PDF is returned unsigned so the
-   * customer can sign externally and upload it via the Documents API.
+   * 1-based page number. Out-of-range values return an empty page with correct meta.
    */
-  export interface Signature {
-    /**
-     * PNG image, base64-encoded.
-     */
-    image_base64: string;
+  'page[number]'?: number;
 
-    /**
-     * Optional. When absent the rendered PDF falls back to the enterprise contact's
-     * legal name.
-     */
-    signer_name?: string | null;
-  }
+  /**
+   * Items per page. Maximum 250; values above are clamped to 250.
+   */
+  'page[size]'?: number;
+}
+
+export interface DirBpoLoaParams {
+  /**
+   * The approved BPO enterprise the Brand Owner is authorizing. Must be a BPO
+   * account on the caller's organization that has already been approved.
+   */
+  bpo_enterprise_id: string;
+
+  /**
+   * Optional. When provided the rendered PDF embeds the signature image, printed
+   * name, and signed-at date. When absent the PDF is returned unsigned so the Brand
+   * Owner can sign externally and the BPO can upload it via the Documents API.
+   */
+  signature?: SignaturePayload;
 }
 
 DirResource.Comments = Comments;
@@ -665,18 +890,24 @@ DirResource.VerifyEmail = VerifyEmail;
 
 export declare namespace DirResource {
   export {
+    type BpoAuthorizationInput as BpoAuthorizationInput,
     type Dir as Dir,
     type DirList as DirList,
     type DirStatus as DirStatus,
     type DirWrapped as DirWrapped,
     type Document as Document,
+    type SignaturePayload as SignaturePayload,
+    type DirDeleteResponse as DirDeleteResponse,
     type DirListDocumentTypesResponse as DirListDocumentTypesResponse,
+    type DirRetrieveBpoAuthorizationsResponse as DirRetrieveBpoAuthorizationsResponse,
     type DirsDefaultFlatPagination as DirsDefaultFlatPagination,
     type DirListParams as DirListParams,
     type DirUpdateParams as DirUpdateParams,
     type DirListInfringementClaimsParams as DirListInfringementClaimsParams,
     type DirUpdateInfringementParams as DirUpdateInfringementParams,
     type DirNewLoaParams as DirNewLoaParams,
+    type DirRetrieveBpoAuthorizationsParams as DirRetrieveBpoAuthorizationsParams,
+    type DirBpoLoaParams as DirBpoLoaParams,
   };
 
   export {

package/src/resources/dir/index.ts

@@ -11,17 +11,23 @@ export {
 } from './comments';
 export {
   DirResource,
+  type BpoAuthorizationInput,
   type Dir,
   type DirList,
   type DirStatus,
   type DirWrapped,
   type Document,
+  type SignaturePayload,
+  type DirDeleteResponse,
   type DirListDocumentTypesResponse,
+  type DirRetrieveBpoAuthorizationsResponse,
   type DirListParams,
   type DirUpdateParams,
   type DirListInfringementClaimsParams,
   type DirUpdateInfringementParams,
   type DirNewLoaParams,
+  type DirRetrieveBpoAuthorizationsParams,
+  type DirBpoLoaParams,
   type DirsDefaultFlatPagination,
 } from './dir';
 export {

package/src/resources/dir/phone-numbers.ts

@@ -59,11 +59,11 @@ export class PhoneNumbers extends APIResource {
 
   /**
    * Register phone numbers under a DIR. The enterprise is resolved server-side from
-   * the DIR id. Same body, failure modes, and batch semantics whichever path form
-   * you use.
+   * the DIR id.
    *
-   * **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
-   * for current pricing.
+   * **Pricing:** Adding phone numbers is free. Branded Calling fees are charged per
+   * DIR and per branded call. See https://telnyx.com/pricing/branded-calling for
+   * current pricing.
    *
    * @example
    * ```ts
@@ -225,6 +225,10 @@ export namespace PhoneNumberRemoveResponse {
 }
 
 export interface PhoneNumberRemoveParams {
+  /**
+   * The phone numbers to remove from this brand, in E.164 format, up to 100 per
+   * request. They must currently be attached to this brand.
+   */
   phone_numbers: Array<string>;
 }
 

package/src/resources/dir/references.ts

@@ -268,27 +268,29 @@ export interface ReferenceUpdateParams {
   ref_type: 'business' | 'financial';
 
   /**
-   * Body param: Reference contact email address.
+   * Body param: The reference's email address. We email them scheduling and dial-in
+   * instructions before we call, so use an address they check.
    */
   email?: string;
 
   /**
-   * Body param: Full name of the reference contact.
+   * Body param: The full name of the person we should contact as your reference.
    */
   full_name?: string;
 
   /**
-   * Body param: Job title of the reference contact.
+   * Body param: The reference contact's job title, for example CFO or Owner.
    */
   job_title?: string | null;
 
   /**
-   * Body param: Organization the reference contact belongs to.
+   * Body param: The name of the organization the reference contact works for.
    */
   organization?: string | null;
 
   /**
-   * Body param: Reference phone number in E.164 format.
+   * Body param: The reference's phone number in E.164 format, for example
+   * +14155550123. We call this number during their local business hours.
    */
   phone_e164?: string;
 
@@ -298,7 +300,8 @@ export interface ReferenceUpdateParams {
   relationship_to_registrant?: string | null;
 
   /**
-   * Body param: IANA timezone id for the reference.
+   * Body param: The reference's IANA time zone, for example America/New_York. We
+   * only call during their local 8am to 9pm hours, which is why we need it.
    */
   timezone?: string;
 }

package/src/resources/email-blocks/email-blocks.ts

@@ -78,9 +78,11 @@ export class EmailBlocks extends APIResource {
    * stream `ORDER BY created_at ASC, id ASC` with no pagination.
    *
    * CSV columns:
-   * `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id`.
-   * The CSV carries the `group_id` column so group-scoped suppressions' group link
-   * survives the export (empty for account-scope rows).
+   * `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id,bounce_category,dsn_code, meta`
+   * (15 columns). The first 12 columns are the stable native signature;
+   * `bounce_category`, `dsn_code`, and `meta` are optional backup fields (empty when
+   * unset). The CSV carries the `group_id` column so group-scoped suppressions'
+   * group link survives the export (empty for account-scope rows).
    *
    * @example
    * ```ts
@@ -201,6 +203,12 @@ export interface EmailBlock {
    */
   domain_id?: string | null;
 
+  /**
+   * Optional expiration time. An active row stops matching send-time suppression
+   * checks as soon as `expires_at <= now()`. A maintenance worker later transitions
+   * the row to `status: expired` and appends an `expired` audit event (normally
+   * within 15 minutes).
+   */
   expires_at?: string | null;
 
   /**
@@ -267,7 +275,7 @@ export interface EmailBlockRetrieveEventsResponse {
 
 /**
  * CSV with header row
- * `id,to,from,reason,source,scope,status,domain_id,created_at,updated_at,expires_at,group_id`.
+ * `id,to,from,reason,source,scope,status,domain_id,created_at,updated_at,expires_at,group_id,bounce_category,dsn_code,meta`.
  */
 export type EmailBlockRetrieveExportResponse = string;
 

package/src/resources/email-blocks/imports.ts

@@ -20,9 +20,23 @@ export class Imports extends APIResource {
    * - header-only / all-blank / undetectable provider → `400` Returns `202` with the
    *   import record (status `pending`); an Oban worker (`EmailBlockImportWorker`,
    *   max_attempts 3) transitions `pending → processing → completed | failed`.
-   *   `block_ttl_days` applies only to imported `manual_block` rows; other reasons
-   *   get `expires_at: nil`. Provider is auto-detected from the CSV header
-   *   (`sendgrid` / `mailgun` / `ses` / `generic`).
+   *
+   * Native Telnyx exports are detected by the stable first-12-column header
+   * signature (`id` … `group_id`) and are restored with their original `from`,
+   * `domain_id`, `group_id`, `source`, `status`, `expires_at`, plus
+   * `bounce_category`, `dsn_code`, and `meta` when present (`scope` is re-derived
+   * from `domain_id`/`from`; the exported `scope` cell must be a valid enum value).
+   * Lifecycle changes reconcile through the same create path as the API: a row
+   * already in the requested state restores its mutable backup fields without a new
+   * audit event, and a real transition (e.g. tombstone → active) appends the
+   * matching lifecycle event. `block_ttl_days` is not applied to native rows — their
+   * exported `expires_at` is preserved verbatim.
+   *
+   * Competitor and generic imports (SendGrid / Mailgun / SES / generic) remain
+   * account-scoped (`from`, `domain_id`, `group_id`, `scope` are not read) and
+   * `block_ttl_days` applies only to imported `manual_block` rows; other reasons get
+   * `expires_at: nil`. Provider is auto-detected from the CSV header (`sendgrid` /
+   * `mailgun` / `ses` / `generic`).
    *
    * @example
    * ```ts
@@ -94,7 +108,9 @@ export interface EmailBlockImport {
   created_count?: number;
 
   /**
-   * Only when `status == completed`.
+   * Rows that passed CSV parsing but failed suppression creation. This is the
+   * creation-failure subset of `skipped_count`; parser-rejected rows equal
+   * `skipped_count - error_count`. Only when `status == completed`.
    */
   error_count?: number;