@tryfinch/finch-api 1.0.0

package/resources/hris/company.ts

@@ -0,0 +1,127 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import * as HRIS from '~/resources/hris';
+
+export class CompanyResource extends APIResource {
+  /**
+   * Read basic company data
+   */
+  retrieve(options?: Core.RequestOptions): Promise<Core.APIResponse<Company>> {
+    return this.get('/employer/company', options);
+  }
+}
+
+export interface Company {
+  /**
+   * An array of bank account objects associated with the payroll/HRIS system.
+   */
+  accounts: Array<Company.Accounts> | null;
+
+  /**
+   * The array of company departments.
+   */
+  departments: Array<Company.Departments | null> | null;
+
+  /**
+   * The employer identification number.
+   */
+  ein: string | null;
+
+  /**
+   * The entity type object.
+   */
+  entity: Company.Entity | null;
+
+  /**
+   * A stable Finch `id` (UUID v4) for the company.
+   */
+  id: string;
+
+  /**
+   * The legal name of the company.
+   */
+  legal_name: string | null;
+
+  locations: Array<HRIS.Location | null> | null;
+
+  /**
+   * The email of the main administrator on the account.
+   */
+  primary_email: string | null;
+
+  /**
+   * The phone number of the main administrator on the account. Format: `XXXXXXXXXX`
+   */
+  primary_phone_number: string | null;
+}
+
+export namespace Company {
+  /**
+   * The entity type object.
+   */
+  export interface Entity {
+    /**
+     * The tax payer subtype of the company.
+     */
+    subtype?: 's_corporation' | 'c_corporation' | 'b_corporation' | null;
+
+    /**
+     * The tax payer type of the company.
+     */
+    type?: 'llc' | 'corporation' | 'sole_proprietor' | 'non_profit' | 'partnership' | 'cooperative' | null;
+  }
+
+  export interface Departments {
+    /**
+     * The department name.
+     */
+    name?: string | null;
+
+    /**
+     * The parent department, if present.
+     */
+    parent?: Departments.Parent | null;
+  }
+
+  export namespace Departments {
+    /**
+     * The parent department, if present.
+     */
+    export interface Parent {
+      /**
+       * The parent department's name.
+       */
+      name?: string | null;
+    }
+  }
+
+  export interface Accounts {
+    /**
+     * The name of the bank associated in the payroll/HRIS system.
+     */
+    account_name?: string | null;
+
+    /**
+     * 10-12 digit number to specify the bank account
+     */
+    account_number?: string | null;
+
+    /**
+     * The type of bank account.
+     */
+    account_type?: 'checking' | 'savings' | null;
+
+    /**
+     * Name of the banking institution.
+     */
+    institution_name?: string | null;
+
+    /**
+     * A nine-digit code that's based on the U.S. Bank location where your account was
+     * opened.
+     */
+    routing_number?: string | null;
+  }
+}

package/resources/hris/directory.ts

