The Documents API from Finch — 2 operation(s) for documents.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/finch:finch-documents-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Reference Documents API
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. 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
'
servers:
- url: https://api.tryfinch.com
description: ''
tags:
- name: Documents
paths:
/employer/documents:
get:
summary: List Documents
description: '**Beta:** This endpoint is in beta and may change.
Retrieve a list of company-wide documents.'
operationId: list-documents
tags:
- Documents
parameters:
- name: entity_ids
in: query
required: false
description: The entity IDs to specify which entities' data to access. Provide exactly one entity ID per request; a maximum of one is accepted.
schema:
type: array
items:
type: string
format: uuid
minItems: 1
maxItems: 1
example:
- 550e8400-e29b-41d4-a716-446655440000
style: form
explode: true
- name: limit
in: query
description: Number of documents to return (defaults to all)
required: false
schema:
type: integer
- name: offset
in: query
description: Index to start from (defaults to 0)
required: false
schema:
type: integer
- name: individual_ids
in: query
description: Comma-delimited list of stable Finch uuids for each individual. If empty, defaults to all individuals
required: false
schema:
type: array
items:
type: string
- name: types
in: query
description: Comma-delimited list of document types to filter on. If empty, defaults to all types
required: false
schema:
type: array
items:
type: string
enum:
- w4_2020
- w4_2005
- $ref: '#/components/parameters/API-Version'
security:
- bearerAuth: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListDocumentsResponse'
examples:
Success:
value:
paging:
count: 1
offset: 0
documents:
- id: 238b1d2a-3172-4b4a-a825-b04c0b2d0cac
individual_id: f92b3db4-7bcb-4a54-a570-396bf99e041a
year: 2020
url: https://api.tryfinch.com/employer/documents/238b1d2a-3172-4b4a-a825-b04c0b2d0cac
type: w4_2020
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
finch_code:
type: string
enum:
- w4_sync_required
message:
type: string
name:
type: string
example: bad_request
context:
type: object
properties:
docs_url:
type: string
format: uri
required:
- code
- finch_code
- message
- name
- context
examples:
W4SyncRequired:
value:
code: 400
finch_code: w4_sync_required
message: W4 documents are not available. Please trigger a W4 sync job first.
name: bad_request
context:
docs_url: https://developer.tryfinch.com/api-reference/management/enqueue-a-new-automated-job#w4-form-employee-sync
x-codeSamples:
- lang: JavaScript
source: "import Finch from '@tryfinch/finch-api';\n\nconst client = new Finch({\n accessToken: 'My Access Token',\n});\n\nconst documents = await client.hris.documents.list();\n\nconsole.log(documents.documents);"
- lang: Python
source: "from finch import Finch\n\nclient = Finch(\n access_token=\"My Access Token\",\n)\ndocuments = client.hris.documents.list()\nprint(documents.documents)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go/v2\"\n\t\"github.com/Finch-API/finch-api-go/v2/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithAccessToken(\"My Access Token\"),\n\t)\n\tdocuments, err := client.HRIS.Documents.List(context.TODO(), finchgo.HRISDocumentListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", documents.Documents)\n}\n"
- lang: Java
source: "package com.tryfinch.api.example;\n\nimport com.tryfinch.api.client.FinchClient;\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient;\nimport com.tryfinch.api.models.DocumentListResponse;\nimport com.tryfinch.api.models.HrisDocumentListParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n FinchClient client = FinchOkHttpClient.builder()\n .fromEnv()\n .accessToken(\"My Access Token\")\n .build();\n\n DocumentListResponse documents = client.hris().documents().list();\n }\n}"
- lang: Kotlin
source: "package com.tryfinch.api.example\n\nimport com.tryfinch.api.client.FinchClient\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient\nimport com.tryfinch.api.models.DocumentListResponse\nimport com.tryfinch.api.models.HrisDocumentListParams\n\nfun main() {\n val client: FinchClient = FinchOkHttpClient.builder()\n .fromEnv()\n .accessToken(\"My Access Token\")\n .build()\n\n val documents: DocumentListResponse = client.hris().documents().list()\n}"
- lang: Ruby
source: 'require "finch_api"
finch = FinchAPI::Client.new(access_token: "My Access Token")
documents = finch.hris.documents.list
puts(documents)'
/employer/documents/{document_id}:
get:
summary: Get Document
description: '**Beta:** This endpoint is in beta and may change.
Retrieve details of a specific document by its ID.'
operationId: get-document
tags:
- Documents
parameters:
- name: entity_ids
in: query
required: false
description: The entity IDs to specify which entities' data to access. Provide exactly one entity ID per request; a maximum of one is accepted.
schema:
type: array
items:
type: string
format: uuid
minItems: 1
maxItems: 1
example:
- 550e8400-e29b-41d4-a716-446655440000
style: form
explode: true
- name: document_id
in: path
description: The unique identifier of the document.
required: true
schema:
type: string
- $ref: '#/components/parameters/API-Version'
security:
- bearerAuth: []
responses:
'200':
description: Successful response with document data specific to form type.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/W4Document2020'
- $ref: '#/components/schemas/W4Document2005'
discriminator:
propertyName: type
examples:
W4_2005:
value:
type: w4_2005
year: 2005
data:
individual_id: f92b3db4-7bcb-4a54-a570-396bf99e041a
filing_status: married
total_number_of_allowances: 22000
additional_withholding: 10000
exemption: exempt
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
finch_code:
type: string
enum:
- w4_sync_required
message:
type: string
name:
type: string
example: bad_request
context:
type: object
properties:
docs_url:
type: string
format: uri
required:
- code
- finch_code
- message
- name
- context
examples:
W4SyncRequired:
value:
code: 400
finch_code: w4_sync_required
message: W4 documents are not available. Please trigger a W4 sync job first.
name: bad_request
context:
docs_url: https://developer.tryfinch.com/api-reference/management/enqueue-a-new-automated-job#w4-form-employee-sync
x-codeSamples:
- lang: JavaScript
source: "import Finch from '@tryfinch/finch-api';\n\nconst client = new Finch({\n accessToken: 'My Access Token',\n});\n\nconst response = await client.hris.documents.retreive('document_id');\n\nconsole.log(response);"
- lang: Python
source: "from finch import Finch\n\nclient = Finch(\n access_token=\"My Access Token\",\n)\nresponse = client.hris.documents.retreive(\n document_id=\"document_id\",\n)\nprint(response)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go/v2\"\n\t\"github.com/Finch-API/finch-api-go/v2/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithAccessToken(\"My Access Token\"),\n\t)\n\tresponse, err := client.HRIS.Documents.Retreive(\n\t\tcontext.TODO(),\n\t\t\"document_id\",\n\t\tfinchgo.HRISDocumentRetreiveParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response)\n}\n"
- lang: Java
source: "package com.tryfinch.api.example;\n\nimport com.tryfinch.api.client.FinchClient;\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient;\nimport com.tryfinch.api.models.DocumentRetreiveResponse;\nimport com.tryfinch.api.models.HrisDocumentRetreiveParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n FinchClient client = FinchOkHttpClient.builder()\n .fromEnv()\n .accessToken(\"My Access Token\")\n .build();\n\n DocumentRetreiveResponse response = client.hris().documents().retreive(\"document_id\");\n }\n}"
- lang: Kotlin
source: "package com.tryfinch.api.example\n\nimport com.tryfinch.api.client.FinchClient\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient\nimport com.tryfinch.api.models.DocumentRetreiveResponse\nimport com.tryfinch.api.models.HrisDocumentRetreiveParams\n\nfun main() {\n val client: FinchClient = FinchOkHttpClient.builder()\n .fromEnv()\n .accessToken(\"My Access Token\")\n .build()\n\n val response: DocumentRetreiveResponse = client.hris().documents().retreive(\"document_id\")\n}"
- lang: Ruby
source: 'require "finch_api"
finch = FinchAPI::Client.new(access_token: "My Access Token")
response = finch.hris.documents.retreive("document_id")
puts(response)'
components:
schemas:
W4Document2005:
type: object
properties:
type:
type: string
enum:
- w4_2005
description: Specifies the form type, indicating that this document is a 2005 W4 form.
year:
type: number
description: The tax year this W4 document applies to.
data:
type: object
properties:
individual_id:
type: string
format: uuid
description: The unique identifier for the individual associated with this 2005 W4 form.
filing_status:
type: string
nullable: true
enum:
- married
- married_but_withhold_at_higher_single_rate
- single
- null
description: The individual's filing status for tax purposes.
total_number_of_allowances:
type: integer
description: Total number of allowances claimed (in cents).
additional_withholding:
type: integer
description: Additional withholding amount (in cents).
exemption:
type: string
nullable: true
enum:
- exempt
- non_exempt
- null
description: Indicates exemption status from federal tax withholding.
required:
- individual_id
- filing_status
- total_number_of_allowances
- additional_withholding
- exemption
description: Detailed information specific to the 2005 W4 form.
required:
- type
- year
- data
description: A 2005 version of the W-4 tax form containing information on an individual's filing status, dependents, and withholding details.
x-stainless-variantName: w42005
DocumentItem:
type: object
properties:
id:
type: string
format: uuid
description: A stable Finch id for the document.
individual_id:
type: string
nullable: true
description: The ID of the individual associated with the document. This will be null for employer-level documents.
url:
type: string
format: uri
description: 'A URL to access the document. Format: `https://api.tryfinch.com/employer/documents/:document_id`.'
year:
type: number
description: The year the document applies to, if available.
type:
type: string
enum:
- w4_2020
- w4_2005
description: The type of document.
required:
- id
- individual_id
- url
- year
- type
W4Document2020:
type: object
properties:
type:
type: string
enum:
- w4_2020
description: Specifies the form type, indicating that this document is a 2020 W4 form.
year:
type: number
description: The tax year this W4 document applies to.
data:
type: object
properties:
individual_id:
type: string
format: uuid
description: The unique identifier for the individual associated with this document.
filing_status:
type: string
nullable: true
enum:
- head_of_household
- married_filing_jointly_or_qualifying_surviving_spouse
- single_or_married_filing_separately
- null
description: The individual's filing status for tax purposes.
amount_for_qualifying_children_under_17:
type: integer
description: Amount claimed for dependents under 17 years old (in cents).
total_claim_dependent_and_other_credits:
type: integer
description: Total amount claimed for dependents and other credits (in cents).
amount_for_other_dependents:
type: integer
description: Amount claimed for dependents other than qualifying children under 17 (in cents).
other_income:
type: integer
description: Additional income from sources outside of primary employment (in cents).
deductions:
type: integer
description: Deductible expenses (in cents).
extra_withholding:
type: integer
description: Additional withholding amount (in cents).
required:
- individual_id
- filing_status
- amount_for_qualifying_children_under_17
- total_claim_dependent_and_other_credits
- amount_for_other_dependents
- other_income
- deductions
- extra_withholding
description: Detailed information specific to the 2020 W4 form.
required:
- type
- year
- data
description: A 2020 version of the W-4 tax form containing information on an individual's filing status, dependents, and withholding details.
x-stainless-variantName: w42020
ListDocumentsResponse:
type: object
properties:
paging:
$ref: '#/components/schemas/Paging'
documents:
type: array
items:
$ref: '#/components/schemas/DocumentItem'
required:
- paging
- documents
Paging:
type: object
properties:
count:
type: integer
description: The total number of elements for the entire query (not just the given page)
x-stainless-pagination-property:
purpose: offset_total_count_field
offset:
type: integer
description: The current start index of the returned list of elements
x-stainless-pagination-property:
purpose: offset_count_start_field
required:
- offset
title: Paging
x-tags:
- Models
parameters:
API-Version:
name: Finch-API-Version
in: header
required: true
schema:
type: string
default: '2020-09-17'
format: date
description: Header used to specify the version for a given API request. Current version is 2020-09-17.
x-stainless-param: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Please use your Access Token
basicAuth:
type: http
scheme: basic
description: Please use base64 encoded client_id:client_secret
x-provenance:
method: harvested
publisher: Finch
source: https://developer.tryfinch.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)