---
title: "Employment"
method: POST
path: "/employer/employment"
tags: ["Organization"]
---

# Employment

`POST /employer/employment`

Read individual employment and income data

## Query parameters

- `entity_ids` string[]

## Headers

- `Finch-API-Version` string, date, required
- `Content-Type` string, required

## Request body

- object — Individual Ids Request Body
  - `requests` object[], required — The array of batch 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 `200`

Employment data

- GetEmploymentResponse
  - `responses` object[], required
    - `individual_id` string, uuid, required — A stable Finch `id` (UUID v4) for an individual in the company.
    - `code` integer, required
    - `body` union, required
      - object
        - `first_name` string, nullable, required — The legal first name of the individual.
        - `middle_name` string, nullable, required — The legal middle name of the individual.
        - `last_name` string, nullable, required — The legal last name of the individual.
        - `title` string, nullable, required — The current title of the individual.
        - `manager` object, nullable, required — The manager object representing the manager of the individual within the org.
          - `id` string, uuid, required — A stable Finch `id` (UUID v4) for an individual in the company.
        - `department` object, nullable, required — The department object.
          - `name` string, nullable, required — The name of the department associated with the individual.
        - `employment` object, nullable, required — The employment object.
          - `type` 'employee' | 'contractor' | 'null', nullable, required — The main employment type of the individual.
          - `subtype` 'full_time' | 'intern' | 'part_time' | 'temp' | 'seasonal' | 'individual_contractor' | 'null', nullable, required — The secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`.
        - `start_date` string, nullable, required
        - `end_date` string, nullable, required
        - `latest_rehire_date` string, nullable, required
        - `is_active` boolean, nullable, required — `true` if the individual an an active employee or contractor at the company.
        - `employment_status` 'active' | 'deceased' | 'leave' | 'onboarding' | 'prehire' | 'retired' | 'terminated' | 'null', nullable, required — The detailed employment status of the individual. Available options: `active`, `deceased`, `leave`, `onboarding`, `prehire`, `retired`, `terminated`.
        - `class_code` string, nullable, required — Worker's compensation classification code for this employee
        - `location` Location, nullable, required
          - `line1` string, nullable, required — Street address or PO box.
          - `line2` string, nullable, required — Apartment, suite, unit, or building.
          - `city` string, nullable, required — City, district, suburb, town, or village.
          - `state` string, nullable, required — The state code.
          - `postal_code` string, nullable, required — The postal code or zip code.
          - `country` string, nullable, required — The 2-letter ISO 3166 country code.
          - `name` string, nullable
          - `source_id` string, nullable
        - `income` Income, nullable — 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.
          - `unit` 'yearly' | 'quarterly' | 'monthly' | 'semi_monthly' | 'bi_weekly' | 'weekly' | 'daily' | 'hourly' | 'fixed' | 'null', nullable, required — The income unit of payment. Options: `yearly`, `quarterly`, `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`.
          - `amount` integer, nullable, required — The income amount in cents.
          - `currency` string, nullable, required — The currency code.
          - `effective_date` string, date, nullable, required — The date the income amount went into effect.
        - `income_history` Income[], nullable — The array of income history.
          - `unit` 'yearly' | 'quarterly' | 'monthly' | 'semi_monthly' | 'bi_weekly' | 'weekly' | 'daily' | 'hourly' | 'fixed' | 'null', nullable, required — The income unit of payment. Options: `yearly`, `quarterly`, `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`.
          - `amount` integer, nullable, required — The income amount in cents.
          - `currency` string, nullable, required — The currency code.
          - `effective_date` string, date, nullable, required — The date the income amount went into effect.
        - `custom_fields` object[], nullable — 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.
          - `name` string, nullable
          - `value` union
            - string
            - object
            - number
            - boolean
        - `source_id` string, nullable — The source system's unique employment identifier for this individual
        - `id` string, uuid, required — A stable Finch `id` (UUID v4) for an individual in the company.
        - `work_id` string, nullable — This field is deprecated in favour of `source_id`
      - BatchError
        - `code` number, required
        - `finch_code` string
        - `message` string, required
        - `name` string, required

## Other responses

- `202` — The request has been accepted for processing, but data is not yet available

## Changes

- **2025-10-27** `0105d239fcaf` — 1 info
  - added the new optional `query` request parameter `entity_ids`
- **2025-06-24** `f7e741bc6e01` — 2 breaking
  - the response property `responses/items/body/anyOf[subschema #1]/custom_fields` became optional for the status `200`
  - the response property `responses/items/body/anyOf[subschema #1]/work_id` became optional for the status `200`
- **2025-05-17** `944a0f9d35f3` — 2 breaking
  - the response property `responses/items/body/anyOf[subschema #1]/custom_fields/items/name` became nullable for the status `200`
  - the response property `responses/items/body/anyOf[subschema #1]/custom_fields/items/value` became nullable for the status `200`
- **2025-05-16** `dbbf65e94ae7` — 1 breaking
  - the response property `responses/items/body/anyOf[subschema #1]/source_id` became optional for the status `200`
- **2025-05-08** `f09e5f2c555d` — 1 breaking, 20 warning, 5 info
  - the `responses/items/body` response's property type/format changed from `object`/`` to ``/`` for status `200`
  - removed the optional property `responses/items/body/class_code` from the response with the `200` status
  - removed the optional property `responses/items/body/custom_fields` from the response with the `200` status
  - removed the optional property `responses/items/body/department` from the response with the `200` status
  - …22 more

[Full history](https://skmtc.dev/finch-api/apis/api-reference/changes/employer/employment/post.md)

---

[API](https://skmtc.dev/finch-api/apis/api-reference.md) · [All operations](https://skmtc.dev/finch-api/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/finch-api/api-reference/revisions/0105d239fcaf/schema)