> ## Documentation Index > Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt > Use this file to discover all available pages before exploring further. # Employment > 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. ## OpenAPI ````yaml post /employer/employment openapi: 3.1.0 info: title: API Reference version: '2020-09-17' contact: {} description: >- The Finch HRIS API provides a unified way to connect to a multitide of HRIS systems. The API requires an access token issued by Finch. By default, Organization and Payroll requests use Finch's [Data Syncs](/developer-resources/Data-Syncs). If a request is made before the initial sync has completed, Finch will request data live from the provider. The latency on live requests may range from seconds to minutes depending on the provider and batch size. For automated integrations, Deductions requests (both read and write) are always made live to the provider. Latencies may range from seconds to minutes depending on the provider and batch size. Employer products are specified by the product parameter, a space-separated list of products that your application requests from an employer authenticating through Finch Connect. Valid product names are— - `company`: Read basic company data - `directory`: Read company directory and organization structure - `individual`: Read individual data, excluding income and employment data - `employment`: Read individual employment and income data - `payment`: Read payroll and contractor related payments by the company - `pay_statement`: Read detailed pay statements for each individual - `benefits`: Create and manage deductions and contributions and enrollment for an employer [![Open in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4?action=collection%2Ffork&collection-url=entityId%3D21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4%26entityType%3Dcollection%26workspaceId%3D1edf19bc-e0a8-41e9-ac55-481a4b50790b) servers: - url: https://api.tryfinch.com description: '' security: [] tags: - name: Organization - name: Payroll - name: Deductions - name: Management - name: Sandbox paths: /employer/employment: post: tags: - Organization summary: Employment description: Read individual employment and income data operationId: get-employment parameters: - name: entity_ids in: query required: false description: The entity IDs to specify which entities' data to access. schema: type: array items: type: string format: uuid minItems: 1 maxItems: 1 example: - 550e8400-e29b-41d4-a716-446655440000 style: form explode: true - $ref: '#/components/parameters/API-Version' - $ref: '#/components/parameters/Content-Type' requestBody: $ref: '#/components/requestBodies/Individual-Ids' responses: '200': description: Employment data content: application/json: schema: $ref: '#/components/schemas/GetEmploymentResponse' examples: Success: value: 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 flsa_status: exempt 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 source_id: VWK-88a8505d BatchError: value: responses: - individual_id: 8b3f8edc-735d-4382-84d6-104eac2013b5 code: 404 body: code: 404 finch_code: individual_not_found message: >- No individual with id 8b3f8edc-735d-4382-84d6-104eac2013b5 found name: not_found_error '202': description: >- The request has been accepted for processing, but data is not yet available content: application/json: schema: $ref: '#/components/schemas/AcceptedResponse' examples: DataSyncInProgress: value: code: 202 name: sync_in_progress finch_code: data_sync_in_progress message: >- The data being requested is being fetched. Please check back later. AuthorizationPending: value: code: 202 name: authorization_pending finch_code: pending message: Authorization to this company's data is pending security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: >- 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); } - lang: Python source: |- from finch import Finch client = Finch( access_token="My Access Token", ) page = client.hris.employments.retrieve_many( requests=[{ "individual_id": "individual_id" }], ) page = page.responses[0] print(page.individual_id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go\"\n\t\"github.com/Finch-API/finch-api-go/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithAccessToken(\"My Access Token\"),\n\t)\n\tpage, err := client.HRIS.Employments.GetMany(context.TODO(), finchgo.HRISEmploymentGetManyParams{\n\t\tRequests: finchgo.F([]finchgo.HRISEmploymentGetManyParamsRequest{{\n\t\t\tIndividualID: finchgo.F(\"individual_id\"),\n\t\t}}),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Java source: |- package com.tryfinch.api.example; import com.tryfinch.api.client.FinchClient; import com.tryfinch.api.client.okhttp.FinchOkHttpClient; import com.tryfinch.api.models.HrisEmploymentRetrieveManyPage; import com.tryfinch.api.models.HrisEmploymentRetrieveManyParams; public final class Main { private Main() {} public static void main(String[] args) { FinchClient client = FinchOkHttpClient.builder() .fromEnv() .accessToken("My Access Token") .build(); HrisEmploymentRetrieveManyParams params = HrisEmploymentRetrieveManyParams.builder() .addRequest(HrisEmploymentRetrieveManyParams.Request.builder() .individualId("individual_id") .build()) .build(); HrisEmploymentRetrieveManyPage page = client.hris().employments().retrieveMany(params); } } - lang: Kotlin source: |- package com.tryfinch.api.example import com.tryfinch.api.client.FinchClient import com.tryfinch.api.client.okhttp.FinchOkHttpClient import com.tryfinch.api.models.HrisEmploymentRetrieveManyPage import com.tryfinch.api.models.HrisEmploymentRetrieveManyParams fun main() { val client: FinchClient = FinchOkHttpClient.builder() .fromEnv() .accessToken("My Access Token") .build() val params: HrisEmploymentRetrieveManyParams = HrisEmploymentRetrieveManyParams.builder() .addRequest(HrisEmploymentRetrieveManyParams.Request.builder() .individualId("individual_id") .build()) .build() val page: HrisEmploymentRetrieveManyPage = client.hris().employments().retrieveMany(params) } - lang: Ruby source: >- require "finch_api" finch = FinchAPI::Client.new(access_token: "My Access Token") page = finch.hris.employments.retrieve_many(requests: [{individual_id: "individual_id"}]) puts(page) components: parameters: API-Version: name: Finch-API-Version in: header required: true schema: type: string default: '2020-09-17' format: date pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) description: >- Header used to specify the version for a given API request. Current version is 2020-09-17. Content-Type: name: Content-Type in: header required: true schema: type: string default: application/json description: 'Used to indicate the original media type of the resource ' requestBodies: Individual-Ids: content: application/json: schema: type: object description: Individual Ids Request Body properties: requests: type: array description: The array of batch requests. items: type: object properties: individual_id: type: string description: >- 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. required: - individual_id required: - requests schemas: GetEmploymentResponse: type: object properties: responses: type: array items: type: object properties: individual_id: type: string description: >- A stable Finch `id` (UUID v4) for an individual in the company. pattern: '[0-9a-fA-F]{8}[-]?(?:[0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12}' format: uuid code: type: integer body: anyOf: - type: object properties: first_name: type: string description: The legal first name of the individual. nullable: true middle_name: type: string description: The legal middle name of the individual. nullable: true last_name: type: string description: The legal last name of the individual. nullable: true title: type: string description: The current title of the individual. nullable: true manager: type: object nullable: true properties: id: type: string description: >- A stable Finch `id` (UUID v4) for an individual in the company. pattern: >- [0-9a-fA-F]{8}[-]?(?:[0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12} format: uuid required: - id description: >- The manager object representing the manager of the individual within the org. department: type: object nullable: true properties: name: type: string description: >- The name of the department associated with the individual. nullable: true required: - name description: The department object. employment: type: object nullable: true properties: type: type: string description: The main employment type of the individual. enum: - employee - contractor - null nullable: true subtype: type: string description: >- The secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`. enum: - full_time - intern - part_time - temp - seasonal - individual_contractor - null nullable: true required: - type - subtype description: The employment object. start_date: $ref: '#/components/schemas/Date' end_date: $ref: '#/components/schemas/Date' latest_rehire_date: $ref: '#/components/schemas/Date' is_active: type: boolean description: >- `true` if the individual an an active employee or contractor at the company. nullable: true employment_status: type: string description: The detailed employment status of the individual. enum: - active - deceased - leave - onboarding - prehire - retired - terminated - null nullable: true flsa_status: type: string description: >- The FLSA status of the individual. Available options: `exempt`, `non_exempt`, `unknown`. enum: - exempt - non_exempt - unknown - null nullable: true class_code: type: string description: >- Worker's compensation classification code for this employee nullable: true location: $ref: '#/components/schemas/Location' income: $ref: '#/components/schemas/Income' income_history: type: array description: The array of income history. nullable: true items: $ref: '#/components/schemas/Income' custom_fields: type: array nullable: true description: >- 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. items: type: object properties: name: type: string nullable: true value: type: - string - array - object - number - boolean - 'null' nullable: true source_id: type: string nullable: true description: >- The source system's unique employment identifier for this individual id: type: string description: >- A stable Finch `id` (UUID v4) for an individual in the company. pattern: >- [0-9a-fA-F]{8}[-]?(?:[0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12} format: uuid work_id: type: string nullable: true description: This field is deprecated in favour of `source_id` deprecated: true required: - first_name - middle_name - last_name - title - manager - department - employment - start_date - end_date - latest_rehire_date - is_active - employment_status - flsa_status - class_code - location - id title: EmploymentData - $ref: '#/components/schemas/BatchError' required: - individual_id - code - body required: - responses AcceptedResponse: type: object properties: code: type: number default: 202 name: type: string finch_code: type: string message: type: string required: - name - finch_code - message Date: type: string title: Date nullable: true pattern: (\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) Location: type: object nullable: true properties: line1: type: string nullable: true description: Street address or PO box. line2: type: string nullable: true description: Apartment, suite, unit, or building. city: type: string nullable: true description: City, district, suburb, town, or village. state: type: string nullable: true description: The state code. postal_code: type: string nullable: true description: The postal code or zip code. country: type: string nullable: true description: The 2-letter ISO 3166 country code. name: type: string nullable: true source_id: type: string nullable: true required: - line1 - line2 - city - state - postal_code - country description: '' title: Location x-tags: - Models Income: type: object nullable: true properties: unit: type: string nullable: true enum: - yearly - quarterly - monthly - semi_monthly - bi_weekly - weekly - daily - hourly - fixed - null description: >- The income unit of payment. Options: `yearly`, `quarterly`, `monthly`, `semi_monthly`, `bi_weekly`, `weekly`, `daily`, `hourly`, and `fixed`. amount: type: integer nullable: true description: The income amount in cents. currency: type: string nullable: true description: The currency code. effective_date: type: string nullable: true format: date description: The date the income amount went into effect. required: - unit - amount - currency - effective_date description: >- 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. title: Income x-tags: - Models BatchError: type: object properties: code: type: number finch_code: type: string message: type: string name: type: string required: - code - message - name securitySchemes: bearerAuth: type: http scheme: bearer description: Please use your Access Token ````