Employment

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

// Automatically fetches more pages as needed.
for await (const employmentDataResponse of client.hris.employments.retrieveMany({
  requests: [{ individual_id: 'individual_id' }],
})) {
  console.log(employmentDataResponse.individual_id);
}

{
  "responses": [
    {
      "individual_id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9",
      "code": 200,
      "body": {
        "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9",
        "first_name": "Jane",
        "middle_name": null,
        "last_name": "Doe",
        "title": "Customer Support",
        "manager": {
          "id": "c205b3fa-b626-4346-bf0f-ca065ab88d31"
        },
        "department": {
          "name": "Product"
        },
        "employment": {
          "type": "employee",
          "subtype": "full_time"
        },
        "start_date": "2017-06-30",
        "end_date": null,
        "latest_rehire_date": null,
        "is_active": true,
        "employment_status": "onboarding",
        "class_code": "8810",
        "location": {
          "line1": "12 Bird Drive",
          "line2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postal_code": "94301",
          "country": "US"
        },
        "income": {
          "unit": "yearly",
          "amount": 10000000,
          "currency": "usd",
          "effective_date": "2019-03-01"
        },
        "income_history": [
          {
            "unit": "yearly",
            "amount": 9000000,
            "currency": "usd",
            "effective_date": "2018-05-15"
          },
          {
            "unit": "yearly",
            "amount": 8000000,
            "currency": "usd",
            "effective_date": "2017-06-30"
          }
        ],
        "custom_fields": [
          {
            "name": "tShirtSize",
            "value": "L"
          }
        ]
      }
    }
  ]
}

POST

employer

employment

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

// Automatically fetches more pages as needed.
for await (const employmentDataResponse of client.hris.employments.retrieveMany({
  requests: [{ individual_id: 'individual_id' }],
})) {
  console.log(employmentDataResponse.individual_id);
}

{
  "responses": [
    {
      "individual_id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9",
      "code": 200,
      "body": {
        "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9",
        "first_name": "Jane",
        "middle_name": null,
        "last_name": "Doe",
        "title": "Customer Support",
        "manager": {
          "id": "c205b3fa-b626-4346-bf0f-ca065ab88d31"
        },
        "department": {
          "name": "Product"
        },
        "employment": {
          "type": "employee",
          "subtype": "full_time"
        },
        "start_date": "2017-06-30",
        "end_date": null,
        "latest_rehire_date": null,
        "is_active": true,
        "employment_status": "onboarding",
        "class_code": "8810",
        "location": {
          "line1": "12 Bird Drive",
          "line2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postal_code": "94301",
          "country": "US"
        },
        "income": {
          "unit": "yearly",
          "amount": 10000000,
          "currency": "usd",
          "effective_date": "2019-03-01"
        },
        "income_history": [
          {
            "unit": "yearly",
            "amount": 9000000,
            "currency": "usd",
            "effective_date": "2018-05-15"
          },
          {
            "unit": "yearly",
            "amount": 8000000,
            "currency": "usd",
            "effective_date": "2017-06-30"
          }
        ],
        "custom_fields": [
          {
            "name": "tShirtSize",
            "value": "L"
          }
        ]
      }
    }
  ]
}

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.

Authorizations

Authorization

string

header

required

Please use your Access Token

Headers

Finch-API-Version

string<date>

default:2020-09-17

required

Header used to specify the version for a given API request. Current version is 2020-09-17.

Content-Type

string

default:application/json

required

Used to indicate the original media type of the resource

Query Parameters

entity_ids

string<uuid>[]

The entity IDs to specify which entities' data to access.

Required array length: 1 element

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Body

application/json

Individual Ids Request Body

requests

object[]

required

The array of batch requests.

Show child attributes

requests.individual_id

string

required

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.

Response

Employment data

responses

object[]

required

Show child attributes

responses.individual_id

string<uuid>

required

A stable Finch id (UUID v4) for an individual in the company.

responses.code

integer

required

