@tryfinch/finch-api 1.0.0

package/resources/ats/jobs.ts

@@ -0,0 +1,70 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { isRequestOptions } from '~/core';
+import { JobsPage, JobsPageParams } from '~/pagination';
+
+export class Jobs extends APIResource {
+  /**
+   * Gets a job from an organization.
+   */
+  retrieve(jobId: string, options?: Core.RequestOptions): Promise<Core.APIResponse<Job>> {
+    return this.get(`/ats/jobs/${jobId}`, options);
+  }
+
+  /**
+   * Gets all of an organization's jobs.
+   */
+  list(query?: JobListParams, options?: Core.RequestOptions): Core.PagePromise<JobsPage>;
+  list(options?: Core.RequestOptions): Core.PagePromise<JobsPage>;
+  list(
+    query: JobListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<JobsPage> {
+    if (isRequestOptions(query)) {
+      return this.list({}, query);
+    }
+    return this.getAPIList('/ats/jobs', JobsPage, { query, ...options });
+  }
+}
+
+export interface Job {
+  closed_at: string | null;
+
+  created_at: string | null;
+
+  department: Job.Department;
+
+  hiring_team: Job.HiringTeam;
+
+  id: string;
+
+  name: string | null;
+
+  status: 'open' | 'closed' | 'on_hold' | 'draft' | 'archived' | null;
+}
+
+export namespace Job {
+  export interface Department {
+    name?: string | null;
+  }
+
+  export interface HiringTeam {
+    hiring_managers?: Array<HiringTeam.HiringManagers> | null;
+
+    recruiters?: Array<HiringTeam.Recruiters> | null;
+  }
+
+  export namespace HiringTeam {
+    export interface HiringManagers {
+      name?: string;
+    }
+
+    export interface Recruiters {
+      name?: string;
+    }
+  }
+}
+
+export interface JobListParams extends JobsPageParams {}

package/resources/ats/offers.ts

@@ -0,0 +1,57 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { isRequestOptions } from '~/core';
+import { OffersPage, OffersPageParams } from '~/pagination';
+
+export class Offers extends APIResource {
+  /**
+   * Get a single offer from an organization.
+   */
+  retrieve(offerId: string, options?: Core.RequestOptions): Promise<Core.APIResponse<Offer>> {
+    return this.get(`/ats/offers/${offerId}`, options);
+  }
+
+  /**
+   * Get all offers put out by an organization.
+   */
+  list(query?: OfferListParams, options?: Core.RequestOptions): Core.PagePromise<OffersPage>;
+  list(options?: Core.RequestOptions): Core.PagePromise<OffersPage>;
+  list(
+    query: OfferListParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<OffersPage> {
+    if (isRequestOptions(query)) {
+      return this.list({}, query);
+    }
+    return this.getAPIList('/ats/offers', OffersPage, { query, ...options });
+  }
+}
+
+export interface Offer {
+  application_id: string;
+
+  candidate_id: string;
+
+  created_at: string;
+
+  id: string;
+
+  job_id: string;
+
+  status:
+    | 'signed'
+    | 'rejected'
+    | 'draft'
+    | 'approval-sent'
+    | 'approved'
+    | 'sent'
+    | 'sent-manually'
+    | 'opened'
+    | 'archived';
+
+  updated_at: string;
+}
+
+export interface OfferListParams extends OffersPageParams {}

package/resources/ats/stages.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { SinglePage } from '~/pagination';
+
+export class Stages extends APIResource {
+  /**
+   * Get all job stages for an organization. Depending on the system, some jobs may
+   * have stages specific to that job. Other job stages may apply broadly to all jobs
+   * in the system. Use the `job_id` to determine whether a job applies specifically
+   * to a job.
+   */
+  list(options?: Core.RequestOptions): Core.PagePromise<StagesSinglePage> {
+    return this.getAPIList('/ats/stages', StagesSinglePage, options);
+  }
+}
+
+export class StagesSinglePage extends SinglePage<Stage> {}
+
+export interface Stage {
+  id?: string;
+
+  /**
+   * The job id that this stage applies to, if applicable. Not all systems enumerate
+   * stages specific to jobs.
+   */
+  job_id?: string | null;
+
+  name?: string | null;
+}

package/resources/hris/benefits/benefits.ts

@@ -0,0 +1,214 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { isRequestOptions } from '~/core';
+import { Individuals } from './individuals';
+import { SinglePage } from '~/pagination';
+
+export class Benefits extends APIResource {
+  individuals: Individuals = new Individuals(this.client);
+
+  /**
+   * **Availability: Automated and Assisted Benefits providers**
+   *
+   * Creates a new company-wide benefit. Please use the `/meta` endpoint to view
+   * available types for each provider.
+   */
+  create(
+    body?: BenefitCreateParams,
+    options?: Core.RequestOptions,
+  ): Promise<Core.APIResponse<CreateCompanyBenefitsResponse>>;
+  create(options?: Core.RequestOptions): Promise<Core.APIResponse<CreateCompanyBenefitsResponse>>;
+  create(
+    body: BenefitCreateParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Promise<Core.APIResponse<CreateCompanyBenefitsResponse>> {
+    if (isRequestOptions(body)) {
+      return this.create({}, body);
+    }
+    return this.post('/employer/benefits', { body, ...options });
+  }
+
+  /**
+   * **Availability: Automated Benefits providers only**
+   *
+   * Lists benefit information for a given benefit
+   */
+  retrieve(benefitId: string, options?: Core.RequestOptions): Promise<Core.APIResponse<CompanyBenefit>> {
+    return this.get(`/employer/benefits/${benefitId}`, options);
+  }
+
+  /**
+   * **Availability: Automated and Assisted Benefits providers**
+   *
+   * Updates an existing company-wide benefit
+   */
+  update(
+    benefitId: string,
+    body?: BenefitUpdateParams,
+    options?: Core.RequestOptions,
+  ): Promise<Core.APIResponse<UpdateCompanyBenefitResponse>>;
+  update(
+    benefitId: string,
+    options?: Core.RequestOptions,
+  ): Promise<Core.APIResponse<UpdateCompanyBenefitResponse>>;
+  update(
+    benefitId: string,
+    body: BenefitUpdateParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Promise<Core.APIResponse<UpdateCompanyBenefitResponse>> {
+    if (isRequestOptions(body)) {
+      return this.update(benefitId, {}, body);
+    }
+    return this.post(`/employer/benefits/${benefitId}`, { body, ...options });
+  }
+
+  /**
+   * **Availability: Automated Benefits providers only**
+   *
+   * List all company-wide benefits.
+   */
+  list(options?: Core.RequestOptions): Core.PagePromise<CompanyBenefitsSinglePage> {
+    return this.getAPIList('/employer/benefits', CompanyBenefitsSinglePage, options);
+  }
+
+  /**
+   * **Availability: Automated and Assisted Benefits providers**
+   *
+   * Lists available types and configurations for the provider associated with the
+   * access token.
+   */
+  listSupportedBenefits(options?: Core.RequestOptions): Core.PagePromise<SupportedBenefitsSinglePage> {
+    return this.getAPIList('/employer/benefits/meta', SupportedBenefitsSinglePage, options);
+  }
+}
+
+export class CompanyBenefitsSinglePage extends SinglePage<CompanyBenefit> {}
+
+export class SupportedBenefitsSinglePage extends SinglePage<SupportedBenefit> {}
+
+export type BenefitFrequency = 'one_time' | 'every_paycheck' | null;
+
+/**
+ * Type of benefit.
+ */
+export type BenefitType =
+  | '401k'
+  | '401k_roth'
+  | '401k_loan'
+  | '403b'
+  | '403b_roth'
+  | '457'
+  | '457_roth'
+  | 's125_medical'
+  | 's125_dental'
+  | 's125_vision'
+  | 'hsa_pre'
+  | 'hsa_post'
+  | 'fsa_medical'
+  | 'fsa_dependent_care'
+  | 'simple_ira'
+  | 'simple'
+  | 'commuter'
+  | 'custom_post_tax'
+  | 'custom_pre_tax'
+  | null;
+
+export interface BenfitContribution {
+  /**
+   * Contribution amount in cents (if `fixed`) or basis points (if `percent`).
+   */
+  amount?: number | null;
+
+  /**
+   * Contribution type.
+   */
+  type?: 'fixed' | 'percent' | null;
+}
+
+export interface CompanyBenefit {
+  benefit_id: string;
+
+  company_contribution: BenfitContribution | null;
+
+  description: string | null;
+
+  employee_deduction: BenfitContribution | null;
+
+  frequency: BenefitFrequency | null;
+
+  /**
+   * Type of benefit.
+   */
+  type: BenefitType | null;
+}
+
+export interface CreateCompanyBenefitsResponse {
+  benefit_id: string;
+}
+
+export interface SupportedBenefit {
+  /**
+   * Whether the provider supports an annual maximum for this benefit.
+   */
+  annual_maximum?: boolean | null;
+
+  /**
+   * Whether the provider supports catch up for this benefit. This field will only be
+   * true for retirement benefits.
+   */
+  catch_up?: boolean | null;
+
+  /**
+   * Supported contribution types. An empty array indicates contributions are not
+   * supported.
+   */
+  company_contribution?: Array<'fixed' | 'percent'> | null;
+
+  description?: string | null;
+
+  /**
+   * Supported deduction types. An empty array indicates deductions are not
+   * supported.
+   */
+  employee_deduction?: Array<'fixed' | 'percent'> | null;
+
+  /**
+   * The list of frequencies supported by the provider for this benefit
+   */
+  frequencies?: Array<BenefitFrequency | null>;
+
+  /**
+   * Whether the provider supports HSA contribution limits. Empty if this feature is
+   * not supported for the benefit. This array only has values for HSA benefits.
+   */
+  hsa_contribution_limit?: Array<'individual' | 'family'> | null;
+
+  /**
+   * Type of benefit.
+   */
+  type?: BenefitType | null;
+}
+
+export interface UpdateCompanyBenefitResponse {
+  benefit_id: string;
+}
+
+export interface BenefitCreateParams {
+  description?: string;
+
+  frequency?: BenefitFrequency | null;
+
+  /**
+   * Type of benefit.
+   */
+  type?: BenefitType | null;
+}
+
+export interface BenefitUpdateParams {
+  /**
+   * Updated name or description.
+   */
+  description?: string;
+}

package/resources/hris/benefits/index.ts

@@ -0,0 +1,27 @@
+// File generated from our OpenAPI spec by Stainless.
+
+export {
+  BenefitFrequency,
+  BenefitType,
+  BenfitContribution,
+  CompanyBenefit,
+  CreateCompanyBenefitsResponse,
+  SupportedBenefit,
+  UpdateCompanyBenefitResponse,
+  BenefitCreateParams,
+  BenefitUpdateParams,
+  CompanyBenefitsSinglePage,
+  SupportedBenefitsSinglePage,
+} from './benefits';
+export {
+  EnrolledIndividual,
+  IndividualBenefit,
+  UnenrolledIndividual,
+  IndividualEnrolledIDsResponse,
+  IndividualEnrollManyParams,
+  IndividualRetrieveManyBenefitsParams,
+  IndividualUnenrollParams,
+  EnrolledIndividualsSinglePage,
+  IndividualBenefitsSinglePage,
+  UnenrolledIndividualsSinglePage,
+} from './individuals';

package/resources/hris/benefits/individuals.ts

@@ -0,0 +1,234 @@
+// File generated from our OpenAPI spec by Stainless.
+
+import * as Core from '~/core';
+import { APIResource } from '~/resource';
+import { isRequestOptions } from '~/core';
+import * as Benefits from '~/resources/hris/benefits';
+import { SinglePage } from '~/pagination';
+
+export class Individuals extends APIResource {
+  /**
+   * **Availability: Automated and Assisted Benefits providers**
+   *
+   * Enroll an individual into a benefit. If the employee is already enrolled, the
+   * enrollment amounts will be adjusted.
+   *
+   * <!-- theme: warning -->
+   *
+   * > Making changes to an individual's benefits may have tax consequences based on
+   * > IRS regulations. Please consult a tax expert to ensure all changes being made
+   * > to the system are compliant with local, state, and federal law.
+   */
+  enrollMany(
+    benefitId: string,
+    body: IndividualEnrollManyParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<EnrolledIndividualsSinglePage> {
+    return this.getAPIList(`/employer/benefits/${benefitId}/individuals`, EnrolledIndividualsSinglePage, {
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+
+  /**
+   * **Availability: Automated Benefits providers only**
+   *
+   * Lists individuals currently enrolled in a given benefit.
+   */
+  enrolledIds(
+    benefitId: string,
+    options?: Core.RequestOptions,
+  ): Promise<Core.APIResponse<IndividualEnrolledIDsResponse>> {
+    return this.get(`/employer/benefits/${benefitId}/enrolled`, options);
+  }
+
+  /**
+   * **Availability: Automated Benefits providers only**
+   *
+   * Get enrolled benefit information for the given individuals.
+   */
+  retrieveManyBenefits(
+    benefitId: string,
+    query?: IndividualRetrieveManyBenefitsParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualBenefitsSinglePage>;
+  retrieveManyBenefits(
+    benefitId: string,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualBenefitsSinglePage>;
+  retrieveManyBenefits(
+    benefitId: string,
+    query: IndividualRetrieveManyBenefitsParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<IndividualBenefitsSinglePage> {
+    if (isRequestOptions(query)) {
+      return this.retrieveManyBenefits(benefitId, {}, query);
+    }
+    return this.getAPIList(`/employer/benefits/${benefitId}/individuals`, IndividualBenefitsSinglePage, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * **Availability: Automated and Assisted Benefits providers**
+   *
+   * Unenroll individuals from a benefit
+   */
+  unenroll(
+    benefitId: string,
+    body?: IndividualUnenrollParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<UnenrolledIndividualsSinglePage>;
+  unenroll(
+    benefitId: string,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<UnenrolledIndividualsSinglePage>;
+  unenroll(
+    benefitId: string,
+    body: IndividualUnenrollParams | Core.RequestOptions = {},
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<UnenrolledIndividualsSinglePage> {
+    if (isRequestOptions(body)) {
+      return this.unenroll(benefitId, {}, body);
+    }
+    return this.getAPIList(`/employer/benefits/${benefitId}/individuals`, UnenrolledIndividualsSinglePage, {
+      body,
+      method: 'delete',
+      ...options,
+    });
+  }
+}
+
+export class EnrolledIndividualsSinglePage extends SinglePage<EnrolledIndividual> {}
+
+export class IndividualBenefitsSinglePage extends SinglePage<IndividualBenefit> {}
+
+export class UnenrolledIndividualsSinglePage extends SinglePage<UnenrolledIndividual> {}
+
+export interface EnrolledIndividual {
+  body?: EnrolledIndividual.Body;
+
+  /**
+   * HTTP status code. Either 201 or 200
+   */
+  code?: 200 | 201 | 404 | 403;
+
+  individual_id?: string;
+}
+
+export namespace EnrolledIndividual {
+  export interface Body {
+    /**
+     * A descriptive identifier for the response
+     */
+    finch_code?: string | null;
+
+    /**
+     * Short description in English that provides more information about the response.
+     */
+    message?: string | null;
+
+    /**
+     * Identifier indicating whether the benefit was newly enrolled or updated.
+     */
+    name?: string | null;
+  }
+}
+
+export interface IndividualBenefit {
+  body?: IndividualBenefit.Body;
+
+  code?: number;
+
+  individual_id?: string;
+}
+
+export namespace IndividualBenefit {
+  export interface Body {
+    /**
+     * If the benefit supports annual maximum, the amount in cents for this individual.
+     */
+    annual_maximum?: number | null;
+
+    /**
+     * If the benefit supports catch up (401k, 403b, etc.), whether catch up is enabled
+     * for this individual.
+     */
+    catch_up?: boolean | null;
+
+    company_contribution?: Benefits.BenfitContribution | null;
+
+    employee_deduction?: Benefits.BenfitContribution | null;
+
+    /**
+     * Type for HSA contribution limit if the benefit is a HSA.
+     */
+    hsa_contribution_limit?: 'individual' | 'family' | null;
+  }
+}
+
+export interface UnenrolledIndividual {
+  body?: UnenrolledIndividual.Body;
+
+  /**
+   * HTTP status code
+   */
+  code?: number;
+
+  individual_id?: string;
+}
+
+export namespace UnenrolledIndividual {
+  export interface Body {
+    /**
+     * A descriptive identifier for the response.
+     */
+    finch_code?: string | null;
+
+    /**
+     * Short description in English that provides more information about the response.
+     */
+    message?: string | null;
+
+    /**
+     * Identifier indicating whether the benefit was newly enrolled or updated.
+     */
+    name?: string | null;
+  }
+}
+
+export interface IndividualEnrolledIDsResponse {
+  benefit_id: string;
+
+  individual_ids: Array<string>;
+}
+
+export type IndividualEnrollManyParams = Array<IndividualEnrollManyParams.Individual>;
+
+export namespace IndividualEnrollManyParams {
+  export interface Individual {
+    configuration?: unknown;
+
+    /**
+     * Finch id (uuidv4) for the individual to enroll
+     */
+    individual_id?: string;
+  }
+}
+
+export interface IndividualRetrieveManyBenefitsParams {
+  /**
+   * comma-delimited list of stable Finch uuids for each individual. If empty,
+   * defaults to all individuals
+   */
+  individual_ids?: string;
+}
+
+export interface IndividualUnenrollParams {
+  /**
+   * Array of individual_ids to unenroll.
+   */
+  individual_ids?: Array<string>;
+}