@tryfinch/finch-api 6.27.0 → 6.28.0

package/src/resources/hris/employments.ts

@@ -8,6 +8,16 @@ import { ResponsesPage } from '../../pagination';
 export class Employments extends APIResource {
   /**
    * Read individual employment and income data
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const employmentDataResponse of client.hris.employments.retrieveMany(
+   *   { requests: [{ individual_id: 'individual_id' }] },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   retrieveMany(
     body: EmploymentRetrieveManyParams,
@@ -23,161 +33,175 @@ export class Employments extends APIResource {
 
 export class EmploymentDataResponsesPage extends ResponsesPage<EmploymentDataResponse> {}
 
-export interface EmploymentData {
-  /**
-   * A stable Finch `id` (UUID v4) for an individual in the company.
-   */
-  id?: string;
-
-  /**
-   * Worker's compensation classification code for this employee
-   */
-  class_code?: string | null;
+export type EmploymentData = EmploymentData.UnionMember0 | EmploymentData.BatchError;
 
-  /**
-   * Custom fields for the individual. These are fields which are defined by the
-   * employer in the system.
-   */
-  custom_fields?: Array<EmploymentData.CustomField> | null;
-
-  /**
-   * The department object.
-   */
-  department?: EmploymentData.Department | null;
+export namespace EmploymentData {
+  export interface UnionMember0 {
+    /**
+     * A stable Finch `id` (UUID v4) for an individual in the company.
+     */
+    id: string;
 
-  /**
-   * The employment object.
-   */
-  employment?: EmploymentData.Employment | null;
+    /**
+     * Worker's compensation classification code for this employee
+     */
+    class_code: string | null;
 
-  /**
-   * The detailed employment status of the individual. Available options: `active`,
-   * `deceased`, `leave`, `onboarding`, `prehire`, `retired`, `terminated`.
-   */
-  employment_status?:
-    | 'active'
-    | 'deceased'
-    | 'leave'
-    | 'onboarding'
-    | 'prehire'
-    | 'retired'
-    | 'terminated'
-    | null;
-
-  end_date?: string | null;
+    /**
+     * Custom fields for the individual. These are fields which are defined by the
+     * employer in the system.
+     */
+    custom_fields: Array<UnionMember0.CustomField> | null;
 
-  /**
-   * The legal first name of the individual.
-   */
-  first_name?: string | null;
+    /**
+     * The department object.
+     */
+    department: UnionMember0.Department | null;
 
-  /**
-   * The employee's income as reported by the provider. This may not always be
-   * annualized income, but may be in units of bi-weekly, semi-monthly, daily, etc,
-   * depending on what information the provider returns.
-   */
-  income?: HRISAPI.Income | null;
+    /**
+     * The employment object.
+     */
+    employment: UnionMember0.Employment | null;
 
-  /**
-   * The array of income history.
-   */
-  income_history?: Array<HRISAPI.Income | null> | null;
+    /**
+     * The detailed employment status of the individual. Available options: `active`,
+     * `deceased`, `leave`, `onboarding`, `prehire`, `retired`, `terminated`.
+     */
+    employment_status:
+      | 'active'
+      | 'deceased'
+      | 'leave'
+      | 'onboarding'
+      | 'prehire'
+      | 'retired'
+      | 'terminated'
+      | null;
+
+    end_date: string | null;
 
-  /**
-   * `true` if the individual an an active employee or contractor at the company.
-   */
-  is_active?: boolean | null;
+    /**
+     * The legal first name of the individual.
+     */
+    first_name: string | null;
 
-  /**
-   * The legal last name of the individual.
-   */
-  last_name?: string | null;
+    /**
+     * `true` if the individual an an active employee or contractor at the company.
+     */
+    is_active: boolean | null;
 
-  latest_rehire_date?: string | null;
+    /**
+     * The legal last name of the individual.
+     */
+    last_name: string | null;
 
-  location?: HRISAPI.Location | null;
+    latest_rehire_date: string | null;
 
-  /**
-   * The manager object representing the manager of the individual within the org.
-   */
-  manager?: EmploymentData.Manager | null;
+    location: HRISAPI.Location | null;
 
-  /**
-   * The legal middle name of the individual.
-   */
-  middle_name?: string | null;
+    /**
+     * The manager object representing the manager of the individual within the org.
+     */
+    manager: UnionMember0.Manager | null;
 
-  /**
-   * The source system's unique employment identifier for this individual
-   */
-  source_id?: string | null;
+    /**
+     * The legal middle name of the individual.
+     */
+    middle_name: string | null;
 
-  start_date?: string | null;
+    /**
+     * The source system's unique employment identifier for this individual
+     */
+    source_id: string | null;
 
-  /**
-   * The current title of the individual.
-   */
-  title?: string | null;
+    start_date: string | null;
 
-  /**
-   * @deprecated This field is deprecated in favour of `source_id`
-   */
-  work_id?: string | null;
-}
+    /**
+     * The current title of the individual.
+     */
+    title: string | null;
 
-export namespace EmploymentData {
-  export interface CustomField {
-    name?: string;
+    /**
+     * @deprecated This field is deprecated in favour of `source_id`
+     */
+    work_id: string | null;
 
-    value?: unknown;
-  }
+    /**
+     * The employee's income as reported by the provider. This may not always be
+     * annualized income, but may be in units of bi-weekly, semi-monthly, daily, etc,
+     * depending on what information the provider returns.
+     */
+    income?: HRISAPI.Income | null;
 
-  /**
-   * The department object.
-   */
-  export interface Department {
     /**
-     * The name of the department associated with the individual.
+     * The array of income history.
      */
-    name?: string | null;
+    income_history?: Array<HRISAPI.Income | null> | null;
   }
 
-  /**
-   * The employment object.
-   */
-  export interface Employment {
+  export namespace UnionMember0 {
+    export interface CustomField {
+      name?: string;
+
+      value?: string | Array<unknown> | unknown | number | boolean | null;
+    }
+
     /**
-     * The secondary employment type of the individual. Options: `full_time`,
-     * `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.
+     * The department object.
      */
-    subtype?: 'full_time' | 'intern' | 'part_time' | 'temp' | 'seasonal' | 'individual_contractor' | null;
+    export interface Department {
+      /**
+       * The name of the department associated with the individual.
+       */
+      name: string | null;
+    }
 
     /**
-     * The main employment type of the individual.
+     * The employment object.
      */
-    type?: 'employee' | 'contractor' | null;
-  }
+    export interface Employment {
+      /**
+       * The secondary employment type of the individual. Options: `full_time`,
+       * `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.
+       */
+      subtype: 'full_time' | 'intern' | 'part_time' | 'temp' | 'seasonal' | 'individual_contractor' | null;
+
+      /**
+       * The main employment type of the individual.
+       */
+      type: 'employee' | 'contractor' | null;
+    }
 
-  /**
-   * The manager object representing the manager of the individual within the org.
-   */
-  export interface Manager {
     /**
-     * A stable Finch `id` (UUID v4) for an individual in the company.
+     * The manager object representing the manager of the individual within the org.
      */
-    id?: string;
+    export interface Manager {
+      /**
+       * A stable Finch `id` (UUID v4) for an individual in the company.
+       */
+      id: string;
+    }
+  }
+
+  export interface BatchError {
+    code: number;
+
+    message: string;
+
+    name: string;
+
+    finch_code?: string;
   }
 }
 
 export interface EmploymentDataResponse {
-  body?: EmploymentData;
+  body: EmploymentData;
 
-  code?: number;
+  code: number;
 
   /**
    * A stable Finch `id` (UUID v4) for an individual in the company.
    */
-  individual_id?: string;
+  individual_id: string;
 }
 
 export interface EmploymentRetrieveManyParams {

package/src/resources/hris/hris.ts

@@ -88,23 +88,23 @@ export interface Income {
   /**
    * The income amount in cents.
    */
-  amount?: number | null;
+  amount: number | null;
 
   /**
    * The currency code.
    */
-  currency?: string | null;
+  currency: string | null;
 
   /**
    * The date the income amount went into effect.
    */
-  effective_date?: string | null;
+  effective_date: string | null;
 
   /**
    * The income unit of payment. Options: `yearly`, `quarterly`, `monthly`,
    * `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`.
    */
-  unit?:
+  unit:
     | 'yearly'
     | 'quarterly'
     | 'monthly'
@@ -121,36 +121,36 @@ export interface Location {
   /**
    * City, district, suburb, town, or village.
    */
-  city?: string | null;
+  city: string | null;
 
   /**
    * The 2-letter ISO 3166 country code.
    */
-  country?: string | null;
+  country: string | null;
 
   /**
    * Street address or PO box.
    */
-  line1?: string | null;
+  line1: string | null;
 
   /**
    * Apartment, suite, unit, or building.
    */
-  line2?: string | null;
-
-  name?: string | null;
+  line2: string | null;
 
   /**
    * The postal code or zip code.
    */
-  postal_code?: string | null;
-
-  source_id?: string | null;
+  postal_code: string | null;
 
   /**
    * The state code.
    */
-  state?: string | null;
+  state: string | null;
+
+  name?: string | null;
+
+  source_id?: string | null;
 }
 
 export interface Money {

package/src/resources/hris/individuals.ts

@@ -9,6 +9,14 @@ import { ResponsesPage } from '../../pagination';
 export class Individuals extends APIResource {
   /**
    * Read individual data, excluding income and employment data
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const individualResponse of client.hris.individuals.retrieveMany()) {
+   *   // ...
+   * }
+   * ```
    */
   retrieveMany(
     body?: IndividualRetrieveManyParams,
@@ -32,95 +40,109 @@ export class Individuals extends APIResource {
 
 export class IndividualResponsesPage extends ResponsesPage<IndividualResponse> {}
 
-export interface Individual {
-  /**
-   * A stable Finch `id` (UUID v4) for an individual in the company.
-   */
-  id?: string;
-
-  dob?: string | null;
+export type Individual = Individual.UnionMember0 | Individual.BatchError;
 
-  emails?: Array<Individual.Email> | null;
-
-  /**
-   * Social Security Number of the individual in **encrypted** format. This field is
-   * only available with the `ssn` scope enabled and the
-   * `options: { include: ['ssn'] }` param set in the body.
-   */
-  encrypted_ssn?: string | null;
-
-  /**
-   * The EEOC-defined ethnicity of the individual.
-   */
-  ethnicity?:
-    | 'asian'
-    | 'white'
-    | 'black_or_african_american'
-    | 'native_hawaiian_or_pacific_islander'
-    | 'american_indian_or_alaska_native'
-    | 'hispanic_or_latino'
-    | 'two_or_more_races'
-    | 'decline_to_specify'
-    | null;
-
-  /**
-   * The legal first name of the individual.
-   */
-  first_name?: string | null;
-
-  /**
-   * The gender of the individual.
-   */
-  gender?: 'female' | 'male' | 'other' | 'decline_to_specify' | null;
-
-  /**
-   * The legal last name of the individual.
-   */
-  last_name?: string | null;
-
-  /**
-   * The legal middle name of the individual.
-   */
-  middle_name?: string | null;
+export namespace Individual {
+  export interface UnionMember0 {
+    /**
+     * A stable Finch `id` (UUID v4) for an individual in the company.
+     */
+    id: string;
+
+    dob: string | null;
+
+    /**
+     * The EEOC-defined ethnicity of the individual.
+     */
+    ethnicity:
+      | 'asian'
+      | 'white'
+      | 'black_or_african_american'
+      | 'native_hawaiian_or_pacific_islander'
+      | 'american_indian_or_alaska_native'
+      | 'hispanic_or_latino'
+      | 'two_or_more_races'
+      | 'decline_to_specify'
+      | null;
+
+    /**
+     * The legal first name of the individual.
+     */
+    first_name: string | null;
+
+    /**
+     * The gender of the individual.
+     */
+    gender: 'female' | 'male' | 'other' | 'decline_to_specify' | null;
+
+    /**
+     * The legal last name of the individual.
+     */
+    last_name: string | null;
+
+    /**
+     * The legal middle name of the individual.
+     */
+    middle_name: string | null;
+
+    phone_numbers: Array<UnionMember0.PhoneNumber | null> | null;
+
+    /**
+     * The preferred name of the individual.
+     */
+    preferred_name: string | null;
+
+    residence: HRISAPI.Location | null;
+
+    emails?: Array<UnionMember0.Email> | null;
+
+    /**
+     * Social Security Number of the individual in **encrypted** format. This field is
+     * only available with the `ssn` scope enabled and the
+     * `options: { include: ['ssn'] }` param set in the body.
+     */
+    encrypted_ssn?: string | null;
+
+    /**
+     * Social Security Number of the individual. This field is only available with the
+     * `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the
+     * body.
+     * [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).
+     */
+    ssn?: string | null;
+  }
 
-  phone_numbers?: Array<Individual.PhoneNumber | null> | null;
+  export namespace UnionMember0 {
+    export interface PhoneNumber {
+      data: string | null;
 
-  /**
-   * The preferred name of the individual.
-   */
-  preferred_name?: string | null;
+      type: 'work' | 'personal' | null;
+    }
 
-  residence?: HRISAPI.Location | null;
+    export interface Email {
+      data: string;
 
-  /**
-   * Social Security Number of the individual. This field is only available with the
-   * `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the
-   * body.
-   * [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).
-   */
-  ssn?: string | null;
-}
+      type: 'work' | 'personal' | null;
+    }
+  }
 
-export namespace Individual {
-  export interface Email {
-    data?: string;
+  export interface BatchError {
+    code: number;
 
-    type?: 'work' | 'personal' | null;
-  }
+    message: string;
 
-  export interface PhoneNumber {
-    data?: string | null;
+    name: string;
 
-    type?: 'work' | 'personal' | null;
+    finch_code?: string;
   }
 }
 
 export interface IndividualResponse {
-  body?: Individual;
+  body: Individual;
 
-  code?: number;
+  code: number;
 
-  individual_id?: string;
+  individual_id: string;
 }
 
 export interface IndividualRetrieveManyParams {

package/src/resources/hris/pay-statements.ts

@@ -13,6 +13,22 @@ export class PayStatements extends APIResource {
    *
    * Deduction and contribution types are supported by the payroll systems that
    * supports Benefits.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const payStatementResponse of client.hris.payStatements.retrieveMany(
+   *   {
+   *     requests: [
+   *       {
+   *         payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *       },
+   *     ],
+   *   },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   retrieveMany(
     body: PayStatementRetrieveManyParams,

package/src/resources/hris/payments.ts

@@ -8,6 +8,17 @@ import { SinglePage } from '../../pagination';
 export class Payments extends APIResource {
   /**
    * Read payroll and contractor related payments by the company.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const payment of client.hris.payments.list({
+   *   end_date: '2021-01-01',
+   *   start_date: '2021-01-01',
+   * })) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: PaymentListParams,

package/src/resources/request-forwarding.ts

@@ -9,6 +9,16 @@ export class RequestForwarding extends APIResource {
    * Finch’s unified API doesn’t have a data model that cleanly fits your needs, then
    * Forward allows you to push or pull data models directly against an integration’s
    * API.
+   *
+   * @example
+   * ```ts
+   * const response = await client.requestForwarding.forward({
+   *   method: 'POST',
+   *   route: '/people/search',
+   *   headers: { 'content-type': 'application/json' },
+   *   params: { showInactive: true, humanReadable: true },
+   * });
+   * ```
    */
   forward(
     body: RequestForwardingForwardParams,

package/src/resources/sandbox/company.ts

@@ -7,6 +7,29 @@ import * as HRISAPI from '../hris/hris';
 export class Company extends APIResource {
   /**
    * Update a sandbox company's data
+   *
+   * @example
+   * ```ts
+   * const company = await client.sandbox.company.update({
+   *   accounts: [{}],
+   *   departments: [{}],
+   *   ein: 'ein',
+   *   entity: {},
+   *   legal_name: 'legal_name',
+   *   locations: [
+   *     {
+   *       city: 'city',
+   *       country: 'country',
+   *       line1: 'line1',
+   *       line2: 'line2',
+   *       postal_code: 'postal_code',
+   *       state: 'state',
+   *     },
+   *   ],
+   *   primary_email: 'dev@stainless.com',
+   *   primary_phone_number: 'primary_phone_number',
+   * });
+   * ```
    */
   update(body: CompanyUpdateParams, options?: Core.RequestOptions): Core.APIPromise<CompanyUpdateResponse> {
     return this._client.put('/sandbox/company', { body, ...options });