Employment

POST

employer

employment

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

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

async function main() {
  // 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);
  }
}

main();

{
  "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

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

Body

application/json

Individual Ids Request Body

requests

object[]

required

The array of batch requests.

Response

200 - application/json

Employment data

responses

object[]

responses.individual_id

string

responses.code

integer

responses.body

object

responses.body.id

string

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

responses.body.first_name

string | null

The legal first name of the individual.

responses.body.middle_name

string | null

The legal middle name of the individual.

responses.body.last_name

string | null

The legal last name of the individual.

responses.body.title

string | null

The current title of the individual.

responses.body.manager

object | null

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

responses.body.department

object | null

The department object.

responses.body.employment

object | null

The employment object.

responses.body.employment.type

enum<string> | null

The main employment type of the individual.

Available options:

employee,

contractor

responses.body.employment.subtype

enum<string> | null

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

responses.body.end_date

string | null

responses.body.latest_rehire_date

string | null

responses.body.is_active

boolean | null

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

responses.body.employment_status

enum<string> | null

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

Worker's compensation classification code for this employee

responses.body.location

object | null

responses.body.income

object | 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.

responses.body.income_history

array | null

The array of income history.

responses.body.custom_fields

object[] | null

Custom fields for the individual. These are fields which are defined by the employer in the system.

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

Was this page helpful?

Individual Payment

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

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

async function main() {
  // 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);
  }
}

main();

{
  "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"
          }
        ]
      }
    }
  ]
}

Organization

Payroll

Deductions

Documents

Connect

Management

Sandbox

Development Guides

Authorizations

Headers

Body

Response