responses.body

object

required

Option 1
Option 2

Show child attributes

responses.body.first_name

string | null

required

The legal first name of the individual.

responses.body.middle_name

string | null

required

The legal middle name of the individual.

responses.body.last_name

string | null

required

The legal last name of the individual.

responses.body.title

string | null

required

The current title of the individual.

responses.body.manager

object

required

The manager object representing the manager of the individual within the org.

Show child attributes

responses.body.manager.id

string<uuid>

required

A stable Finch id (UUID v4) for an individual in the company.

responses.body.department

object

required

The department object.

Show child attributes

responses.body.department.name

string | null

required

The name of the department associated with the individual.

responses.body.employment

object

required

The employment object.

Show child attributes

responses.body.employment.type

enum<string> | null

required

The main employment type of the individual.

Available options:

employee,

contractor,

responses.body.employment.subtype

enum<string> | null

required

The secondary employment type of the individual. Options: full_time, part_time, intern, temp, seasonal and individual_contractor.

Available options:

full_time,

intern,

part_time,

temp,

seasonal,

individual_contractor,

responses.body.start_date

string | null

required

responses.body.end_date

string | null

required

responses.body.latest_rehire_date

string | null

required

responses.body.is_active

boolean | null

required

true if the individual an an active employee or contractor at the company.

responses.body.employment_status

enum<string> | null

required

The detailed employment status of the individual. Available options: active, deceased, leave, onboarding, prehire, retired, terminated.

Available options:

active,

deceased,

leave,

onboarding,

prehire,

retired,

terminated,

responses.body.class_code

string | null

required

Worker's compensation classification code for this employee

responses.body.location

Location · object

required

Show child attributes

responses.body.location.line1

string | null

required

Street address or PO box.

responses.body.location.line2

string | null

required

Apartment, suite, unit, or building.

responses.body.location.city

string | null

required

City, district, suburb, town, or village.

responses.body.location.state

string | null

required

The state code.

responses.body.location.postal_code

string | null

required

The postal code or zip code.

responses.body.location.country

string | null

required

The 2-letter ISO 3166 country code.

responses.body.location.name

string | null

responses.body.location.source_id

string | null

responses.body.id

string<uuid>

required

A stable Finch id (UUID v4) for an individual in the company.

responses.body.income

Income · object

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.

Show child attributes

responses.body.income.unit

enum<string> | null

required

The income unit of payment. Options: yearly, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, hourly, and fixed.

Available options:

yearly,

quarterly,

monthly,

semi_monthly,

bi_weekly,

weekly,

daily,

hourly,

fixed,

responses.body.income.amount

integer | null

required

The income amount in cents.

responses.body.income.currency

string | null

required

The currency code.

responses.body.income.effective_date

string<date> | null

required

The date the income amount went into effect.

responses.body.income_history

(Income · object | null)[] | null

The array of income history.

Show child attributes

responses.body.income_history.unit

enum<string> | null

required

The income unit of payment. Options: yearly, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, hourly, and fixed.

Available options:

yearly,

quarterly,

monthly,

semi_monthly,

bi_weekly,

weekly,

daily,

hourly,

fixed,

responses.body.income_history.amount

integer | null

required

The income amount in cents.

responses.body.income_history.currency

string | null

required

The currency code.

responses.body.income_history.effective_date

string<date> | null

required

The date the income amount went into effect.

responses.body.custom_fields

object[] | null

Custom fields for the individual. These are fields which are defined by the employer in the system. Custom fields are not currently supported for assisted connections.

Show child attributes

responses.body.custom_fields.name

string | null

responses.body.custom_fields.value

string | null

responses.body.source_id

string | null

The source system's unique employment identifier for this individual

responses.body.work_id

string | null

deprecated

This field is deprecated in favour of source_id

Individual Payment

⌘I

Organization

Payroll

Deductions

Documents

Connect

Management

Sandbox

Development Guides

Authorizations

Headers

Query Parameters

Body

Response