Deductions
Documents
Management
Sandbox
- POSTCreate a new Sandbox Connection
- POSTCreate a new sandbox account
- PUTUpdate a sandbox account
- GETGet configurations for sandbox jobs
- PUTUpdate configurations for sandbox jobs
- POSTAdd a new sandbox payment
- PUTUpdate sandbox individual
- PUTUpdate sandbox employment
- POSTAdd new individuals to a sandbox company
- PUTUpdate a sandbox company's data
- POSTEnqueue a new sandbox job
Development Guides
Employment
Read individual employment and income data
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": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"code": 123,
"body": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"title": "<string>",
"manager": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"department": {
"name": "<string>"
},
"employment": {
"type": "employee",
"subtype": "full_time"
},
"start_date": "<string>",
"end_date": "<string>",
"latest_rehire_date": "<string>",
"is_active": true,
"employment_status": "active",
"class_code": "<string>",
"location": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"name": "<string>",
"source_id": "<string>"
},
"income": {
"unit": "yearly",
"amount": 123,
"currency": "<string>",
"effective_date": "<string>"
},
"income_history": [
{
"unit": "yearly",
"amount": 123,
"currency": "<string>",
"effective_date": "<string>"
}
],
"custom_fields": [
{
"name": "<string>",
"value": "<any>"
}
],
"source_id": "<string>",
"work_id": "<string>"
}
}
]
}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
Please use your Access Token
Headers
Header used to specify the version for a given API request. Current version is 2020-09-17.
Used to indicate the original media type of the resource
Body
Individual Ids Request Body
The array of batch requests.
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
A stable Finch id (UUID v4) for an individual in the company.
A stable Finch id (UUID v4) for an individual in the company.
The legal first name of the individual.
The legal middle name of the individual.
The legal last name of the individual.
The current title of the individual.
The manager object representing the manager of the individual within the org.
A stable Finch id (UUID v4) for an individual in the company.
The department object.
The name of the department associated with the individual.
The employment object.
The main employment type of the individual.
employee, contractor The secondary employment type of the individual. Options: full_time, part_time, intern, temp, seasonal and individual_contractor.
full_time, intern, part_time, temp, seasonal, individual_contractor true if the individual an an active employee or contractor at the company.
The detailed employment status of the individual. Available options: active, deceased, leave, onboarding, prehire, retired, terminated.
active, deceased, leave, onboarding, prehire, retired, terminated Worker's compensation classification code for this employee
Street address or PO box.
Apartment, suite, unit, or building.
City, district, suburb, town, or village.
The state code.
The postal code or zip code.
The 2-letter ISO 3166 country code.
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.
The income unit of payment. Options: yearly, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, hourly, and fixed.
yearly, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, hourly, fixed The income amount in cents.
The currency code.
The date the income amount went into effect.
The array of income history.
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.
The income unit of payment. Options: yearly, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, hourly, and fixed.
yearly, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, hourly, fixed The income amount in cents.
The currency code.
The date the income amount went into effect.
The source system's unique employment identifier for this individual
This field is deprecated in favour of source_id
Was this page helpful?
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": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"code": 123,
"body": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"title": "<string>",
"manager": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"department": {
"name": "<string>"
},
"employment": {
"type": "employee",
"subtype": "full_time"
},
"start_date": "<string>",
"end_date": "<string>",
"latest_rehire_date": "<string>",
"is_active": true,
"employment_status": "active",
"class_code": "<string>",
"location": {
"line1": "<string>",
"line2": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"country": "<string>",
"name": "<string>",
"source_id": "<string>"
},
"income": {
"unit": "yearly",
"amount": 123,
"currency": "<string>",
"effective_date": "<string>"
},
"income_history": [
{
"unit": "yearly",
"amount": 123,
"currency": "<string>",
"effective_date": "<string>"
}
],
"custom_fields": [
{
"name": "<string>",
"value": "<any>"
}
],
"source_id": "<string>",
"work_id": "<string>"
}
}
]
}