@@ -0,0 +1,87 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { isRequestOptions } from '~/core';
+import { IndividualsPage, IndividualsPageParams } from '~/pagination';
+
+export class Directory extends APIResource {
+  /**
+   * Read company directory and organization structure
+   */
+  listIndividuals(
+    query?: DirectoryListIndividualsParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualsPage>;
+  listIndividuals(options?: Core.RequestOptions): Core.PagePromise<IndividualsPage>;
+  listIndividuals(
+    query: DirectoryListIndividualsParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualsPage> {
+    if (isRequestOptions(query)) {
+      return this.listIndividuals({}, query);
+    }
+    return this.getAPIList('/employer/directory', IndividualsPage, { query, ...options });
+  }
+}
+
+export interface IndividualInDirectory {
+  /**
+   * The department object.
+   */
+  department?: IndividualInDirectory.Department | null;
+
+  /**
+   * The legal first name of the individual.
+   */
+  first_name?: string | null;
+
+  /**
+   * A stable Finch id (UUID v4) for an individual in the company.
+   */
+  id?: string;
+
+  /**
+   * `true` if the individual is an active employee or contractor at the company.
+   */
+  is_active?: boolean | null;
+
+  /**
+   * The legal last name of the individual.
+   */
+  last_name?: string | null;
+
+  /**
+   * The manager object.
+   */
+  manager?: IndividualInDirectory.Manager | null;
+
+  /**
+   * The legal middle name of the individual.
+   */
+  middle_name?: string | null;
+}
+
+export namespace IndividualInDirectory {
+  /**
+   * The manager object.
+   */
+  export interface Manager {
+    /**
+     * A stable Finch `id` (UUID v4) for an individual in the company.
+     */
+    id?: string;
+  }
+
+  /**
+   * The department object.
+   */
+  export interface Department {
+    /**
+     * The name of the department.
+     */
+    name?: string | null;
+  }
+}
+
+export interface DirectoryListIndividualsParams extends IndividualsPageParams {}

package/resources/hris/hris.ts

@@ -0,0 +1,113 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import { APIResource } from '~/resource';
+import { CompanyResource } from './company';
+import { Payments } from './payments';
+import { PayStatements } from './pay-statements';
+import { Directory } from './directory';
+import { Individuals } from './individuals/individuals';
+import { Benefits } from './benefits/benefits';
+
+export class HRIS extends APIResource {
+  company: CompanyResource = new CompanyResource(this.client);
+  payments: Payments = new Payments(this.client);
+  payStatements: PayStatements = new PayStatements(this.client);
+  directory: Directory = new Directory(this.client);
+  individuals: Individuals = new Individuals(this.client);
+  benefits: Benefits = new Benefits(this.client);
+}
+
+/**
+ * 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.
+ */
+export interface Income {
+  /**
+   * The income amount in cents.
+   */
+  amount?: number | null;
+
+  /**
+   * The currency code.
+   */
+  currency?: string | null;
+
+  /**
+   * The date the income amount went into effect.
+   */
+  effective_date?: string | null;
+
+  /**
+   * The income unit of payment. Options: `yearly`, `quarterly`, `monthly`,
+   * `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`.
+   */
+  unit?:
+    | 'yearly'
+    | 'quarterly'
+    | 'monthly'
+    | 'semi_monthly'
+    | 'bi_weekly'
+    | 'weekly'
+    | 'daily'
+    | 'hourly'
+    | 'fixed'
+    | null;
+}
+
+export interface Location {
+  /**
+   * City, district, suburb, town, or village.
+   */
+  city?: string | null;
+
+  /**
+   * The 2-letter ISO 3166 country code.
+   */
+  country?: string | null;
+
+  /**
+   * Street address or PO box.
+   */
+  line1?: string | null;
+
+  /**
+   * Apartment, suite, unit, or building.
+   */
+  line2?: string | null;
+
+  name?: string | null;
+
+  /**
+   * The postal code or zip code.
+   */
+  postal_code?: string | null;
+
+  source_id?: string | null;
+
+  /**
+   * The state code.
+   */
+  state?: string | null;
+}
+
+export interface Money {
+  /**
+   * Amount for money object (in cents)
+   */
+  amount?: number;
+
+  currency?: string;
+}
+
+export interface Paging {
+  /**
+   * The total number of elements for the entire query (not just the given page)
+   */
+  count?: number;
+
+  /**
+   * The current start index of the returned list of elements
+   */
+  offset?: number;
+}

package/resources/hris/index.ts

@@ -0,0 +1,32 @@
+// File generated from our OpenAPI spec by Stainless.
+
+export {
+  BenefitFrequency,
+  BenefitType,
+  BenfitContribution,
+  CompanyBenefit,
+  CreateCompanyBenefitsResponse,
+  SupportedBenefit,
+  UpdateCompanyBenefitResponse,
+  BenefitCreateParams,
+  BenefitUpdateParams,
+  CompanyBenefitsSinglePage,
+  SupportedBenefitsSinglePage,
+} from './benefits';
+export { Company } from './company';
+export { Income, Location, Money, Paging } from './hris';
+export {
+  Individual,
+  IndividualResponse,
+  IndividualRetrieveManyParams,
+  IndividualResponsesResponsesPage,
+} from './individuals';
+export { IndividualInDirectory, DirectoryListIndividualsParams } from './directory';
+export {
+  PayStatement,
+  PayStatementResponse,
+  PayStatementResponseBody,
+  PayStatementRetrieveManyParams,
+  PayStatementResponsesResponsesPage,
+} from './pay-statements';
+export { Payment, PaymentListParams, PaymentsSinglePage } from './payments';

package/resources/hris/individuals/employment-data.ts

@@ -0,0 +1,188 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import * as HRIS from '~/resources/hris';
+import { ResponsesPage } from '~/pagination';
+
+export class EmploymentData extends APIResource {
+  /**
+   * Read individual employment and income data
+   *
+   * Note: Income information is returned 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.
+   */
+  retrieveMany(
+    body: EmploymentDataRetrieveManyParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<EmploymentDataResponsesResponsesPage> {
+    return this.getAPIList('/employer/employment', EmploymentDataResponsesResponsesPage, {
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+}
+
+export class EmploymentDataResponsesResponsesPage extends ResponsesPage<EmploymentDataResponse> {}
+
+export interface EmploymentData {
+  /**
+   * Worker's compensation classification code for this employee
+   */
+  class_code?: string | null;
+
+  /**
+   * The department object.
+   */
+  department?: EmploymentData.Department | null;
+
+  /**
+   * The employment object.
+   */
+  employment?: EmploymentData.Employment | null;
+
+  end_date?: string | null;
+
+  /**
+   * The legal first name of the individual.
+   */
+  first_name?: string | null;
+
+  /**
+   * string A stable Finch `id` (UUID v4) for an individual in the company.
+   */
+  id?: string;
+
+  /**
+   * 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?: HRIS.Income | null;
+
+  /**
+   * The array of income history.
+   */
+  income_history?: Array<HRIS.Income | null> | null;
+
+  /**
+   * `true` if the individual an an active employee or contractor at the company.
+   */
+  is_active?: boolean | null;
+
+  /**
+   * The legal last name of the individual.
+   */
+  last_name?: string | null;
+
+  location?: HRIS.Location | null;
+
+  /**
+   * The manager object representing the manager of the individual within the org.
+   */
+  manager?: EmploymentData.Manager | null;
+
+  /**
+   * The legal middle name of the individual.
+   */
+  middle_name?: string | null;
+
+  /**
+   * Note: This property is only available if enabled for your account. Please reach
+   * out to your Finch representative if you would like access.
+   */
+  pay_group_ids?: Array<string> | null;
+
+  start_date?: string | null;
+
+  /**
+   * The current title of the individual.
+   */
+  title?: string | null;
+
+  /**
+   * Note: This property is only available if enabled for your account. Please reach
+   * out to your Finch representative if you would like access.
+   */
+  work_id?: string | null;
+
+  /**
+   * Note: This property is only available if enabled for your account. Please reach
+   * out to your Finch representative if you would like access.
+   */
+  work_id_2?: string | null;
+}
+
+export namespace EmploymentData {
+  /**
+   * 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.
+     */
+    id?: string;
+  }
+
+  /**
+   * The department object.
+   */
+  export interface Department {
+    /**
+     * The name of the department associated with the individual.
+     */
+    name?: string | null;
+  }
+
+  /**
+   * The employment object.
+   */
+  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;
+  }
+}
+
+export interface EmploymentDataResponse {
+  body?: EmploymentData;
+
+  code?: number;
+
+  individual_id?: string;
+}
+
+export interface EmploymentDataRetrieveManyParams {
+  /**
+   * The array of batch requests.
+   */
+  requests: Array<EmploymentDataRetrieveManyParams.Requests>;
+}
+
+export namespace EmploymentDataRetrieveManyParams {
+  export interface Requests {
+    /**
+     * A stable Finch `id` (UUID v4) for an individual in the company. There is no
+     * limit to the number of `individual_id` to send per request. It is preferantial
+     * to send all ids in a single request for Finch to optimize provider rate-limits.
+     */
+    individual_id: string;
+  }
+
+  export interface Requests {
+    /**
+     * A stable Finch `id` (UUID v4) for an individual in the company. There is no
+     * limit to the number of `individual_id` to send per request. It is preferantial
+     * to send all ids in a single request for Finch to optimize provider rate-limits.
+     */
+    individual_id: string;
+  }
+}

package/resources/hris/individuals/index.ts

@@ -0,0 +1,14 @@
+// File generated from our OpenAPI spec by Stainless.
+
+export {
+  EmploymentData,
+  EmploymentDataResponse,
+  EmploymentDataRetrieveManyParams,
+  EmploymentDataResponsesResponsesPage,
+} from './employment-data';
+export {
+  Individual,
+  IndividualResponse,
+  IndividualRetrieveManyParams,
+  IndividualResponsesResponsesPage,
+} from './individuals';

package/resources/hris/individuals/individuals.ts

@@ -0,0 +1,128 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { isRequestOptions } from '~/core';
+import * as HRIS from '~/resources/hris';
+import { EmploymentData } from './employment-data';
+import { ResponsesPage } from '~/pagination';
+
+export class Individuals extends APIResource {
+  employmentData: EmploymentData = new EmploymentData(this.client);
+
+  /**
+   * Read individual data, excluding income and employment data
+   */
+  retrieveMany(
+    body?: IndividualRetrieveManyParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualResponsesResponsesPage>;
+  retrieveMany(options?: Core.RequestOptions): Core.PagePromise<IndividualResponsesResponsesPage>;
+  retrieveMany(
+    body: IndividualRetrieveManyParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualResponsesResponsesPage> {
+    if (isRequestOptions(body)) {
+      return this.retrieveMany({}, body);
+    }
+    return this.getAPIList('/employer/individual', IndividualResponsesResponsesPage, {
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+}
+
+export class IndividualResponsesResponsesPage extends ResponsesPage<IndividualResponse> {}
+
+export interface Individual {
+  dob?: string | null;
+
+  emails?: Array<Individual.Emails> | 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;
+
+  /**
+   * A stable Finch `id` (UUID v4) for an individual in the company.
+   */
+  id?: string;
+
+  /**
+   * 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<Individual.PhoneNumbers | null> | null;
+
+  /**
+   * The preferred name of the individual.
+   */
+  preferred_name?: string | null;
+
+  residence?: HRIS.Location | null;
+
+  /**
+   * Note: This property is only available if enabled for your account. Please reach
+   * out to your Finch representative if you would like access.
+   */
+  ssn?: string | null;
+}
+
+export namespace Individual {
+  export interface Emails {
+    data?: string;
+
+    type?: 'work' | 'personal';
+  }
+
+  export interface PhoneNumbers {
+    data?: string | null;
+
+    type?: 'work' | 'personal' | null;
+  }
+}
+
+export interface IndividualResponse {
+  body?: Individual;
+
+  code?: number;
+
+  individual_id?: string;
+}
+
+export interface IndividualRetrieveManyParams {
+  options?: IndividualRetrieveManyParams.Options | null;
+
+  requests?: Array<IndividualRetrieveManyParams.Requests>;
+}
+
+export namespace IndividualRetrieveManyParams {
+  export interface Requests {
+    individual_id?: string;
+  }
+
+  export interface Options {
+    include?: Array<string>;
+  }
+
+  export interface Options {
+    include?: Array<string>;
+  }
+
+  export interface Requests {
+    individual_id?: string;
+  }
+}