{ "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.\n\nBy 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.\nFor 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.\n\n\nEmployer 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—\n- `company`: Read basic company data\n\n- `directory`: Read company directory and organization structure\n\n- `individual`: Read individual data, excluding income and employment data\n\n- `employment`: Read individual employment and income data\n\n- `payment`: Read payroll and contractor related payments by the company\n\n- `pay_statement`: Read detailed pay statements for each individual\n\n- `benefits`: Create and manage deductions and contributions and enrollment for an employer\n\n[![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": "" }], "tags": [ { "name": "Organization" }, { "name": "Payroll" }, { "name": "Deductions" }, { "name": "Management" }, { "name": "Sandbox" } ], "paths": { "/employer/company": { "get": { "description": "Read basic company data", "summary": "Company", "tags": ["Organization"], "operationId": "get-company", "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 }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Basic company data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCompanyResponse" }, "examples": { "Success": { "value": { "id": "514aa2b7-898f-4ce7-bc05-c2fe993713e8", "legal_name": "Acme, Inc.", "entity": { "type": "corporation", "subtype": "s_corporation" }, "ein": "12-3456789", "primary_email": "founders@acme.com", "primary_phone_number": "+14475678901", "departments": [ { "name": "Engineering", "parent": null }, { "name": "Platform", "parent": { "name": "Engineering" } } ], "locations": [ { "line1": "628 Bear Ave", "line2": "Apt A", "city": "Schenectady", "state": "NY", "postal_code": "94301", "country": "US" } ], "accounts": [ { "routing_number": "123456789", "account_name": "CHECKING ACCOUNT", "institution_name": "BANK OF AMERICA, N.A.", "account_type": "checking", "account_number": "98765432" } ] } } } } } }, "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" } } } } } } } } }, "/employer/directory": { "get": { "description": "Read company directory and organization structure", "summary": "Directory", "operationId": "get-directory", "tags": ["Organization"], "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 employees to return (defaults to 100, maximum 10000)", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 10000 } }, { "name": "offset", "in": "query", "description": "Index to start from (defaults to 0)", "required": false, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Company directory and organization structure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDirectoryResponse" }, "examples": { "Success": { "value": { "paging": { "count": 25, "offset": 10 }, "individuals": [ { "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "first_name": "Jane", "middle_name": null, "last_name": "Doe", "manager": { "id": "c205b3fa-b626-4346-bf0f-ca065ab88d31" }, "department": { "name": "Product" }, "is_active": true } ] } } } } } }, "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" } } } } } }, "422": { "description": "The request could not be processed due to a validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "finch_code": { "type": "string" } }, "required": ["code", "name", "message", "finch_code"] }, "examples": { "PageSizeLimitExceeded": { "value": { "code": 422, "name": "unprocessable_entity_error", "finch_code": "page_size_limit_exceeded", "message": "Page size exceeds the maximum of 10000 items. Please reduce the limit parameter." } } } } } } } } }, "/employer/individual": { "post": { "description": "Read individual data, excluding income and employment data", "summary": "Individual", "operationId": "get-individual", "tags": ["Organization"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "description": "The array of batch requests. Maximum 10000 items per request.", "maxItems": 10000, "items": { "type": "object", "properties": { "individual_id": { "type": "string" } }, "required": ["individual_id"] } }, "options": { "type": "object", "nullable": true, "properties": { "include": { "type": "array", "items": { "type": "string" } } } } }, "required": ["requests"] } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Individual data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetIndividualsResponse" }, "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", "preferred_name": "Janey", "emails": [ { "data": "jane@acme.com", "type": "work" }, { "data": "janed@personal.com", "type": "personal" } ], "phone_numbers": [{ "data": "+14475678901", "type": "personal" }], "gender": "female", "ethnicity": "black_or_african_american", "marital_status": "married", "dob": "1970-01-01", "residence": { "line1": "123 Main St", "line2": "Apt C", "city": "Schenectady", "state": "NY", "postal_code": "12345", "country": "US" } } } ] } }, "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" } } } } } }, "422": { "description": "The request could not be processed due to a validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "finch_code": { "type": "string" } }, "required": ["code", "name", "message", "finch_code"] }, "examples": { "BatchLimitExceeded": { "value": { "code": 422, "name": "unprocessable_entity_error", "finch_code": "batch_limit_exceeded", "message": "Batch size exceeds the maximum of 10000 items. Please reduce the number of items in your request." } } } } } } } } }, "/employer/employment": { "post": { "description": "Read individual employment and income data", "summary": "Employment", "operationId": "get-employment", "tags": ["Organization"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Individual Ids Request Body", "properties": { "requests": { "type": "array", "description": "The array of batch requests. Maximum 10000 items per request.", "maxItems": 10000, "items": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for an individual in the company." } }, "required": ["individual_id"] } } }, "required": ["requests"] } } } }, "security": [{ "bearerAuth": [] }], "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", "union_code": null, "union_local": null, "highly_compensated_employee": false, "key_employee": false, "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" } } } } } }, "422": { "description": "The request could not be processed due to a validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "finch_code": { "type": "string" } }, "required": ["code", "name", "message", "finch_code"] }, "examples": { "BatchLimitExceeded": { "value": { "code": 422, "name": "unprocessable_entity_error", "finch_code": "batch_limit_exceeded", "message": "Batch size exceeds the maximum of 10000 items. Please reduce the number of items in your request." } } } } } } } } }, "/employer/payment": { "get": { "description": "Read payroll and contractor related payments by the company.", "summary": "Payment", "operationId": "get-payment", "tags": ["Payroll"], "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": "start_date", "in": "query", "required": true, "description": "The start date to retrieve payments by a company (inclusive) in `YYYY-MM-DD` format. Filters payments by their **pay_date** field.", "schema": { "type": "string", "format": "date", "example": "2021-01-01" } }, { "name": "end_date", "in": "query", "required": true, "description": "The end date to retrieve payments by a company (inclusive) in `YYYY-MM-DD` format. Filters payments by their **pay_date** field.", "schema": { "type": "string", "format": "date", "example": "2021-01-01" } }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Payment data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentsResponse" }, "examples": { "Success": { "value": [ { "id": "20aa7cf2-949d-4d4e-9c01-499b59501ded", "pay_period": { "start_date": "2019-08-01", "end_date": "2019-08-15" }, "pay_date": "2019-08-22", "debit_date": "2019-08-22", "company_debit": { "amount": 5300000, "currency": "usd" }, "gross_pay": { "amount": 4000000, "currency": "usd" }, "net_pay": { "amount": 3200000, "currency": "usd" }, "employer_taxes": { "amount": 200000, "currency": "usd" }, "employee_taxes": { "amount": 350000, "currency": "usd" }, "individual_ids": [ "54719e14-5ea7-4fda-9898-f4d9ccb83c1a", "0ab620fc-203e-44ad-916c-facc69250f6f" ], "pay_group_ids": [ "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "9349eed4-4064-4641-ba8e-9e1ad7e1d014" ], "pay_frequencies": ["monthly", "weekly"] } ] } } } } }, "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" } } } } } } } } }, "/employer/pay-statement": { "post": { "description": "Read detailed pay statements for each individual.\n\nDeduction and contribution types are supported by the payroll systems that supports Benefits.", "summary": "Pay Statement", "operationId": "get-pay-statement", "tags": ["Payroll"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "description": "The array of batch requests. Maximum 10 payment_ids per request.", "minItems": 1, "maxItems": 10, "items": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for a payment.", "format": "uuid" }, "limit": { "type": "integer", "description": "Number of pay statements to return (defaults to 100, maximum 5000).", "default": 100, "maximum": 5000, "example": 50 }, "offset": { "type": "integer", "description": "Index to start from.", "example": 0 } }, "required": ["payment_id"] } } }, "required": ["requests"] }, "examples": { "example1": { "value": { "requests": [ { "payment_id": "fc8b024e-d373-4c9c-80fc-f1625383d142", "limit": 100, "offset": 0 } ] } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Pay statement data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPayStatementsResponse" }, "examples": { "Success": { "value": { "responses": [ { "payment_id": "fc8b024e-d373-4c9c-80fc-f1625383d142", "code": 200, "body": { "paging": { "count": 25, "offset": 10 }, "pay_statements": [ { "individual_id": "be7b048c-a6f3-4194-a017-2f537d4f3565", "type": "regular_payroll", "payment_method": "check", "total_hours": 42.5, "gross_pay": { "amount": 230000, "currency": "usd" }, "net_pay": { "amount": 180000, "currency": "usd" }, "earnings": [ { "type": "salary", "name": "Salary", "amount": 230000, "currency": "usd", "hours": 42.5 } ], "taxes": [ { "type": "state", "name": "State Withholding - OR", "employer": false, "amount": 0, "currency": "usd" } ], "employee_deductions": [ { "name": "Pre-Tax 401k", "amount": 50000, "currency": "usd", "pre_tax": true, "type": "401k" } ], "employer_contributions": [ { "name": "Employee Medical Insurance", "amount": 23272, "currency": "usd", "type": "s125_medical" } ] } ] } } ] } }, "RemainingPayStatement": { "value": { "responses": [ { "payment_id": "fc8b024e-d373-4c9c-80fc-f1625383d142", "code": 202, "body": { "code": 202, "finch_code": "data_sync_in_progress", "message": "The pay statements for this payment are being fetched. Please check back later.", "name": "accepted" } } ] } } } } } }, "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" } } } } } }, "422": { "description": "The request could not be processed due to a validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "finch_code": { "type": "string" } }, "required": ["code", "name", "message", "finch_code"] }, "examples": { "BatchLimitExceeded": { "value": { "code": 422, "name": "unprocessable_entity_error", "finch_code": "batch_limit_exceeded", "message": "Batch size exceeds the maximum of 10 payment_ids. Please reduce the number of payment_ids in your request." } }, "PageSizeLimitExceeded": { "value": { "code": 422, "name": "unprocessable_entity_error", "finch_code": "page_size_limit_exceeded", "message": "Page size exceeds the maximum of 5000 items. Please reduce the limit parameter." } } } } } } } } }, "/employer/pay-statement-item": { "get": { "description": "Retrieve a list of detailed pay statement items for the access token's connection account.\n", "summary": "Pay Statement Item", "operationId": "get-pay-statement-item", "tags": ["Payroll"], "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": "categories", "in": "query", "required": false, "description": "Comma-delimited list of pay statement item categories to filter on. If empty, defaults to all categories.", "schema": { "type": "array", "items": { "type": "string", "enum": ["earnings", "taxes", "employee_deductions", "employer_contributions"] } }, "style": "form", "explode": false }, { "name": "name", "in": "query", "required": false, "description": "Case-insensitive partial match search by pay statement item name.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "String search by pay statement item type.", "schema": { "type": "string", "example": "base_compensation" } }, { "name": "start_date", "in": "query", "required": false, "description": "The start date to retrieve pay statement items by via their last seen pay date (inclusive) in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "The end date to retrieve pay statement items by via their last seen pay date in `YYYY-MM-DD` format.", "schema": { "type": "string", "format": "date", "example": "2024-07-01" } }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Pay statement item data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPayStatementItemsResponse" } } } } } } }, "/employer/pay-statement-item/rule": { "post": { "summary": "Create Rule", "description": "Custom rules can be created to associate specific attributes to pay statement items depending on the use case. For example, pay statement items that meet certain conditions can be labeled as a pre-tax 401k. This metadata can be retrieved where pay statement item information is available.\n", "operationId": "create-rule", "tags": ["Payroll"], "parameters": [ { "name": "entity_ids", "in": "query", "required": false, "description": "The entity IDs to create the rule for. 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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRuleRequest" } } } }, "security": [{ "bearerAuth": [] }], "responses": { "201": { "description": "Successfully Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRuleResponse" }, "examples": { "Success": { "value": { "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "priority": 1, "effective_start_date": "2025-01-01", "effective_end_date": "2025-12-31", "conditions": [{ "field": "name", "operator": "equals", "value": "Salary" }], "attributes": { "metadata": { "myLabel": "My Value" } }, "entity_type": "pay_statement_item", "created_at": "2025-01-01T10:00:00Z", "updated_at": "2025-01-01T10:00:00Z" } } } } } }, "400": { "description": "Malformed Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad Request": { "value": { "code": 400, "name": "invalid_request_error", "finch_code": "invalid_request", "message": "Validation error: Array must contain at least 1 element(s) at \"conditions\"" } } } } } } } }, "get": { "summary": "Get Rules", "description": "List all rules of a connection account.", "operationId": "get-rules", "tags": ["Payroll"], "parameters": [ { "name": "entity_ids", "in": "query", "required": false, "description": "The entity IDs to retrieve rules for. 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 }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRulesResponse" } } } } } } }, "/employer/pay-statement-item/rule/{rule_id}": { "parameters": [{ "schema": { "type": "string" }, "name": "rule_id", "in": "path", "required": true }], "put": { "summary": "Update Rule", "operationId": "update-rule", "description": "Update a rule for a pay statement item.", "tags": ["Payroll"], "parameters": [ { "name": "entity_ids", "in": "query", "required": false, "description": "The entity IDs to update the rule for. 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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRuleRequest" } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Successfully Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRuleResponse" }, "examples": { "Success": { "value": { "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "priority": 1, "effective_start_date": null, "effective_end_date": "2025-12-31", "conditions": [{ "field": "name", "operator": "equals", "value": "Salary" }], "attributes": { "metadata": { "myLabel": "My Value" } }, "created_at": "2025-01-01T10:00:00Z", "updated_at": "2025-02-13T08:30:00Z" } } } } } }, "400": { "description": "Malformed Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad Request": { "value": { "code": 400, "name": "invalid_request_error", "finch_code": "invalid_request", "message": "Validation error: Array must contain at least 1 element(s) at \"conditions\"" } } } } } } } }, "delete": { "summary": "Delete Rule", "operationId": "delete-rule", "description": "Delete a rule for a pay statement item.", "tags": ["Payroll"], "parameters": [ { "name": "entity_ids", "in": "query", "required": false, "description": "The entity IDs to delete the rule for. 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 }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Successfully Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRuleResponse" }, "examples": { "Success": { "value": { "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "priority": 1, "effective_end_date": "2025-12-31", "conditions": [{ "field": "name", "operator": "equals", "value": "Salary" }], "attributes": { "metadata": { "myLabel": "My Value" } }, "created_at": "2025-01-01T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z", "deleted_at": "2025-02-13T08:30:00Z" } } } } } }, "400": { "description": "Malformed Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad Request": { "value": { "code": 400, "name": "invalid_request_error", "finch_code": "invalid_request", "message": "Rule 5d0b10a1-a09a-430f-81f1-20be735dc5e9 not found" } } } } } } } } }, "/employer/pay-groups": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "individual_id", "in": "query", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "name": "pay_frequencies", "in": "query", "required": false, "style": "form", "explode": false } ], "get": { "description": "Read company pay groups and frequencies", "summary": "Get All Pay Groups", "operationId": "get-all-pay-groups", "tags": ["Payroll"], "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 }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Company pay groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllPayGroupsResponse" }, "examples": { "Success": { "value": [ { "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "name": "Monthly", "pay_frequencies": ["monthly"] }, { "id": "9349eed4-4064-4641-ba8e-9e1ad7e1d014", "name": "Weekly", "pay_frequencies": ["weekly"] } ] } } } } } } } }, "/employer/pay-groups/{pay_group_id}": { "parameters": [ { "schema": { "type": "string" }, "name": "pay_group_id", "in": "path", "required": true } ], "get": { "description": "Read information from a single pay group", "summary": "Get Pay Group", "operationId": "get-pay-group", "tags": ["Payroll"], "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 }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Pay group data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPayGroupResponse" }, "examples": { "Success": { "value": { "id": "5d0b10a1-a09a-430f-81f1-20be735dc5e9", "name": "Monthly", "pay_frequencies": ["monthly"], "individual_ids": ["be7b048c-a6f3-4194-a017-2f537d4f3565"] } } } } } } } } }, "/employer/benefits": { "get": { "summary": "Get All Deductions", "description": "List all company-wide deductions and contributions.", "operationId": "get-company-benefits", "tags": ["Deductions"], "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 }, { "$ref": "#/components/parameters/API-Version" } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCompanyBenefitsResponse" }, "examples": { "Success": { "value": [ { "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782", "type": "401k", "description": "Example 401k", "frequency": "every_paycheck" } ] } } } } } } }, "post": { "summary": "Create Deduction", "description": "Creates a new company-wide deduction or contribution. Please use the `/providers` endpoint to view available types for each provider.", "operationId": "create-company-benefits", "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "tags": ["Deductions"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/BenefitType" }, "description": { "$ref": "#/components/schemas/BenefitDescription" }, "frequency": { "$ref": "#/components/schemas/BenefitFrequency" }, "company_contribution": { "$ref": "#/components/schemas/BenefitCompanyMatchContribution" } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "201": { "description": "Successfully Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompanyBenefitsResponse" }, "examples": { "Success": { "value": { "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782", "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7" } } } } } }, "400": { "description": "Malformed Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad Request": { "value": { "code": 400, "name": "invalid_request_error", "finch_code": "invalid_request", "message": "[body:description]: Not a valid string" } } } } } }, "422": { "description": "Request provided with unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid Benefit": { "value": { "code": 422, "name": "unprocessable_request_error", "finch_code": "unsupported_paramters", "message": "Provider does not support benefit type '401k'" } } } } } } } } }, "/employer/benefits/register": { "post": { "summary": "Register Deduction", "operationId": "register-company-benefits", "description": "Register existing benefits from the customer on the provider, on Finch's end. Please use the `/provider` endpoint to view available types for each provider.", "tags": ["Deductions"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/BenefitType" }, "description": { "type": "string" }, "frequency": { "$ref": "#/components/schemas/BenefitFrequency" } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "201": { "description": "Successfully Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCompanyBenefitResponse" }, "examples": { "Success": { "value": { "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782", "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7" } } } } } }, "400": { "description": "Requested adapter is not assisted benefits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request provided with unsupported parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Invalid Benefit": { "value": { "code": 422, "name": "unprocessable_request_error", "finch_code": "unsupported_paramters", "message": "Provider does not support benefit type '401k'" } } } } } } } } }, "/employer/documents": { "get": { "summary": "List Documents", "description": "**Beta:** This endpoint is in beta and may change.\nRetrieve a list of company-wide documents.\n", "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" } } } } } } } } } }, "/employer/documents/{document_id}": { "get": { "summary": "Get Document", "description": "**Beta:** This endpoint is in beta and may change.\nRetrieve details of a specific document by its ID.\n", "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" } } } } } } } } } }, "/employer/benefits/meta": { "get": { "summary": "[Deprecated] Get Deductions Metadata", "operationId": "get-company-benefits-meta", "description": "Get deductions metadata", "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 }, { "$ref": "#/components/parameters/API-Version" } ], "tags": ["Deductions"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCompanyBenefitsMetadataResponse" }, "examples": { "Metadata Example": { "value": [ { "type": "401k", "description": "401(k)", "employee_deduction": ["fixed", "percent"], "company_contribution": ["fixed", "percent"], "annual_maximum": true, "catch_up": true, "frequencies": ["every_paycheck"] } ] } } } } } } } }, "/employer/benefits/{benefit_id}": { "parameters": [ { "schema": { "type": "string" }, "name": "benefit_id", "in": "path", "required": true } ], "get": { "summary": "Get Deduction", "operationId": "get-company-benefit", "description": "Lists deductions and contributions information for a given item", "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 }, { "$ref": "#/components/parameters/API-Version" } ], "tags": ["Deductions"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyBenefit" }, "examples": { "Example Benefit": { "value": { "benefit_id": "6547e3aa-d887-4a77-bd41-17221e17cce3", "type": "401k", "description": "Example 401k", "frequency": "every_paycheck" } } } } } }, "404": { "description": "Benefit Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not Found": { "value": { "code": 404, "name": "not_found_error", "finch_code": "benefit_not_found", "message": "Benefit not found" } } } } } } } }, "post": { "summary": "Update Deduction", "operationId": "update-company-benefits", "description": "Updates an existing company-wide deduction or contribution", "tags": ["Deductions"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Updated name or description." } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyBenefitResponse" }, "examples": { "Success": { "value": { "benefit_id": "6547e3aa-d887-4a77-bd41-17221e17cce3", "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7" } } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Benefit Not Found" } } } }, "/employer/benefits/{benefit_id}/enrolled": { "parameters": [ { "schema": { "type": "string" }, "name": "benefit_id", "in": "path", "required": true } ], "get": { "summary": "Get Enrolled Individuals", "operationId": "get-company-benefits-enrolled", "description": "Lists individuals currently enrolled in a given deduction.", "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 }, { "$ref": "#/components/parameters/API-Version" } ], "tags": ["Deductions"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCompanyBenefitEnrolledIndividualsResponse" }, "examples": { "Success": { "value": { "benefit_id": "6547e3aa-d887-4a77-bd41-17221e17cce3", "individual_ids": ["7fc9fb3a-2a62-47c1-9a5a-c9146483b58e"] } } } } } }, "404": { "description": "Benefit Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not Found": { "value": { "code": 404, "name": "not_found_error", "finch_code": "benefit_not_found", "message": "Benefit not found" } } } } } } } } }, "/employer/benefits/{benefit_id}/individuals": { "parameters": [ { "schema": { "type": "string" }, "name": "benefit_id", "in": "path", "required": true } ], "get": { "summary": "Get Deductions for Individuals", "operationId": "get-individual-benefits", "description": "Get enrollment information for the given individuals.", "tags": ["Deductions"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "name": "individual_ids", "in": "query", "description": "comma-delimited list of stable Finch uuids for each individual. If empty, defaults to all individuals", "schema": { "type": "string", "example": "d675d2b7-6d7b-41a8-b2d3-001eb3fb88f6,d02a6346-1f08-4312-a064-49ff3cafaa7a" } } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndividualBenefits" } } } }, "207": { "description": "Multi-Status (WebDAV)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndividualBenefits" } } } }, "404": { "description": "Benefit Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not Found": { "value": { "code": 404, "name": "not_found_error", "finch_code": "benefit_not_found", "message": "Benefit not found" } } } } } } } }, "post": { "summary": "Enroll Individuals in Deductions", "operationId": "post-employer-individual-benefits-benefit_id", "description": "Enroll an individual into a deduction or contribution. This is an overwrite operation. If the employee is already enrolled, the enrollment amounts will be adjusted. Making the same request multiple times will not create new enrollments, but will continue to set the state of the existing enrollment.", "tags": ["Deductions"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "Finch id (uuidv4) for the individual to enroll" }, "configuration": { "type": "object", "properties": { "employee_deduction": { "type": "object", "properties": { "type": { "type": "string", "enum": ["fixed", "percent"] }, "amount": { "type": "integer", "description": "Amount in cents for fixed type or basis points (1/100th of a percent) for percent type" } } }, "company_contribution": { "type": "object", "properties": { "type": { "type": "string", "enum": ["fixed", "percent", "tiered"] }, "amount": { "type": "integer", "description": "Amount in cents for fixed type or basis points (1/100th of a percent) for percent type" }, "tiers": { "type": "array", "description": "Array of tier objects for tiered contribution matching (required when type is tiered)", "items": { "type": "object", "properties": { "match": { "type": "integer", "description": "The employer match percentage in basis points (0-10000 = 0-100%)" }, "threshold": { "type": "integer", "description": "The employee contribution threshold in basis points (0-10000 = 0-100%)" } }, "required": ["match", "threshold"] } } } }, "annual_maximum": { "type": "integer", "nullable": true, "description": "Maximum annual amount in cents" }, "annual_contribution_limit": { "type": "string", "enum": ["individual", "family"], "description": "For HSA benefits only - whether the contribution limit is for an individual or family" }, "catch_up": { "type": "boolean", "description": "For retirement benefits only - whether catch up contributions are enabled" }, "effective_date": { "type": "string", "format": "date", "description": "The date the enrollment will take effect" } } } } }, "description": "Array of the individual_id to enroll and a configuration object." }, "examples": { "HSA": { "value": [ { "individual_id": "d02a6346-1f08-4312-a064-49ff3cafaa7a", "configuration": { "employee_deduction": { "type": "fixed", "amount": 10000 }, "company_contribution": { "type": "fixed", "amount": 0 }, "annual_maximum": null, "annual_contribution_limit": "individual" } } ] }, "Custom": { "value": [ { "individual_id": "string", "configuration": { "employee_deduction": { "type": "fixed", "amount": 10000 }, "company_contribution": { "type": "fixed", "amount": 0 } } } ] } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Successfully enqueued job to enroll individuals in the benefit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollIndividualBenefitResponse" }, "examples": { "Success": { "value": { "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7" } } } } } }, "400": { "description": "Malformed Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Malformed Request": { "value": { "code": 400, "name": "bad_request_error", "finch_code": "malformed_request", "message": "Malformed request" } } } } } }, "404": { "description": "Benefit Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not Found": { "value": { "code": 404, "name": "not_found_error", "finch_code": "benefit_not_found", "message": "Benefit not found" } } } } } }, "422": { "description": "Unprocessable Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Cannot Enroll": { "value": { "code": 422, "name": "unprocessable_request_error", "finch_code": "unprocessable_parameters", "message": "HSA enrollment are not currently available for this provider" } } } } } } } }, "delete": { "summary": "Unenroll Individuals from Deductions", "operationId": "delete-individual-benefits", "description": "Unenroll individuals from a deduction or contribution", "tags": ["Deductions"], "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 }, { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "individual_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of individual_ids to unenroll." } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Successfully enqueued job to unenroll individuals from the benefit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnenrollIndividualBenefitResponse" }, "examples": { "Success": { "value": { "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7" } } } } } }, "404": { "description": "Benefit Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not Found": { "value": { "code": 404, "name": "not_found_error", "finch_code": "benefit_not_found", "message": "Benefit not found" } } } } } } } } }, "/auth/token": { "post": { "summary": "Create Access Token", "operationId": "create-access-token", "description": "Exchange the authorization code for an access token", "tags": ["Management"], "parameters": [ { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessTokenRequest" } } } }, "security": [], "responses": { "200": { "description": "Access Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessTokenResponse" }, "examples": { "Success": { "value": { "access_token": "7e965183-9332-423c-9259-3edafb332ad2", "token_type": "bearer", "connection_id": "bc3a2af9-ce03-46c4-9142-81abe789c64d", "customer_id": "1234567890", "customer_name": "Acme Inc", "account_id": "ac3a2af9-ce03-46c4-9142-81abe789c64d", "client_type": "production", "company_id": "4ab15e51-11ad-49f4-acae-f343b7794375", "connection_type": "provider", "products": ["directory", "employment", "individual"], "provider_id": "gusto", "entity_ids": [ "550e8400-e29b-41d4-a716-446655440000", "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "6ba7b811-9dad-11d1-80b4-00c04fd430c8" ] } } } } } } } } }, "/providers": { "get": { "summary": "Providers", "operationId": "get-providers", "description": "Return details on all available payroll and HR systems.", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "security": [{}, { "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProvidersResponse" } } } } } } }, "/introspect": { "get": { "summary": "Introspect", "operationId": "get-introspect", "description": "Read account information associated with an `access_token`", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetIntrospectResponse" } } } } } } }, "/disconnect": { "post": { "summary": "Disconnect", "operationId": "post-disconnect", "description": "Disconnect one or more `access_token`s from your application.", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectResponse" }, "examples": { "Success": { "value": { "status": "success" } } } } } } } } }, "/forward": { "post": { "summary": "Request Forwarding", "operationId": "post-forward", "description": "The Forward API allows you to make direct requests to an employment system. If Finch's unified API\ndoesn't have a data model that cleanly fits your needs, then Forward allows you to push or pull\ndata models directly against an integration's API.", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardRequest" } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardResponse" } } } } } } }, "/jobs/automated": { "get": { "summary": "List All Automated Jobs", "operationId": "get-jobs-automated", "description": "Get all automated jobs. Automated jobs are completed by a machine. By default, jobs are sorted in descending order by submission time. For scheduled jobs such as data syncs, only the next scheduled job is shown.", "tags": ["Management"], "parameters": [ { "$ref": "#/components/parameters/API-Version" }, { "name": "limit", "in": "query", "description": "Number of items to return", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Index to start from (defaults to 0)", "required": false, "schema": { "type": "integer" } } ], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Job was found", "content": { "application/json": { "schema": { "type": "object", "properties": { "": { "$ref": "#/components/schemas/Paging" }, "meta": { "type": "object", "properties": { "quotas": { "type": "object", "description": "Information about remaining quotas for this connection. Only applicable for customers opted in to use Finch's Data Sync Refresh endpoint (`POST /jobs/automated`). Please contact a Finch representative for more details.", "properties": { "data_sync_all": { "type": "object", "properties": { "allowed_refreshes": { "type": "integer" }, "remaining_refreshes": { "type": "integer" } } } } } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomatedAsyncJob" } } }, "required": ["", "meta", "data"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "status": { "type": "integer" }, "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": ["statusCode", "status", "code", "name", "message"] }, "examples": { "Example 1": { "value": { "statusCode": 401, "status": 401, "code": 401, "message": "Unauthorized request: no authentication given", "name": "unauthorized_request_error" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "status": { "type": "integer" }, "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": ["statusCode", "status", "code", "name", "message"] }, "examples": { "Example 1": { "value": { "statusCode": 404, "status": 404, "code": 404, "message": "could not find job with id job-fb3b25dc-02dc-48eb-9cfc-3f9837276884", "name": "not_found_error" } } } } } } } }, "post": { "summary": "Enqueue a New Automated Job", "operationId": "post-jobs-automated", "description": "Enqueue an automated job.\n\n`data_sync_all`: Enqueue a job to re-sync all data for a connection. `data_sync_all` has a concurrency limit of 1 job at a time per connection. This means that if this endpoint is called while a job is already in progress for this connection, Finch will return the `job_id` of the job that is currently in progress. Finch allows a fixed window rate limit of 1 forced refresh per hour per connection.\n\n`w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular individual, identified by `individual_id`. This feature is currently in beta.\n\nThis endpoint is available for *Scale* tier customers as an add-on. To request access to this endpoint, please contact your Finch account manager.", "tags": ["Management"], "parameters": [ { "$ref": "#/components/parameters/API-Version" }, { "$ref": "#/components/parameters/Content-Type" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "data_sync_all", "properties": { "type": { "type": "string", "description": "The type of job to start.", "enum": ["data_sync_all"] } }, "required": ["type"] }, { "type": "object", "title": "w4_form_employee_sync", "properties": { "type": { "type": "string", "description": "The type of job to start.", "enum": ["w4_form_employee_sync"] }, "params": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "The unique ID of the individual for W-4 data sync." } }, "required": ["individual_id"] } }, "required": ["type", "params"] } ], "discriminator": { "propertyName": "type" } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedJobResponse" }, "examples": { "Example 1": { "value": { "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", "job_url": "https://api.tryfinch.com/jobs/automated/453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", "allowed_refreshes": 2, "remaining_refreshes": 1 } } } } } }, "202": { "description": "Accepted. This response will be returned if a job is already enqueued for the connection. This case does not consume any job quota as it just returns the details of an existing job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedJobResponse" }, "examples": { "Example 1": { "value": { "job_id": "de9113d6-e2fa-4c72-ba4a-ee1d8a4f8df6", "job_url": "https://api.tryfinch.com/jobs/automated/de9113d6-e2fa-4c72-ba4a-ee1d8a4f8df6", "allowed_refreshes": 2, "remaining_refreshes": 2 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example 1": { "value": { "statusCode": 400, "status": 400, "code": 400, "message": "cannot create automated job for Assisted Connect token", "name": "bad_request" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example 1": { "value": { "statusCode": 401, "status": 401, "code": 401, "message": "Unauthorized request: no authentication given", "name": "unauthorized_request_error" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedJobResponse" }, "examples": { "Example 1": { "value": { "job_id": "de9113d6-e2fa-4c72-ba4a-ee1d8a4f8df6", "job_url": "https://api.tryfinch.com/jobs/automated/de9113d6-e2fa-4c72-ba4a-ee1d8a4f8df6", "allowed_refreshes": 2, "remaining_refreshes": 0, "retry_at": "2019-08-24T14:15:22Z" } } } } } } } } }, "/jobs/automated/{job_id}": { "parameters": [{ "schema": { "type": "string" }, "name": "job_id", "in": "path", "required": true }], "get": { "summary": "Retrieve an Automated Job", "operationId": "get-jobs-job_id", "description": "Get an automated job by `job_id`.", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedAsyncJob" } } } }, "404": { "description": "Not Found" } } } }, "/jobs/manual/{job_id}": { "parameters": [{ "schema": { "type": "string" }, "name": "job_id", "in": "path", "required": true }], "get": { "summary": "Retrieve a Manual Job", "operationId": "get-jobs-manual-job_id", "description": "Check the status and outcome of a job by `job_id`. This includes all deductions jobs including those for both automated and assisted integrations.", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualAsyncJob" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "finch_code": { "type": "string" }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "finch_code", "name", "message"] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "finch_code": { "type": "string" }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "finch_code", "name", "message"] }, "examples": { "Example 1": { "value": { "code": 404, "finch_code": "item_not_found", "name": "not_found_error", "message": "could not find job with id '49142223-78e0-4092-80e1-313f510b0977'" } } } } } } } } }, "/connect/sessions": { "post": { "summary": "Create a new connect session", "description": "Create a new connect session for an employer", "operationId": "post-connect-sessions", "tags": ["Connect"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectSessionRequest" } } } }, "security": [{ "basicAuth": [] }], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectSessionResponse" }, "examples": { "Success": { "value": { "session_id": "550e8400-e29b-41d4-a716-446655440000", "connect_url": "https://connect.tryfinch.com/authorize?session=550e8400-e29b-41d4-a716-446655440000" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "finch_code": { "type": "string", "enum": ["connection_already_exists", "invalid_request"], "example": "connection_already_exists" }, "message": { "type": "string", "example": "There's an existing connection for the customer_id: {customer_id}. Please use the /connect/sessions/reauthenticate endpoint instead." }, "name": { "type": "string", "example": "bad_request" }, "context": { "type": "object", "properties": { "customer_id": { "type": "string" }, "connection_id": { "type": "string" } } } }, "required": ["code", "finch_code", "message", "name", "context"] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "finch_code": { "type": "string", "example": "invalid_client" }, "message": { "type": "string", "example": "Invalid client: Unable to validate credentials" } }, "required": ["code", "finch_code", "message"] } } } } } } }, "/connect/sessions/reauthenticate": { "post": { "summary": "Create a new Connect session for reauthentication", "description": "Create a new Connect session for reauthenticating an existing connection", "operationId": "post-connect-sessions-reauthenticate", "tags": ["Connect"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthenticateRequest" } } } }, "security": [{ "basicAuth": [] }], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthenticateResponse" }, "examples": { "Success": { "value": { "session_id": "550e8400-e29b-41d4-a716-446655440000", "connect_url": "https://connect.tryfinch.com/authorize?session=550e8400-e29b-41d4-a716-446655440000" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "finch_code": { "type": "string", "enum": ["connection_not_found", "invalid_request"] } }, "required": ["code", "finch_code"] }, "examples": { "ConnectionNotFound": { "value": { "code": 400, "finch_code": "invalid_request", "message": "Connection not found", "name": "bad_request" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "finch_code": { "type": "string", "example": "invalid_client" }, "message": { "type": "string", "example": "Invalid client: Unable to validate credentials" } }, "required": ["code", "finch_code", "message"] } } } } } } }, "/sandbox/connections": { "post": { "summary": "Create a new Sandbox Connection", "operationId": "post-sandbox-connections", "description": "Create a new connection (new company/provider pair) with a new account", "tags": ["Sandbox"], "parameters": [], "security": [{ "basicAuth": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_id": { "type": "string", "description": "The provider associated with the connection" }, "authentication_type": { "$ref": "#/components/schemas/AuthenticationType" }, "products": { "type": "array", "items": { "type": "string" } }, "employee_size": { "type": "integer", "description": "Optional: the size of the employer to be created with this connection. Defaults to 20. Note that if this is higher than 100, historical payroll data will not be generated, and instead only one pay period will be created." } }, "required": ["provider_id"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "The ID of the new connection" }, "entity_id": { "type": "string", "format": "uuid", "description": "The ID of the entity for this connection" }, "company_id": { "type": "string", "format": "uuid", "description": "The Finch UUID of the company associated with the `access_token`." }, "provider_id": { "type": "string", "format": "uuid", "description": "The ID of the provider associated with the `access_token`." }, "account_id": { "type": "string", "format": "uuid", "deprecated": true, "description": "[DEPRECATED] Use `connection_id` to associate a connection with an access token" }, "authentication_type": { "$ref": "#/components/schemas/AuthenticationType" }, "products": { "type": "array", "items": { "type": "string" } }, "access_token": { "type": "string", "format": "uuid" }, "token_type": { "type": "string" } }, "required": [ "connection_id", "entity_id", "company_id", "provider_id", "account_id", "authentication_type", "products", "access_token" ] } } } } } } }, "/sandbox/connections/accounts": { "parameters": [], "post": { "summary": "Create a new sandbox account", "operationId": "post-sandbox-connections-accounts", "description": "Create a new account for an existing connection (company/provider pair)", "tags": ["Sandbox"], "security": [{ "basicAuth": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid" }, "provider_id": { "type": "string", "description": "The provider associated with the `access_token`" }, "authentication_type": { "$ref": "#/components/schemas/AuthenticationType" }, "products": { "type": "array", "description": "Optional, defaults to Organization products (`company`, `directory`, `employment`, `individual`)", "items": { "type": "string" } } }, "required": ["company_id", "provider_id"] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "The ID of the new connection" }, "entity_id": { "type": "string", "format": "uuid", "description": "The ID of the entity for this connection" }, "company_id": { "type": "string", "format": "uuid", "description": "The Finch UUID of the company associated with the `access_token`." }, "provider_id": { "type": "string", "description": "The ID of the provider associated with the `access_token`" }, "account_id": { "type": "string", "format": "uuid", "deprecated": true, "description": "[DEPRECATED] Use `connection_id` to associate a connection with an access token" }, "authentication_type": { "$ref": "#/components/schemas/AuthenticationType" }, "products": { "type": "array", "items": { "type": "string" } }, "access_token": { "type": "string", "format": "uuid" } }, "required": [ "connection_id", "entity_id", "company_id", "provider_id", "account_id", "authentication_type", "products", "access_token" ] }, "examples": { "Example 1": { "value": { "connection_id": "a237a1c3-1a5e-44ae-a8fd-81f76fd715c2", "entity_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65", "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf", "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65", "provider_id": "gusto", "authentication_type": "credential", "products": ["company"], "access_token": "7eb55bcf-6593-4040-afac-252ee1f78e20" } } } } } } } }, "put": { "summary": "Update a sandbox account", "description": "Update an existing sandbox account. Change the connection status to understand how the Finch API responds.", "operationId": "put-sandbox-connections-accounts", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_status": { "$ref": "#/components/schemas/ConnectionStatus" } } }, "examples": { "Example 1": { "value": { "connection_status": "reauth" } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "The ID of the new connection" }, "entity_id": { "type": "string", "format": "uuid", "description": "The ID of the entity whose status was updated" }, "account_id": { "type": "string", "format": "uuid", "deprecated": true, "description": "[DEPRECATED] Use `connection_id` to associate a connection with an access token" }, "authentication_type": { "$ref": "#/components/schemas/AuthenticationType" }, "company_id": { "type": "string", "format": "uuid", "description": "The Finch UUID of the company associated with the `access_token`." }, "provider_id": { "type": "string", "description": "The ID of the provider associated with the `access_token`" }, "products": { "type": "array", "items": { "type": "string" } } }, "required": [ "connection_id", "entity_id", "account_id", "authentication_type", "company_id", "provider_id", "products" ] }, "examples": { "success": { "value": { "connection_id": "a237a1c3-1a5e-44ae-a8fd-81f76fd715c2", "entity_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65", "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf", "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65", "provider_id": "gusto", "authentication_type": "credential", "products": ["company"] } } } } } } } } }, "/sandbox/company": { "put": { "summary": "Update a sandbox company's data", "operationId": "put-sandbox-company", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyWithoutId" } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyWithoutId" } } } } } } }, "/sandbox/directory": { "post": { "summary": "Add new individuals to a sandbox company", "operationId": "post-sandbox-directory", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "Array of individuals to create. Takes all combined fields from `/individual` and `/employment` endpoints. All fields are optional.", "items": { "$ref": "#/components/schemas/individual_or_employment" } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "The individuals which were created", "items": { "type": "object" } } } } } } } }, "/sandbox/individual/{individual_id}": { "parameters": [ { "schema": { "type": "string" }, "name": "individual_id", "in": "path", "required": true } ], "put": { "summary": "Update sandbox individual", "operationId": "put-sandbox-individual-individual_id", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndividualWithoutId" } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Individual" } } } } } } }, "/sandbox/employment/{individual_id}": { "parameters": [ { "schema": { "type": "string" }, "name": "individual_id", "in": "path", "required": true } ], "put": { "summary": "Update sandbox employment", "operationId": "put-sandbox-employment-individual_id", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentWithoutId" }, "examples": { "Example 1": { "value": { "start_date": "3/4/2020" } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employment" } } } } } } }, "/sandbox/payment": { "post": { "summary": "Add a new sandbox payment", "operationId": "post-sandbox-payment", "tags": ["Sandbox"], "security": [{ "bearerAuth": [] }], "requestBody": { "description": "Fields to configure the payment. Takes all fields from the `/payment` endpoint. All fields are optional.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxPaymentRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIdentifiers" }, "examples": { "Success": { "value": { "payment_id": "some-payment-id", "pay_date": "2024-01-01" } } } } } } } } }, "/sandbox/jobs": { "post": { "summary": "Enqueue a new sandbox job", "operationId": "post-sandbox-job", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of job to start. Currently the only supported type is `data_sync_all`", "enum": ["data_sync_all"] } }, "required": ["type"] } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "The id of the job that has been created." }, "job_url": { "type": "string", "description": "The url that can be used to retrieve the job status" }, "allowed_refreshes": { "type": "integer", "description": "The number of allowed refreshes per hour (per hour, fixed window)" }, "remaining_refreshes": { "type": "integer", "description": "The number of remaining refreshes available (per hour, fixed window)" } }, "required": ["job_id", "job_url", "allowed_refreshes", "remaining_refreshes"] }, "examples": { "Example 1": { "value": { "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", "job_url": "https://api.tryfinch.com/jobs/automated/453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", "allowed_refreshes": 2, "remaining_refreshes": 1 } } } } } } } } }, "/sandbox/jobs/configuration": { "get": { "summary": "Get configurations for sandbox jobs", "operationId": "get-sandbox-jobs-configuration", "tags": ["Sandbox"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxJobConfiguration" } } } } } } }, "put": { "summary": "Update configurations for sandbox jobs", "operationId": "put-sandbox-jobs-configuration", "tags": ["Sandbox"], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxJobConfiguration" } } }, "required": true }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxJobConfiguration" } } } } } } }, "/disconnect-entity": { "post": { "summary": "Disconnect Entity", "operationId": "post-disconnect-entity", "description": "Disconnect entity(s) from a connection without affecting other entities associated with the same connection.", "tags": ["Management"], "parameters": [{ "$ref": "#/components/parameters/API-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectEntityRequest" }, "examples": { "Sample": { "value": { "entity_ids": [ "3c90c3cc-0d44-4b50-8888-8dd25736052a", "5e6f7a8b-9c10-4d11-a12b-c13d14e15f16" ] } } } } } }, "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectEntityResponse" }, "examples": { "Success": { "value": { "status": "success" } } } } } }, "400": { "description": "Bad request. Either the request body is malformed (missing or invalid entity_ids) or one or more entity IDs failed validation.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DisconnectEntityErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] }, "examples": { "NotFound": { "summary": "One or more entity IDs not found", "value": { "errors": [{ "entityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "error": "NOT_FOUND" }] } }, "BadRequest": { "summary": "Malformed request (missing or invalid entity_ids)", "value": { "statusCode": 400, "status": 400, "code": 400, "name": "BadRequestError", "message": "entity_ids must be a non-empty array of UUIDs." } } } } } } } } } }, "components": { "schemas": { "CompanyWithoutId": { "type": "object", "properties": { "legal_name": { "type": "string", "description": "The legal name of the company.", "nullable": true }, "entity": { "type": "object", "description": "The entity type object.", "nullable": true, "properties": { "type": { "type": "string", "description": "The tax payer type of the company.", "enum": [ "llc", "lp", "corporation", "sole_proprietor", "non_profit", "partnership", "cooperative", null ], "nullable": true }, "subtype": { "type": "string", "description": "The tax payer subtype of the company.", "enum": ["s_corporation", "c_corporation", "b_corporation", null], "nullable": true } } }, "primary_email": { "type": "string", "description": "The email of the main administrator on the account.", "nullable": true, "format": "email" }, "primary_phone_number": { "type": "string", "description": "The phone number of the main administrator on the account. Format: E.164, with extension where applicable, e.g. `+NNNNNNNNNNN xExtension`", "nullable": true }, "departments": { "type": "array", "description": "The array of company departments.", "nullable": true, "items": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "The department name.", "nullable": true }, "parent": { "type": "object", "description": "The parent department, if present.", "nullable": true, "properties": { "name": { "type": "string", "description": "The parent department's name.", "nullable": true } } } } } }, "ein": { "type": "string", "description": "The employer identification number.", "nullable": true }, "locations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Location" } }, "accounts": { "type": "array", "description": "An array of bank account objects associated with the payroll/HRIS system.", "nullable": true, "items": { "type": "object", "properties": { "routing_number": { "type": "string", "description": "A nine-digit code that's based on the U.S. Bank location where your account was opened.", "nullable": true }, "account_name": { "type": "string", "description": "The name of the bank associated in the payroll/HRIS system.", "nullable": true }, "institution_name": { "type": "string", "description": "Name of the banking institution.", "nullable": true }, "account_type": { "type": "string", "description": "The type of bank account.", "enum": ["checking", "savings", null], "nullable": true }, "account_number": { "type": "string", "description": "10-12 digit number to specify the bank account", "nullable": true } } } } }, "required": [ "legal_name", "entity", "primary_email", "primary_phone_number", "departments", "ein", "locations", "accounts" ] }, "Company": { "title": "Company", "allOf": [ { "$ref": "#/components/schemas/CompanyWithoutId" }, { "type": "object", "properties": { "id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for the company.", "format": "uuid" } } } ], "x-tags": ["Models"] }, "IndividualWithoutId": { "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 }, "preferred_name": { "type": "string", "description": "The preferred name of the individual.", "nullable": true }, "emails": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "data": { "type": "string" }, "type": { "type": "string", "enum": ["work", "personal", null], "nullable": true } } } }, "phone_numbers": { "type": "array", "nullable": true, "items": { "type": "object", "nullable": true, "properties": { "data": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": ["work", "personal", null], "nullable": true } } } }, "gender": { "type": "string", "description": "The gender of the individual.", "enum": ["female", "male", "other", "decline_to_specify", null], "nullable": true }, "ethnicity": { "type": "string", "enum": [ "asian", "white", "black_or_african_american", "native_hawaiian_or_pacific_islander", "american_indian_or_alaska_native", "hispanic_or_latino", "two_or_more_races", "decline_to_specify", null ], "description": "The EEOC-defined ethnicity of the individual.", "nullable": true }, "marital_status": { "type": "string", "description": "The employee's marital status, used for beneficiary designation and spousal consent workflows.", "enum": ["single", "married", "divorced", "widowed", "domestic_partner", "unknown", null], "nullable": true }, "dob": { "$ref": "#/components/schemas/Date", "nullable": true }, "ssn": { "type": "string", "description": "Social Security Number of the individual. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body. [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).", "nullable": true }, "encrypted_ssn": { "type": "string", "description": "Social Security Number of the individual in **encrypted** format. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body.", "nullable": true }, "residence": { "$ref": "#/components/schemas/Location" } } }, "Individual": { "title": "Individual", "allOf": [ { "$ref": "#/components/schemas/IndividualWithoutId" }, { "type": "object", "properties": { "id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for an individual in the company.", "format": "uuid" } } } ] }, "EmploymentWithoutId": { "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", "description": "The manager object representing the manager of the individual within the org.", "nullable": true, "properties": { "id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for an individual in the company.", "format": "uuid" } } }, "department": { "type": "object", "description": "The department object.", "nullable": true, "properties": { "name": { "type": "string", "description": "The name of the department associated with the individual.", "nullable": true } } }, "employment": { "type": "object", "description": "The employment 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 } } }, "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 } } } }, "union_code": { "type": "string", "nullable": true, "description": "The code identifying the union the employee is a member of, as configured in the payroll system." }, "union_local": { "type": "string", "nullable": true, "description": "The local chapter or local number within the employee's union." }, "highly_compensated_employee": { "type": "boolean", "nullable": true, "description": "IRS flag indicating whether the employee is classified as a Highly Compensated Employee for nondiscrimination testing purposes (ADP/ACP tests). US-only." }, "key_employee": { "type": "boolean", "nullable": true, "description": "IRS flag indicating whether the employee is classified as a Key Employee for top-heavy testing purposes. US-only." }, "source_id": { "type": "string", "nullable": true, "description": "The source system's unique employment identifier for this individual" } } }, "Employment": { "title": "Employment", "allOf": [ { "$ref": "#/components/schemas/EmploymentWithoutId" }, { "type": "object", "properties": { "id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for an individual in the company.", "format": "uuid" } } } ] }, "ConnectionStatus": { "type": "string", "enum": [ "pending", "processing", "connected", "error_no_account_setup", "error_permissions", "reauth" ] }, "SandboxJobConfiguration": { "title": "SandboxJobConfiguration", "type": "object", "properties": { "type": { "enum": ["data_sync_all"] }, "completion_status": { "enum": ["complete", "reauth_error", "permissions_error", "error"] } }, "required": ["type", "completion_status"] }, "AuthenticationType": { "title": "AuthenticationType", "enum": ["credential", "api_token", "oauth", "assisted"] }, "BaseWebhookEvent": { "type": "object", "properties": { "connection_id": { "type": "string", "description": "Unique Finch ID of the connection associated with the webhook event." }, "company_id": { "type": "string", "description": "Unique Finch ID of the company for which data has been updated." }, "account_id": { "type": "string", "deprecated": true, "description": "[DEPRECATED] Unique Finch ID of the employer account used to make this connection. Use `connection_id` instead to identify the connection associated with this event." }, "entity_id": { "type": "string", "description": "Unique Finch id of the entity for which data has been updated." } }, "required": ["company_id", "account_id"] }, "WebhookEvent": { "anyOf": [ { "$ref": "#/components/schemas/AccountUpdateEvent" }, { "$ref": "#/components/schemas/JobCompletionEvent" }, { "$ref": "#/components/schemas/CompanyEvent" }, { "$ref": "#/components/schemas/DirectoryEvent" }, { "$ref": "#/components/schemas/EmploymentEvent" }, { "$ref": "#/components/schemas/IndividualEvent" }, { "$ref": "#/components/schemas/PaymentEvent" }, { "$ref": "#/components/schemas/PayStatementEvent" } ], "x-stainless-go-union": { "flattened": false }, "discriminator": { "propertyName": "event_type" } }, "AccountUpdateEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["account.updated"] }, "data": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ConnectionStatus" }, "authentication_method": { "$ref": "#/components/schemas/AuthenticationMethod" } }, "required": ["status", "authentication_method"] } } } ] }, "JobCompletionEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "job.benefit_create.completed", "job.benefit_enroll.completed", "job.benefit_register.completed", "job.benefit_unenroll.completed", "job.benefit_update.completed", "job.data_sync_all.completed", "job.w4_form_employee_sync.completed", "job.initial_data_sync_org.succeeded", "job.initial_data_sync_payroll.succeeded" ] }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The id of the job which has completed." }, "job_url": { "type": "string", "description": "The url to query the result of the job." } }, "required": ["job_id", "job_url"] } } } ] }, "CompanyEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["company.updated"] }, "data": { "type": "object", "nullable": true, "additionalProperties": true } } } ] }, "DirectoryEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["directory.created", "directory.updated", "directory.deleted"] }, "data": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "The ID of the individual related to the event." } } } } } ] }, "EmploymentEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["employment.created", "employment.updated", "employment.deleted"] }, "data": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "The ID of the individual related to the event." } } } } } ] }, "IndividualEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["individual.created", "individual.updated", "individual.deleted"] }, "data": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "The ID of the individual related to the event." } } } } } ] }, "PaymentIdentifiers": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "The ID of the payment." }, "pay_date": { "type": "string", "description": "The date of the payment." } }, "required": ["payment_id", "pay_date"] }, "PaymentEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["payment.created", "payment.updated", "payment.deleted"] }, "data": { "$ref": "#/components/schemas/PaymentIdentifiers" } } } ] }, "PayStatementEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseWebhookEvent" }, { "type": "object", "properties": { "event_type": { "type": "string", "enum": ["pay_statement.created", "pay_statement.updated", "pay_statement.deleted"] }, "data": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "The ID of the payment associated with the pay statement." }, "individual_id": { "type": "string", "description": "The ID of the individual associated with the pay statement." } } } } } ] }, "CreateAccessTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The access token for the connection" }, "token_type": { "type": "string", "description": "The RFC 8693 token type (Finch uses `bearer` tokens)" }, "connection_id": { "type": "string", "description": "The Finch UUID of the connection associated with the `access_token`" }, "customer_id": { "type": "string", "nullable": true, "description": "The ID of your customer you provided to Finch when a connect session was created for this connection" }, "customer_name": { "type": "string", "nullable": true, "description": "The name of your customer you provided to Finch when a connect session was created for this connection" }, "account_id": { "type": "string", "description": "[DEPRECATED] Use `connection_id` to identify the connection instead of this account ID", "deprecated": true }, "client_type": { "$ref": "#/components/schemas/ClientType" }, "company_id": { "type": "string", "description": "The Finch UUID of the company associated with the `access_token`." }, "connection_type": { "$ref": "#/components/schemas/ConnectionType" }, "products": { "type": "array", "items": { "type": "string" }, "description": "An array of the authorized products associated with the `access_token`" }, "provider_id": { "type": "string", "description": "The ID of the provider associated with the `access_token`" }, "entity_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "An array of entity IDs that can be accessed with this access token" } }, "required": [ "access_token", "token_type", "connection_id", "client_type", "connection_type", "products", "provider_id", "entity_ids" ] }, "AutomatedAsyncJob": { "title": "AutomatedAsyncJob", "type": "object", "properties": { "job_id": { "type": "string", "description": "The id of the job that has been created.", "format": "uuid" }, "job_url": { "type": "string", "description": "The url that can be used to retrieve the job status" }, "type": { "type": "string", "description": "The type of automated job", "enum": ["data_sync_all", "w4_form_employee_sync"] }, "status": { "type": "string", "enum": ["pending", "in_progress", "complete", "error", "reauth_error", "permissions_error"] }, "created_at": { "type": "string", "format": "date-time", "description": "The datetime when the job was created. for scheduled jobs, this will be the initial connection time. For ad-hoc jobs, this will be the time the creation request was received." }, "scheduled_at": { "type": "string", "format": "date-time", "description": "The datetime a job is scheduled to be run. For scheduled jobs, this datetime can be in the future if the job has not yet been enqueued. For ad-hoc jobs, this field will be null.", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "description": "The datetime a job entered into the job queue.", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "description": "The datetime the job completed.", "nullable": true }, "params": { "type": "object", "description": "The input parameters for the job.", "nullable": true, "properties": { "individual_id": { "type": "string", "description": "The ID of the individual that the job was completed for." } } } }, "required": [ "job_id", "job_url", "type", "status", "created_at", "scheduled_at", "started_at", "completed_at", "params" ] }, "ManualAsyncJob": { "title": "ManualAsyncJob", "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["pending", "in_progress", "error", "complete"] }, "body": { "type": "array", "description": "Specific information about the job, such as individual statuses for batch jobs.", "nullable": true, "items": { "nullable": true } } }, "required": ["job_id", "status", "body"] }, "GetCompanyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for the company." }, "legal_name": { "type": "string", "nullable": true, "description": "The legal name of the company." }, "entity": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "nullable": true, "enum": [ "llc", "lp", "corporation", "sole_proprietor", "non_profit", "partnership", "cooperative", null ], "description": "The tax payer type of the company." }, "subtype": { "type": "string", "nullable": true, "enum": ["s_corporation", "c_corporation", "b_corporation", null], "description": "The tax payer subtype of the company." } }, "required": ["type", "subtype"], "description": "The entity type object." }, "primary_email": { "type": "string", "nullable": true, "format": "email", "description": "The email of the main administrator on the account." }, "primary_phone_number": { "type": "string", "nullable": true, "description": "The phone number of the main administrator on the account. Format: E.164, with extension where applicable, e.g. `+NNNNNNNNNNN xExtension`" }, "departments": { "type": "array", "nullable": true, "items": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "The department name." }, "parent": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "The parent department's name." } }, "required": ["name"], "description": "The parent department, if present." } }, "required": ["name", "parent"] }, "description": "The array of company departments." }, "ein": { "type": "string", "nullable": true, "description": "The employer identification number." }, "locations": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Location" } }, "accounts": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "routing_number": { "type": "string", "nullable": true, "description": "A nine-digit code that's based on the U.S. Bank location where your account was opened." }, "account_name": { "type": "string", "nullable": true, "description": "The name of the bank associated in the payroll/HRIS system." }, "institution_name": { "type": "string", "nullable": true, "description": "Name of the banking institution." }, "account_type": { "type": "string", "nullable": true, "enum": ["checking", "savings", null], "description": "The type of bank account." }, "account_number": { "type": "string", "nullable": true, "description": "10-12 digit number to specify the bank account" } }, "required": [ "routing_number", "account_name", "institution_name", "account_type", "account_number" ] }, "description": "An array of bank account objects associated with the payroll/HRIS system." } }, "required": [ "id", "legal_name", "entity", "primary_email", "primary_phone_number", "departments", "ein", "locations", "accounts" ], "title": "GetCompany" }, "GetDirectoryResponse": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Paging" }, "individuals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." }, "first_name": { "type": "string", "nullable": true, "description": "The legal first name of the individual." }, "middle_name": { "type": "string", "nullable": true, "description": "The legal middle name of the individual." }, "last_name": { "type": "string", "nullable": true, "description": "The legal last name of the individual." }, "manager": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." } }, "required": ["id"], "description": "The manager object." }, "department": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "The name of the department." } }, "description": "The department object." }, "is_active": { "type": "boolean", "nullable": true, "description": "`true` if the individual is an active employee or contractor at the company." } }, "required": [ "id", "first_name", "middle_name", "last_name", "manager", "department", "is_active" ] }, "description": "The array of employees." } }, "required": ["paging", "individuals"] }, "GetIndividualsResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "type": "object", "properties": { "individual_id": { "type": "string" }, "code": { "type": "integer" }, "body": { "anyOf": [ { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true, "description": "The legal first name of the individual." }, "middle_name": { "type": "string", "nullable": true, "description": "The legal middle name of the individual." }, "last_name": { "type": "string", "nullable": true, "description": "The legal last name of the individual." }, "preferred_name": { "type": "string", "nullable": true, "description": "The preferred name of the individual." }, "emails": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "data": { "type": "string" }, "type": { "type": "string", "nullable": true, "enum": ["work", "personal", null] } }, "required": ["data", "type"] } }, "phone_numbers": { "type": "array", "nullable": true, "items": { "type": "object", "nullable": true, "properties": { "data": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": ["work", "personal", null] } }, "required": ["data", "type"] } }, "gender": { "type": "string", "nullable": true, "enum": ["female", "male", "other", "decline_to_specify", null], "description": "The gender of the individual." }, "ethnicity": { "type": "string", "nullable": true, "enum": [ "asian", "white", "black_or_african_american", "native_hawaiian_or_pacific_islander", "american_indian_or_alaska_native", "hispanic_or_latino", "two_or_more_races", "decline_to_specify", null ], "description": "The EEOC-defined ethnicity of the individual." }, "marital_status": { "type": "string", "nullable": true, "enum": [ "single", "married", "divorced", "widowed", "domestic_partner", "unknown", null ], "description": "The employee's marital status, used for beneficiary designation and spousal consent workflows." }, "dob": { "anyOf": [{ "type": "null" }, { "$ref": "#/components/schemas/Date" }] }, "ssn": { "type": "string", "nullable": true, "description": "Social Security Number of the individual. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body. [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field)." }, "encrypted_ssn": { "type": "string", "nullable": true, "description": "Social Security Number of the individual in **encrypted** format. This field is only available with the `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the body." }, "residence": { "$ref": "#/components/schemas/Location" }, "id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." } }, "required": [ "first_name", "middle_name", "last_name", "preferred_name", "phone_numbers", "gender", "ethnicity", "marital_status", "dob", "residence", "id" ], "title": "IndividualResponseBody" }, { "$ref": "#/components/schemas/BatchError" } ] } }, "required": ["individual_id", "code", "body"] } } }, "required": ["responses"] }, "GetEmploymentResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "type": "object", "properties": { "individual_id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." }, "code": { "type": "integer" }, "body": { "anyOf": [ { "type": "object", "properties": { "first_name": { "type": "string", "nullable": true, "description": "The legal first name of the individual." }, "middle_name": { "type": "string", "nullable": true, "description": "The legal middle name of the individual." }, "last_name": { "type": "string", "nullable": true, "description": "The legal last name of the individual." }, "title": { "type": "string", "nullable": true, "description": "The current title of the individual." }, "manager": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." } }, "required": ["id"], "description": "The manager object representing the manager of the individual within the org." }, "department": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true, "description": "The name of the department associated with the individual." } }, "required": ["name"], "description": "The department object." }, "employment": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "nullable": true, "enum": ["employee", "contractor", null], "description": "The main employment type of the individual." }, "subtype": { "type": "string", "nullable": true, "enum": [ "full_time", "intern", "part_time", "temp", "seasonal", "individual_contractor", null ], "description": "The secondary employment type of the individual. Options: `full_time`, `part_time`, `intern`, `temp`, `seasonal` and `individual_contractor`." } }, "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", "nullable": true, "description": "`true` if the individual an an active employee or contractor at the company." }, "employment_status": { "type": "string", "nullable": true, "enum": [ "active", "deceased", "leave", "onboarding", "prehire", "retired", "terminated", null ], "description": "The detailed employment status of the individual." }, "flsa_status": { "type": "string", "nullable": true, "enum": ["exempt", "non_exempt", "unknown", null], "description": "The FLSA status of the individual. Available options: `exempt`, `non_exempt`, `unknown`." }, "union_code": { "type": "string", "nullable": true, "description": "The code identifying the union the employee is a member of, as configured in the payroll system." }, "union_local": { "type": "string", "nullable": true, "description": "The local chapter or local number within the employee's union." }, "highly_compensated_employee": { "type": "boolean", "nullable": true, "description": "IRS flag indicating whether the employee is classified as a Highly Compensated Employee for nondiscrimination testing purposes (ADP/ACP tests). US-only." }, "key_employee": { "type": "boolean", "nullable": true, "description": "IRS flag indicating whether the employee is classified as a Key Employee for top-heavy testing purposes. US-only." }, "class_code": { "type": "string", "nullable": true, "description": "Worker's compensation classification code for this employee" }, "location": { "$ref": "#/components/schemas/Location" }, "income": { "$ref": "#/components/schemas/Income" }, "income_history": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Income" }, "description": "The array of income history." }, "custom_fields": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "value": { "type": ["string", "array", "object", "number", "boolean", "null"], "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." }, "source_id": { "type": "string", "nullable": true, "description": "The source system's unique employment identifier for this individual" }, "id": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." }, "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", "union_code", "union_local", "highly_compensated_employee", "key_employee", "class_code", "location", "id" ], "title": "EmploymentDataResponseBody" }, { "$ref": "#/components/schemas/BatchError" } ] } }, "required": ["individual_id", "code", "body"] } } }, "required": ["responses"] }, "GetPaymentsResponse": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique id for the payment." }, "pay_period": { "type": "object", "nullable": true, "properties": { "start_date": { "$ref": "#/components/schemas/Date" }, "end_date": { "$ref": "#/components/schemas/Date" } }, "required": ["start_date", "end_date"], "description": "The pay period object." }, "pay_date": { "$ref": "#/components/schemas/Date" }, "debit_date": { "$ref": "#/components/schemas/Date" }, "company_debit": { "$ref": "#/components/schemas/Money" }, "gross_pay": { "$ref": "#/components/schemas/Money" }, "net_pay": { "$ref": "#/components/schemas/Money" }, "employer_taxes": { "$ref": "#/components/schemas/Money" }, "employee_taxes": { "$ref": "#/components/schemas/Money" }, "individual_ids": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "description": "Array of every individual on this payment." }, "pay_group_ids": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" }, "description": "Array of the Finch id (uuidv4) of every pay group associated with this payment." }, "pay_frequencies": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PayFrequency" }, "description": "List of pay frequencies associated with this payment." } }, "required": [ "id", "pay_period", "pay_date", "debit_date", "company_debit", "gross_pay", "net_pay", "employer_taxes", "employee_taxes", "individual_ids", "pay_group_ids", "pay_frequencies" ] } }, "PayStatement": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "A stable Finch `id` (UUID v4) for an individual in the company" }, "type": { "type": "string", "nullable": true, "enum": ["off_cycle_payroll", "one_time_payment", "regular_payroll", null], "description": "The type of the payment associated with the pay statement." }, "payment_method": { "type": "string", "nullable": true, "enum": ["check", "direct_deposit", "other", null], "description": "The payment method." }, "total_hours": { "type": "number", "nullable": true, "description": "The number of hours worked for this pay period" }, "gross_pay": { "$ref": "#/components/schemas/Money" }, "net_pay": { "$ref": "#/components/schemas/Money" }, "earnings": { "type": "array", "nullable": true, "items": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "nullable": true, "enum": [ "salary", "wage", "reimbursement", "overtime", "severance", "double_overtime", "pto", "sick", "bonus", "commission", "tips", "1099", "other", null ], "description": "The type of earning." }, "name": { "type": "string", "nullable": true, "description": "The exact name of the earning from the pay statement." }, "amount": { "type": "integer", "nullable": true, "description": "The earnings amount in cents." }, "currency": { "type": "string", "nullable": true, "description": "The earnings currency code." }, "hours": { "type": "number", "nullable": true, "description": "The number of hours associated with this earning. (For salaried employees, this could be hours per pay period, `0` or `null`, depending on the provider)." }, "attributes": { "type": "object", "nullable": true, "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": ["metadata"] } }, "required": ["type", "name", "amount", "currency", "hours"] }, "description": "The array of earnings objects associated with this pay statement" }, "taxes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "enum": ["state", "federal", "local", "fica", null], "description": "The type of taxes." }, "name": { "type": "string", "nullable": true, "description": "The exact name of tax from the pay statement." }, "employer": { "type": "boolean", "nullable": true, "description": "`true` if the amount is paid by the employers." }, "amount": { "type": "integer", "nullable": true, "description": "The tax amount in cents." }, "currency": { "type": "string", "nullable": true, "description": "The currency code." }, "attributes": { "type": "object", "nullable": true, "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": ["metadata"] } }, "required": ["type", "name", "employer", "currency"] }, "description": "The array of taxes objects associated with this pay statement." }, "employee_deductions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The deduction name from the pay statement." }, "amount": { "type": "integer", "nullable": true, "description": "The deduction amount in cents." }, "currency": { "type": "string", "nullable": true, "description": "The deduction currency." }, "pre_tax": { "type": "boolean", "nullable": true, "description": "Boolean indicating if the deduction is pre-tax." }, "type": { "$ref": "#/components/schemas/BenefitType" }, "attributes": { "type": "object", "nullable": true, "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": ["metadata"] } }, "required": ["name", "amount", "currency", "pre_tax", "type"] }, "description": "The array of deductions objects associated with this pay statement." }, "employer_contributions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The contribution name from the pay statement." }, "amount": { "type": "integer", "nullable": true, "description": "The contribution amount in cents." }, "currency": { "type": "string", "nullable": true, "description": "The contribution currency." }, "type": { "$ref": "#/components/schemas/BenefitType" }, "attributes": { "type": "object", "nullable": true, "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": ["metadata"] } }, "required": ["name", "currency", "type"] } } }, "required": [ "individual_id", "type", "payment_method", "total_hours", "gross_pay", "net_pay", "earnings", "taxes", "employee_deductions", "employer_contributions" ], "title": "Pay Statement" }, "GetPayStatementsResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string" }, "code": { "type": "integer" }, "body": { "anyOf": [ { "type": "object", "properties": { "paging": { "type": "object", "properties": { "count": { "type": "integer", "description": "The total number of elements for the entire query (not just the given page)" }, "offset": { "type": "integer", "description": "The current start index of the returned list of elements" } }, "required": ["offset"], "title": "Paging", "x-tags": ["Models"] }, "pay_statements": { "type": "array", "items": { "$ref": "#/components/schemas/PayStatement" } } }, "required": ["paging", "pay_statements"], "title": "PayStatementData" }, { "$ref": "#/components/schemas/BatchError" }, { "type": "object", "properties": { "code": { "type": "number", "enum": [202] }, "finch_code": { "type": "string", "enum": ["data_sync_in_progress"] }, "message": { "type": "string", "enum": [ "The pay statements for this payment are being fetched. Please check back later." ] }, "name": { "type": "string", "enum": ["accepted"] } }, "required": ["code", "finch_code", "message", "name"], "title": "PayStatementDataSyncInProgress" } ] } }, "required": ["payment_id", "code", "body"] } } }, "required": ["responses"] }, "GetPayStatementItemsResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the pay statement item." }, "category": { "type": "string", "enum": ["earnings", "taxes", "employee_deductions", "employer_contributions"], "description": "The category of the pay statement item." }, "attributes": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "description": "The type of the pay statement item." }, "pre_tax": { "type": "boolean", "nullable": true, "description": "`true` if the pay statement item is pre-tax. This field is only available for employee deductions." }, "employer": { "type": "boolean", "nullable": true, "description": "`true` if the amount is paid by the employers. This field is only available for taxes." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "The metadata of the pay statement item derived by the rules engine if available. Each attribute will be a key-value pair defined by a rule." } }, "required": ["metadata"], "description": "The attributes of the pay statement item." } }, "required": ["name", "category", "attributes"] } } }, "required": ["responses"] }, "CreateRuleRequest": { "type": "object", "properties": { "effective_start_date": { "description": "Specifies when the rule should begin applying based on the date.", "$ref": "#/components/schemas/Date" }, "effective_end_date": { "$ref": "#/components/schemas/Date", "description": "Specifies when the rules should stop applying rules based on the date." }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The field to be checked in the rule." }, "operator": { "type": "string", "description": "The operator to be used in the rule.", "enum": ["equals"] }, "value": { "type": "string", "description": "The value of the field to be checked in the rule." } } } }, "attributes": { "type": "object", "description": "Specifies the fields to be applied when the condition is met.", "properties": { "metadata": { "type": "object", "description": "The metadata to be attached in the entity. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).", "additionalProperties": true } } }, "entity_type": { "type": "string", "description": "The entity type to which the rule is applied.", "enum": ["pay_statement_item"] } } }, "UpdateRuleRequest": { "type": "object", "properties": { "optionalProperty": { "effective_start_date": { "description": "Specifies when the rule should begin applying based on the date.", "$ref": "#/components/schemas/Date" }, "effective_end_date": { "$ref": "#/components/schemas/Date", "description": "Specifies when the rules should stop applying rules based on the date." }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The field to be checked in the rule." }, "operator": { "type": "string", "description": "The operator to be used in the rule.", "enum": ["equals"] }, "value": { "type": "string", "description": "The value of the field to be checked in the rule." } } } }, "attributes": { "type": "object", "description": "Specifies the fields to be applied when the condition is met.", "properties": { "metadata": { "type": "object", "description": "The metadata to be attached in the entity. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).", "additionalProperties": true } } }, "entity_type": { "type": "string", "description": "The entity type to which the rule is applied.", "enum": ["pay_statement_item"] } } } }, "CreateRuleResponse": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Finch id (uuidv4) for the rule." }, "priority": { "type": "integer", "description": "The priority of the rule." }, "created_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was last updated." } } }, { "$ref": "#/components/schemas/CreateRuleRequest" } ] }, "UpdateRuleResponse": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Finch id (uuidv4) for the rule.", "format": "uuid" }, "priority": { "type": "integer", "description": "The priority of the rule." }, "created_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was last updated." } } }, { "$ref": "#/components/schemas/CreateRuleRequest" } ] }, "DeleteRuleResponse": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Finch id (uuidv4) for the rule.", "format": "uuid" }, "priority": { "type": "integer", "description": "The priority of the rule." }, "created_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was last updated." }, "deleted_at": { "type": "string", "format": "date-time", "description": "The datetime when the rule was deleted." } } }, { "$ref": "#/components/schemas/CreateRuleRequest" } ] }, "GetRulesResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "$ref": "#/components/schemas/CreateRuleResponse" } } }, "required": ["responses"] }, "ConnectProducts": { "type": "string", "enum": [ "benefits", "company", "deduction", "directory", "documents", "employment", "individual", "payment", "pay_statement", "recordkeeping", "ssn" ] }, "GetAllPayGroupsResponse": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Finch id (uuidv4) for the pay group" }, "name": { "type": "string", "description": "Name of the pay group" }, "pay_frequencies": { "type": "array", "items": { "$ref": "#/components/schemas/PayFrequency" }, "description": "List of pay frequencies associated with this pay group" } }, "required": ["id", "name", "pay_frequencies"] } }, "GetPayGroupResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Finch id (uuidv4) for the pay group" }, "name": { "type": "string", "description": "Name of the pay group" }, "pay_frequencies": { "type": "array", "items": { "$ref": "#/components/schemas/PayFrequency" }, "description": "List of pay frequencies associated with this pay group" }, "individual_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "Finch id (uuidv4) for an individual assigned to this pay group" } } }, "required": ["id", "name", "pay_frequencies", "individual_ids"] }, "PayFrequency": { "type": "string", "enum": [ "annually", "bi_weekly", "daily", "monthly", "other", "quarterly", "semi_annually", "semi_monthly", "weekly" ] }, "GetProvidersResponse": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "GetIntrospectResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The Finch UUID of the token being introspected" }, "connection_id": { "type": "string", "description": "The Finch UUID of the connection associated with the `access_token`" }, "connection_status": { "$ref": "#/components/schemas/ConnectionStatusDetail" }, "client_id": { "type": "string", "description": "The client ID of the application associated with the `access_token`" }, "client_type": { "$ref": "#/components/schemas/ClientType" }, "connection_type": { "$ref": "#/components/schemas/ConnectionType" }, "company_id": { "type": "string", "description": "The Finch UUID of the company associated with the `access_token`." }, "account_id": { "type": "string", "description": "[DEPRECATED] Use `connection_id` to associate tokens with a Finch connection instead of this account ID", "deprecated": true }, "customer_id": { "type": "string", "nullable": true, "description": "The ID of your customer you provided to Finch when a connect session was created for this connection" }, "customer_name": { "type": "string", "nullable": true, "description": "The name of your customer you provided to Finch when a connect session was created for this connection" }, "customer_email": { "type": "string", "nullable": true, "description": "The email of your customer you provided to Finch when a connect session was created for this connection" }, "authentication_methods": { "type": "array", "items": { "$ref": "#/components/schemas/AuthenticationMethodDetail" } }, "products": { "type": "array", "items": { "type": "string" }, "description": "An array of the authorized products associated with the `access_token`." }, "username": { "type": "string", "nullable": true, "description": "The account username used for login associated with the `access_token`." }, "provider_id": { "type": "string", "description": "The ID of the provider associated with the `access_token`." }, "payroll_provider_id": { "type": "string", "description": "[DEPRECATED] Use `provider_id` to identify the provider instead of this payroll provider ID.", "deprecated": true }, "manual": { "type": "boolean", "description": "Whether the connection associated with the `access_token` uses the Assisted Connect Flow. (`true` if using Assisted Connect, `false` if connection is automated)" }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/MultiAccountEntity" }, "description": "Array of detailed entity information for each connected account in multi-account mode" } }, "required": [ "id", "connection_id", "connection_status", "client_id", "client_type", "connection_type", "products", "provider_id" ] }, "DisconnectResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "If the request is successful, Finch will return \"success\" (HTTP 200 status)." } }, "required": ["status"] }, "GetCompanyBenefitsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyBenefit" }, "description": "Array of company benefits." }, "ListDocumentsResponse": { "type": "object", "properties": { "paging": { "$ref": "#/components/schemas/Paging" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentItem" } } }, "required": ["paging", "documents"] }, "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" }, "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" }, "CreateCompanyBenefitsResponse": { "type": "object", "properties": { "benefit_id": { "type": "string", "format": "uuid", "description": "The id of the benefit." }, "job_id": { "type": "string", "format": "uuid" } }, "required": ["benefit_id", "job_id"] }, "RegisterCompanyBenefitResponse": { "type": "object", "properties": { "benefit_id": { "type": "string", "format": "uuid", "description": "The id of the benefit." }, "job_id": { "type": "string", "format": "uuid" } }, "required": ["benefit_id", "job_id"] }, "GetCompanyBenefitsMetadataResponse": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/BenefitFeature" } }, "UpdateCompanyBenefitResponse": { "type": "object", "properties": { "benefit_id": { "type": "string", "format": "uuid", "description": "The id of the benefit." }, "job_id": { "type": "string", "format": "uuid" } }, "required": ["benefit_id", "job_id"] }, "GetCompanyBenefitEnrolledIndividualsResponse": { "type": "object", "properties": { "benefit_id": { "type": "string", "format": "uuid", "description": "The id of the benefit." }, "individual_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "A stable Finch `id` (UUID v4) for an individual in the company." } } }, "required": ["benefit_id", "individual_ids"] }, "EnrollIndividualBenefitResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" } }, "required": ["job_id"] }, "UnenrollIndividualBenefitResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" } }, "required": ["job_id"] }, "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"] }, "Money": { "type": "object", "nullable": true, "properties": { "amount": { "type": "integer", "nullable": true, "description": "Amount for money object (in cents)" }, "currency": { "type": "string" } }, "required": ["amount", "currency"], "title": "Money", "x-tags": ["Models"] }, "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"] }, "Date": { "type": "string", "title": "Date", "nullable": true }, "BenefitType": { "type": "string", "nullable": true, "enum": [ "457", "401k", "401k_roth", "401k_loan", "403b", "403b_roth", "457_roth", "commuter", "custom_post_tax", "custom_pre_tax", "fsa_dependent_care", "fsa_medical", "hsa_post", "hsa_pre", "s125_dental", "s125_medical", "s125_vision", "simple", "simple_ira", null ], "description": "Type of benefit.", "title": "BenefitType", "x-tags": ["Models"], "x-stainless-renameMap": { "_401k_loan": "401k_loan", "_401k_roth": "401k_roth", "_401k": "401k", "_403b_roth": "403b_roth", "_403b": "403b", "_457_roth": "457_roth", "_457": "457" } }, "BenefitDescription": { "type": "string", "title": "BenefitDescription", "description": "Name of the benefit as it appears in the provider and pay statements. Recommend limiting this to <30 characters due to limitations in specific providers (e.g. Justworks).", "x-tags": ["Models"] }, "BenefitFrequency": { "type": "string", "nullable": true, "enum": ["every_paycheck", "monthly", "one_time", null], "description": "The frequency of the benefit deduction/contribution.", "title": "BenefitFrequency", "x-tags": ["Models"] }, "BenefitCompanyMatchContribution": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "enum": ["match"] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "match": { "type": "integer", "minimum": 1, "maximum": 10000 }, "threshold": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": ["match", "threshold"] }, "minItems": 1, "maxItems": 3 } }, "required": ["type", "tiers"], "description": "The company match for this benefit.", "title": "BenefitCompanyMatchContribution", "x-tags": ["Models"] }, "BenefitContribution": { "oneOf": [ { "title": "BenefitContributionFixed", "type": "object", "properties": { "type": { "type": "string", "enum": ["fixed"], "description": "Fixed contribution type." }, "amount": { "type": "integer", "description": "Contribution amount in cents." } }, "required": ["type", "amount"] }, { "title": "BenefitContributionPercent", "type": "object", "properties": { "type": { "type": "string", "enum": ["percent"], "description": "Percentage contribution type." }, "amount": { "type": "integer", "description": "Contribution amount in basis points (1/100th of a percent)." } }, "required": ["type", "amount"] }, { "title": "BenefitContributionTiered", "type": "object", "properties": { "type": { "type": "string", "enum": ["tiered"], "description": "Tiered contribution type (only valid for company_contribution)." }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "match": { "type": "integer", "minimum": 1, "maximum": 10000 }, "threshold": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": ["match", "threshold"] }, "minItems": 1, "description": "Array of tier objects defining employer match tiers based on employee contribution thresholds." } }, "required": ["type", "tiers"] }, { "nullable": true } ], "title": "BenefitContribution", "x-tags": ["Models"] }, "BenefitFeature": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "frequencies": { "type": "array", "items": { "$ref": "#/components/schemas/BenefitFrequency" }, "description": "The list of frequencies supported by the provider for this benefit" }, "employee_deduction": { "type": "array", "nullable": true, "items": { "type": "string", "enum": ["fixed", "percent", null] }, "description": "Supported deduction types. An empty array indicates deductions are not supported." }, "company_contribution": { "type": "array", "nullable": true, "items": { "type": "string", "enum": ["fixed", "percent", "tiered", null] }, "description": "Supported contribution types. An empty array indicates contributions are not supported." }, "annual_maximum": { "type": "boolean", "nullable": true, "description": "Whether the provider supports an annual maximum for this benefit." }, "catch_up": { "type": "boolean", "nullable": true, "description": "Whether the provider supports catch up for this benefit. This field will only be true for retirement benefits." }, "hsa_contribution_limit": { "type": "array", "nullable": true, "items": { "type": "string", "enum": ["family", "individual", null] }, "description": "Whether the provider supports HSA contribution limits. Empty if this feature is not supported for the benefit. This array only has values for HSA benefits." } }, "required": [ "description", "frequencies", "employee_deduction", "company_contribution", "annual_maximum" ], "title": "BenefitFeature" }, "ClientType": { "type": "string", "enum": ["development", "production", "sandbox"], "description": "The type of application associated with a token.", "title": "ClientType" }, "ConnectionType": { "type": "string", "enum": ["finch", "provider"], "description": "The type of the connection associated with the token.\n- `provider` - connection to an external provider\n- `finch` - finch-generated data.", "title": "ConnectionType" }, "CompanyBenefit": { "type": "object", "properties": { "benefit_id": { "type": "string", "format": "uuid", "description": "The id of the benefit." }, "type": { "$ref": "#/components/schemas/BenefitType" }, "description": { "type": "string", "nullable": true }, "frequency": { "$ref": "#/components/schemas/BenefitFrequency" }, "company_contribution": { "$ref": "#/components/schemas/BenefitCompanyMatchContribution" } }, "required": ["benefit_id", "type", "description", "frequency"], "title": "CompanyBenefit" }, "IndividualBenefits": { "type": "array", "items": { "type": "object", "properties": { "individual_id": { "type": "string" }, "code": { "type": "integer" }, "body": { "anyOf": [ { "type": "object", "properties": { "employee_deduction": { "$ref": "#/components/schemas/EmployeeDeductionContribution" }, "company_contribution": { "$ref": "#/components/schemas/CompanyContribution" }, "annual_maximum": { "type": "integer", "nullable": true, "description": "If the benefit supports annual maximum, the amount in cents for this individual." }, "catch_up": { "type": "boolean", "nullable": true, "description": "If the benefit supports catch up (401k, 403b, etc.), whether catch up is enabled for this individual." }, "hsa_contribution_limit": { "type": "string", "nullable": true, "enum": ["individual", "family", null], "description": "Type for HSA contribution limit if the benefit is a HSA." } }, "required": ["employee_deduction", "company_contribution", "annual_maximum", "catch_up"], "title": "IndividualBenefit" }, { "$ref": "#/components/schemas/BatchError" } ] } }, "required": ["individual_id", "code", "body"] }, "title": "IndividualBenefits" }, "BenefitFeaturesAndOperations": { "type": "object", "nullable": true, "properties": { "supported_features": { "$ref": "#/components/schemas/BenefitFeature" }, "supported_operations": { "$ref": "#/components/schemas/SupportPerBenefitType" } } }, "BenefitsSupport": { "type": "object", "nullable": true, "description": "Each benefit type and their supported features. If the benefit type is not supported, the property will be null", "properties": { "s125_medical": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "s125_dental": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "s125_vision": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "hsa_pre": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "hsa_post": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "fsa_medical": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "fsa_dependent_care": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "simple_ira": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "simple": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "commuter": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "custom_post_tax": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" }, "custom_pre_tax": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" } }, "additionalProperties": { "$ref": "#/components/schemas/BenefitFeaturesAndOperations" } }, "AuthenticationMethod": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of authentication method.", "enum": ["assisted", "credential", "api_token", "api_credential", "oauth"] }, "benefits_support": { "$ref": "#/components/schemas/BenefitsSupport" }, "supported_fields": { "$ref": "#/components/schemas/SupportedFields" } } }, "Metadata": { "type": "object", "description": "The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).", "additionalProperties": { "type": "object", "nullable": true } }, "SupportedFields": { "type": "object", "description": "The supported data fields returned by our HR and payroll endpoints", "properties": { "company": { "$ref": "#/components/schemas/SupportedCompanyFields" }, "directory": { "$ref": "#/components/schemas/SupportedDirectoryFields" }, "individual": { "$ref": "#/components/schemas/SupportedIndividualFields" }, "employment": { "$ref": "#/components/schemas/SupportedEmploymentFields" }, "payment": { "$ref": "#/components/schemas/SupportedPaymentFields" }, "pay_statement": { "$ref": "#/components/schemas/SupportedPayStatementFields" }, "pay_group": { "$ref": "#/components/schemas/SupportedPayGroupFields" } }, "nullable": true }, "SupportedCompanyFields": { "type": "object", "properties": { "id": { "type": "boolean" }, "legal_name": { "type": "boolean" }, "entity": { "type": "object", "properties": { "type": { "type": "boolean" }, "subtype": { "type": "boolean" } } }, "primary_email": { "type": "boolean" }, "primary_phone_number": { "type": "boolean" }, "ein": { "type": "boolean" }, "accounts": { "type": "object", "properties": { "routing_number": { "type": "boolean" }, "account_name": { "type": "boolean" }, "institution_name": { "type": "boolean" }, "account_type": { "type": "boolean" }, "account_number": { "type": "boolean" } } }, "departments": { "type": "object", "properties": { "name": { "type": "boolean" }, "parent": { "type": "object", "properties": { "name": { "type": "boolean" } } } } }, "locations": { "type": "object", "properties": { "line1": { "type": "boolean" }, "line2": { "type": "boolean" }, "city": { "type": "boolean" }, "state": { "type": "boolean" }, "postal_code": { "type": "boolean" }, "country": { "type": "boolean" } } } } }, "SupportedDirectoryFields": { "type": "object", "properties": { "paging": { "type": "object", "properties": { "count": { "type": "boolean" }, "offset": { "type": "boolean" } } }, "individuals": { "type": "object", "properties": { "id": { "type": "boolean" }, "first_name": { "type": "boolean" }, "middle_name": { "type": "boolean" }, "last_name": { "type": "boolean" }, "is_active": { "type": "boolean" }, "department": { "type": "boolean" }, "manager": { "type": "object", "properties": { "id": { "type": "boolean" } } } } } } }, "SupportedIndividualFields": { "type": "object", "properties": { "id": { "type": "boolean" }, "first_name": { "type": "boolean" }, "middle_name": { "type": "boolean" }, "last_name": { "type": "boolean" }, "preferred_name": { "type": "boolean" }, "dob": { "type": "boolean" }, "gender": { "type": "boolean" }, "ethnicity": { "type": "boolean" }, "ssn": { "type": "boolean" }, "encrypted_ssn": { "type": "boolean" }, "emails": { "type": "object", "properties": { "data": { "type": "boolean" }, "type": { "type": "boolean" } } }, "phone_numbers": { "type": "object", "properties": { "data": { "type": "boolean" }, "type": { "type": "boolean" } } }, "residence": { "type": "object", "properties": { "city": { "type": "boolean" }, "country": { "type": "boolean" }, "line1": { "type": "boolean" }, "line2": { "type": "boolean" }, "postal_code": { "type": "boolean" }, "state": { "type": "boolean" } } } } }, "SupportedEmploymentFields": { "type": "object", "properties": { "id": { "type": "boolean" }, "first_name": { "type": "boolean" }, "middle_name": { "type": "boolean" }, "last_name": { "type": "boolean" }, "title": { "type": "boolean" }, "start_date": { "type": "boolean" }, "end_date": { "type": "boolean" }, "is_active": { "type": "boolean" }, "employment_status": { "type": "boolean" }, "income_history": { "type": "boolean" }, "class_code": { "type": "boolean" }, "custom_fields": { "type": "boolean" }, "department": { "type": "object", "properties": { "name": { "type": "boolean" } } }, "employment": { "type": "object", "properties": { "type": { "type": "boolean" }, "subtype": { "type": "boolean" } } }, "income": { "type": "object", "properties": { "amount": { "type": "boolean" }, "currency": { "type": "boolean" }, "unit": { "type": "boolean" } } }, "location": { "type": "object", "properties": { "line1": { "type": "boolean" }, "line2": { "type": "boolean" }, "city": { "type": "boolean" }, "state": { "type": "boolean" }, "postal_code": { "type": "boolean" }, "country": { "type": "boolean" } } }, "manager": { "type": "object", "properties": { "id": { "type": "boolean" } } } } }, "SupportedPaymentFields": { "type": "object", "properties": { "id": { "type": "boolean" }, "pay_date": { "type": "boolean" }, "debit_date": { "type": "boolean" }, "company_debit": { "type": "boolean" }, "gross_pay": { "type": "boolean" }, "net_pay": { "type": "boolean" }, "employer_taxes": { "type": "boolean" }, "employee_taxes": { "type": "boolean" }, "individual_ids": { "type": "boolean" }, "pay_period": { "type": "object", "properties": { "start_date": { "type": "boolean" }, "end_date": { "type": "boolean" } } }, "pay_group_ids": { "type": "boolean" }, "pay_frequencies": { "type": "boolean" } } }, "SupportedPayStatementFields": { "type": "object", "properties": { "paging": { "type": "object", "properties": { "count": { "type": "boolean" }, "offset": { "type": "boolean" } }, "required": ["count", "offset"] }, "pay_statements": { "type": "object", "properties": { "individual_id": { "type": "boolean" }, "type": { "type": "boolean" }, "payment_method": { "type": "boolean" }, "total_hours": { "type": "boolean" }, "gross_pay": { "type": "boolean" }, "net_pay": { "type": "boolean" }, "earnings": { "type": "object", "properties": { "type": { "type": "boolean" }, "name": { "type": "boolean" }, "amount": { "type": "boolean" }, "currency": { "type": "boolean" } } }, "employee_deductions": { "type": "object", "properties": { "name": { "type": "boolean" }, "amount": { "type": "boolean" }, "type": { "type": "boolean" }, "pre_tax": { "type": "boolean" }, "currency": { "type": "boolean" } } }, "employer_contributions": { "type": "object", "properties": { "name": { "type": "boolean" }, "amount": { "type": "boolean" }, "currency": { "type": "boolean" } } }, "taxes": { "type": "object", "properties": { "type": { "type": "boolean" }, "name": { "type": "boolean" }, "employer": { "type": "boolean" }, "amount": { "type": "boolean" }, "currency": { "type": "boolean" } } } } } } }, "SupportedPayGroupFields": { "type": "object", "properties": { "id": { "type": "boolean" }, "name": { "type": "boolean" }, "pay_frequencies": { "type": "boolean" }, "individual_ids": { "type": "boolean" } } }, "OperationSupport": { "type": "string", "enum": ["supported", "not_supported_by_finch", "not_supported_by_provider", "client_access_only"], "description": "- `supported`: This operation is supported by both the provider and Finch\n- `not_supported_by_finch`: This operation is not supported by Finch but supported by the provider\n- `not_supported_by_provider`: This operation is not supported by the provider, so Finch cannot support\n- `client_access_only`: This behavior is supported by the provider, but only available to the client and not to Finch" }, "OperationSupportMatrix": { "type": "object", "properties": { "create": { "$ref": "#/components/schemas/OperationSupport" }, "update": { "$ref": "#/components/schemas/OperationSupport" }, "delete": { "$ref": "#/components/schemas/OperationSupport" }, "read": { "$ref": "#/components/schemas/OperationSupport" } } }, "SupportPerBenefitType": { "title": "SupportPerBenefitType", "type": "object", "properties": { "company_benefits": { "$ref": "#/components/schemas/OperationSupportMatrix" }, "individual_benefits": { "$ref": "#/components/schemas/OperationSupportMatrix" } } }, "Error": { "title": "Error", "type": "object", "description": "Generic error response structure", "properties": { "code": { "type": "integer", "description": "The status code of the request." }, "name": { "type": "string", "description": "Identifier describing the error." }, "finch_code": { "type": "string", "description": "A descriptive identifier for the error." }, "message": { "type": "string", "description": "A short English description that provides more information about the error." } }, "required": ["code", "name", "finch_code", "message"] }, "AcceptedResponse": { "type": "object", "properties": { "code": { "type": "number", "default": 202 }, "name": { "type": "string" }, "finch_code": { "type": "string" }, "message": { "type": "string" } }, "required": ["name", "finch_code", "message"] }, "BatchError": { "type": "object", "properties": { "code": { "type": "number" }, "finch_code": { "type": "string" }, "message": { "type": "string" }, "name": { "type": "string" } }, "required": ["code", "message", "name"] }, "CreateSandboxPaymentRequest": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "pay_statements": { "type": "array", "items": { "type": "object", "properties": { "individual_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "nullable": true, "enum": ["off_cycle_payroll", "one_time_payment", "regular_payroll", null], "default": "regular_payroll" }, "payment_method": { "type": "string", "nullable": true, "enum": ["check", "direct_deposit", "other", null], "default": "direct_deposit" }, "total_hours": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "gross_pay": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 9007199254740991 }, "net_pay": { "type": "integer", "maximum": 9007199254740991 }, "earnings": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "hours": { "type": "number" }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "bonus", "commission", "double_overtime", "other", "overtime", "pto", "reimbursement", "salary", "severance", "sick", "tips", "wage", "1099" ] } } } }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "name": { "type": "string", "minLength": 1 }, "employer": { "type": "boolean" }, "type": { "type": "string", "enum": ["federal", "fica", "local", "state"] } } } }, "employee_deductions": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "name": { "type": "string", "minLength": 1, "description": "The deduction name. Required when type is specified." }, "pre_tax": { "type": "boolean" }, "type": { "type": "string", "enum": [ "457", "401k", "401k_roth", "401k_loan", "403b", "403b_roth", "457_roth", "commuter", "custom_post_tax", "custom_pre_tax", "fsa_dependent_care", "fsa_medical", "hsa_post", "hsa_pre", "s125_dental", "s125_medical", "s125_vision", "simple", "simple_ira" ], "x-stainless-renameMap": { "_401k_loan": "401k_loan", "_401k_roth": "401k_roth", "_401k": "401k", "_403b_roth": "403b_roth", "_403b": "403b", "_457_roth": "457_roth", "_457": "457" } } } } }, "employer_contributions": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "name": { "type": "string", "minLength": 1, "description": "The contribution name. Required when type is specified." }, "type": { "type": "string", "enum": [ "457", "401k", "401k_roth", "401k_loan", "403b", "403b_roth", "457_roth", "commuter", "custom_post_tax", "custom_pre_tax", "fsa_dependent_care", "fsa_medical", "hsa_post", "hsa_pre", "s125_dental", "s125_medical", "s125_vision", "simple", "simple_ira" ], "x-stainless-renameMap": { "_401k_loan": "401k_loan", "_401k_roth": "401k_roth", "_401k": "401k", "_403b_roth": "403b_roth", "_403b": "403b", "_457_roth": "457_roth", "_457": "457" } } } } } }, "required": ["individual_id"] }, "maxItems": 10000, "description": "Array of pay statements to include in the payment." } }, "description": "Fields to configure the payment. Takes all fields from the `/payment` endpoint. All fields are optional." }, "AutomatedJobResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "The id of the job that has been created." }, "job_url": { "type": "string", "description": "The url that can be used to retrieve the job status" }, "allowed_refreshes": { "type": "integer", "description": "The number of allowed refreshes per hour (per hour, fixed window)" }, "remaining_refreshes": { "type": "integer", "description": "The number of remaining refreshes available (per hour, fixed window)" }, "retry_at": { "type": "string", "description": "ISO 8601 timestamp indicating when to retry the request" } }, "required": ["allowed_refreshes", "remaining_refreshes"] }, "AutomatedJobRequest": { "oneOf": [ { "type": "object", "title": "data_sync_all", "properties": { "type": { "type": "string", "description": "The type of job to start.", "enum": ["data_sync_all"] } }, "required": ["type"] }, { "type": "object", "title": "w4_form_employee_sync", "properties": { "type": { "type": "string", "description": "The type of job to start.", "enum": ["w4_form_employee_sync"] }, "params": { "type": "object", "properties": { "individual_id": { "type": "string", "description": "The unique ID of the individual for W-4 data sync." } }, "required": ["individual_id"] } }, "required": ["type", "params"] } ], "discriminator": { "propertyName": "type" } }, "ListAutomatedJobsResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "quotas": { "type": "object", "properties": { "data_sync_all": { "type": "object", "properties": { "allowed_refreshes": { "type": "number" }, "remaining_refreshes": { "type": "number" } } } } } } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomatedAsyncJob" } } } }, "TooManyRequestsResponse": { "type": "object", "properties": { "allowed_refreshes": { "type": "integer" }, "remaining_refreshes": { "type": "integer" }, "retry_at": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "status": { "type": "integer" }, "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" } }, "required": ["statusCode", "status", "code", "name", "message"] }, "CreateAccessTokenRequest": { "type": "object", "properties": { "client_id": { "type": "string", "format": "uuid", "description": "The client ID for your application" }, "client_secret": { "type": "string", "description": "The client secret for your application" }, "code": { "type": "string", "description": "The authorization code received from the authorization server" }, "redirect_uri": { "type": "string", "description": "The redirect URI used in the authorization request (optional)" } }, "required": ["code"] }, "ConnectionStatusDetail": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ConnectionStatus" }, "message": { "type": "string" }, "last_successful_sync": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" }, { "nullable": true } ], "description": "The datetime when the connection was last successfully synced" } }, "required": ["status"] }, "AuthenticationMethodDetail": { "type": "object", "properties": { "type": { "type": "string", "enum": ["assisted", "credential", "api_token", "api_credential", "oauth"], "description": "The type of authentication method" }, "connection_status": { "$ref": "#/components/schemas/ConnectionStatusDetail" }, "products": { "type": "array", "items": { "type": "string" }, "description": "An array of the authorized products associated with the `access_token`" } }, "required": ["type"] }, "ForwardRequest": { "type": "object", "properties": { "method": { "type": "string", "description": "The HTTP method for the forwarded request. Valid values include: `GET` , `POST` , `PUT` , `DELETE` , and `PATCH`." }, "route": { "type": "string", "description": "The URL route path for the forwarded request. This value must begin with a forward-slash ( / ) and may only contain alphanumeric characters, hyphens, and underscores." }, "params": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "The query parameters for the forwarded request. This value must be specified as a valid JSON object rather than a query string." }, "data": { "type": "string", "nullable": true, "description": "The body for the forwarded request. This value must be specified as either a string or a valid JSON object." }, "request_headers": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "The HTTP headers to include on the forwarded request. This value must be specified as an object of key-value pairs. Example: `{\"Content-Type\": \"application/xml\", \"X-API-Version\": \"v1\" }`" } }, "required": ["method", "route"] }, "ForwardResponse": { "type": "object", "properties": { "headers": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "The HTTP headers of the forwarded request's response, exactly as received from the underlying integration's API." }, "statusCode": { "type": "integer", "description": "The HTTP status code of the forwarded request's response, exactly received from the underlying integration's API. This value will be returned as an integer." }, "data": { "type": "string", "nullable": true, "description": "A string representation of the HTTP response body of the forwarded request's response received from the underlying integration's API. This field may be null in the case where the upstream system's response is empty." }, "request": { "type": "object", "properties": { "method": { "type": "string", "description": "The HTTP method that was specified for the forwarded request. Valid values include: `GET` , `POST` , `PUT` , `DELETE` , and `PATCH`." }, "route": { "type": "string", "description": "The URL route path that was specified for the forwarded request." }, "headers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "The HTTP headers that were specified for the forwarded request." }, "params": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "The query parameters that were specified for the forwarded request." }, "data": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "nullable": true } }, { "nullable": true }, { "nullable": true } ], "description": "The body that was specified for the forwarded request." } }, "required": ["method", "route"], "description": "An object containing details of your original forwarded request, for your ease of reference." } }, "required": ["statusCode", "request"] }, "Provider": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the payroll provider used in Connect." }, "display_name": { "type": "string", "description": "The display name of the payroll provider." }, "products": { "type": "array", "items": { "type": "string" }, "description": "The list of Finch products supported on this payroll provider." }, "icon": { "type": "string", "description": "The url to the official icon of the payroll provider." }, "logo": { "type": "string", "description": "The url to the official logo of the payroll provider." }, "mfa_required": { "type": "boolean", "description": "whether MFA is required for the provider." }, "primary_color": { "type": "string", "description": "The hex code for the primary color of the payroll provider." }, "manual": { "type": "boolean", "description": "[DEPRECATED] Whether the Finch integration with this provider uses the Assisted Connect Flow by default. This field is now deprecated. Please check for a `type` of `assisted` in the `authentication_methods` field instead.", "deprecated": true }, "beta": { "type": "boolean", "description": "`true` if the integration is in a beta state, `false` otherwise" }, "authentication_methods": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["assisted", "credential", "api_token", "api_credential", "oauth", "api"], "description": "The type of authentication method" }, "benefits_support": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The supported benefit types and their configurations" }, "supported_fields": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The supported fields for each Finch product" } }, "required": ["type"] }, "description": "The authentication methods supported by the provider." } }, "required": ["id", "display_name", "products"] }, "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"] }, "EmployeeDeductionContribution": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["fixed"], "description": "Contribution type. Supported values: \"fixed\" (amount in cents) or \"percent\" (amount in basis points)." }, "amount": { "type": "integer", "description": "Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%)." } }, "required": ["type", "amount"], "title": "EmployeeDeductionContributionFixed" }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["percent"], "description": "Contribution type. Supported values: \"fixed\" (amount in cents) or \"percent\" (amount in basis points)." }, "amount": { "type": "integer", "description": "Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%)." } }, "required": ["type", "amount"], "title": "EmployeeDeductionContributionPercent" }, { "nullable": true } ], "description": "Employee deduction configuration. Supports both fixed amounts (in cents) and percentage-based contributions (in basis points where 100 = 1%).", "title": "EmployeeDeductionContribution", "x-tags": ["Models"] }, "CompanyContribution": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["fixed"], "description": "Contribution type. Supported values: \"fixed\" (amount in cents), \"percent\" (amount in basis points), or \"tiered\" (multi-tier matching)." }, "amount": { "type": "integer", "description": "Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%). Not used for type=tiered." } }, "required": ["type", "amount"], "title": "CompanyContributionFixed" }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["percent"], "description": "Contribution type. Supported values: \"fixed\" (amount in cents), \"percent\" (amount in basis points), or \"tiered\" (multi-tier matching)." }, "amount": { "type": "integer", "description": "Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%). Not used for type=tiered." } }, "required": ["type", "amount"], "title": "CompanyContributionPercent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["tiered"], "description": "Contribution type. Supported values: \"fixed\" (amount in cents), \"percent\" (amount in basis points), or \"tiered\" (multi-tier matching)." }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "match": { "type": "integer", "minimum": 1, "maximum": 10000 }, "threshold": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": ["match", "threshold"] }, "minItems": 1, "description": "Array of tier objects defining employer match tiers based on employee contribution thresholds. Required when type=tiered." } }, "required": ["type", "tiers"], "title": "CompanyContributionTiered" }, { "nullable": true } ], "description": "Company contribution configuration. Supports fixed amounts (in cents), percentage-based contributions (in basis points where 100 = 1%), or tiered matching structures.", "title": "CompanyContribution", "x-tags": ["Models"] }, "CreateConnectSessionRequest": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique identifier for the customer" }, "customer_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the customer" }, "customer_email": { "type": "string", "nullable": true, "format": "email", "description": "Email address of the customer" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectProducts" }, "description": "The Finch products to request access to. Use `benefits` to access deductions endpoints — `deduction` is a deprecated alias that is still accepted but should not be combined with `benefits`." }, "redirect_uri": { "type": "string", "nullable": true, "description": "The URI to redirect to after the Connect flow is completed" }, "minutes_to_expire": { "type": "number", "nullable": true, "minimum": 1, "maximum": 129600, "description": "The number of minutes until the session expires (defaults to 129,600, which is 90 days)" }, "sandbox": { "type": "string", "nullable": true, "enum": ["finch", "provider", null], "description": "Sandbox mode for testing" }, "manual": { "type": "boolean", "nullable": true, "description": "Enable manual authentication mode" }, "integration": { "type": "object", "nullable": true, "properties": { "provider": { "type": "string", "description": "The provider to integrate with" }, "auth_method": { "type": "string", "nullable": true, "enum": ["assisted", "credential", "oauth", "api_token", null], "description": "The authentication method to use" } }, "required": ["provider"], "description": "Integration configuration for the connect session" } }, "required": ["customer_id", "customer_name", "products"] }, "CreateConnectSessionResponse": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The unique identifier for the created connect session" }, "connect_url": { "type": "string", "format": "uri", "description": "The Connect URL to redirect the user to for authentication" } }, "required": ["session_id", "connect_url"] }, "ReauthenticateRequest": { "type": "object", "properties": { "redirect_uri": { "type": "string", "nullable": true, "format": "uri", "description": "The URI to redirect to after the Connect flow is completed" }, "minutes_to_expire": { "type": "integer", "description": "The number of minutes until the session expires (defaults to 43,200, which is 30 days)" }, "products": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ConnectProducts" }, "description": "The products to request access to (optional for reauthentication). Use `benefits` to access deductions endpoints — `deduction` is a deprecated alias that is still accepted but should not be combined with `benefits`." }, "connection_id": { "type": "string", "description": "The ID of the existing connection to reauthenticate" } }, "required": ["connection_id"] }, "ReauthenticateResponse": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The unique identifier for the created connect session" }, "connect_url": { "type": "string", "format": "uri", "description": "The Connect URL to redirect the user to for reauthentication" } }, "required": ["session_id", "connect_url"] }, "MultiAccountEntity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The connection account ID for this entity" }, "name": { "type": "string", "nullable": true, "description": "The name of the entity (payroll provider company name)" }, "source_id": { "type": "string", "nullable": true, "description": "The source ID of the entity" }, "status": { "$ref": "#/components/schemas/EntityConnectionStatus" } }, "required": ["id", "name", "source_id", "status"] }, "DisconnectEntityRequest": { "type": "object", "properties": { "entity_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Array of entity UUIDs to disconnect. At least one entity ID must be provided." } }, "required": ["entity_ids"] }, "DisconnectEntityResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "If the request is successful, Finch will return \"success\" (HTTP 200 status)." } }, "required": ["status"] }, "DisconnectEntityErrorItem": { "type": "object", "properties": { "entityId": { "type": "string", "format": "uuid", "description": "The entity ID that failed." }, "error": { "type": "string", "enum": ["NOT_FOUND"], "description": "The error code indicating why the entity could not be disconnected." } }, "required": ["entityId", "error"] }, "DisconnectEntityErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/DisconnectEntityErrorItem" }, "description": "List of entity IDs that failed validation and their error codes." } }, "required": ["errors"] }, "EntityConnectionStatus": { "type": "string", "enum": [ "pending", "processing", "connected", "error_no_account_setup", "error_permissions", "reauth", "disconnected" ], "description": "The status of the entity connection" }, "LedgerTotals": { "type": "object", "properties": { "debit": { "$ref": "#/components/schemas/LedgerMoney" }, "credit": { "$ref": "#/components/schemas/LedgerMoney" }, "balanced": { "type": "boolean", "description": "`true` when total debit equals total credit." } }, "required": ["debit", "credit", "balanced"], "title": "Ledger Totals" }, "LedgerEntry": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "regular_wages", "overtime_wages", "bonus_wages", "paid_leave_wages", "severance_wages", "equity_compensation", "other_earnings", "expense_reimbursement", "contractor_payment", "employer_donation", "employer_tax_fica", "employer_tax_unemployment", "employer_tax_other", "employee_tax_income", "employee_tax_fica", "employee_tax_other", "employer_contribution_retirement", "employer_contribution_health", "employer_contribution_other", "pretax_deduction", "posttax_deduction", "garnishment", "benefit_liability", "tax_liability_accrual", "tax_receivable", "tax_credit_accrual", "cash_debit_net_pay", "cash_debit_tax_remittance", "cash_debit_other", "adjustment", "other" ], "description": "The canonical Finch classification for this ledger entry." }, "account_type": { "type": "string", "nullable": true, "description": "The provider's passthrough account type for this entry." }, "account_description": { "type": "string", "nullable": true, "description": "The provider's passthrough account description." }, "debit": { "$ref": "#/components/schemas/LedgerMoney" }, "credit": { "$ref": "#/components/schemas/LedgerMoney" } }, "required": ["type", "account_type", "account_description", "debit", "credit"], "title": "Ledger Entry" }, "LedgerItemsData": { "type": "object", "properties": { "source": { "type": "string", "enum": ["direct", "synthesized"], "description": "`direct` when sourced from the provider GL API; `synthesized` when computed from pay statements." }, "provider_description": { "type": "string", "nullable": true, "description": "The provider's passthrough ledger description." }, "pay_date": { "type": "string", "description": "The payroll check date for this ledger, in `YYYY-MM-DD`." }, "totals": { "$ref": "#/components/schemas/LedgerTotals" }, "paging": { "type": "object", "properties": { "count": { "type": "integer", "description": "The total number of elements for the entire query (not just the given page)" }, "offset": { "type": "integer", "description": "The current start index of the returned list of elements" } }, "required": ["offset"], "title": "Paging", "x-tags": ["Models"] }, "ledger_items": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } } }, "required": ["source", "provider_description", "pay_date", "totals", "paging", "ledger_items"], "title": "Ledger Items Data" }, "LedgerBatchItem": { "type": "object", "properties": { "payment_id": { "type": "string" }, "code": { "type": "integer" }, "body": { "anyOf": [ { "$ref": "#/components/schemas/LedgerItemsData" }, { "$ref": "#/components/schemas/BatchError" } ] } }, "required": ["payment_id", "code", "body"], "title": "Ledger Batch Item" }, "GetLedgerItemsResponse": { "type": "object", "properties": { "responses": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerBatchItem" } } }, "required": ["responses"] }, "LedgerMoney": { "type": "object", "properties": { "amount": { "type": "integer", "description": "The amount in cents." }, "currency": { "type": "string", "nullable": true, "description": "The ISO 4217 currency code." } }, "required": ["amount", "currency"], "title": "Ledger Money" }, "individual_or_employment": { "allOf": [ { "$ref": "#/components/schemas/IndividualWithoutId" }, { "$ref": "#/components/schemas/EmploymentWithoutId" } ] } }, "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"] } } } }, "Individual": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "individual_id": { "type": "string" } } } }, "options": { "type": "object", "nullable": true, "properties": { "include": { "type": "array", "items": { "type": "string" } } } } } } } } }, "Forward": { "content": { "application/json": { "schema": { "type": "object", "description": "Forward Request Body", "properties": { "method": { "type": "string", "description": "The HTTP method for the forwarded request. Valid values include: `GET` , `POST` , `PUT` , `DELETE` , and `PATCH`." }, "route": { "type": "string", "description": "The URL route path for the forwarded request. This value must begin with a forward-slash ( / ) and may only contain alphanumeric characters, hyphens, and underscores." }, "headers": { "type": "object", "description": "The HTTP headers to include on the forwarded request. This value must be specified as an object of key-value pairs. Example: `{\"Content-Type\": \"application/xml\", \"X-API-Version\": \"v1\" }`", "nullable": true }, "params": { "type": "object", "description": "The query parameters for the forwarded request. This value must be specified as a valid JSON object rather than a query string.", "nullable": true }, "data": { "type": "string", "description": "The body for the forwarded request. This value must be specified as either a string or a valid JSON object.", "nullable": true } }, "required": ["method", "route"] }, "examples": { "Sample": { "value": { "method": "POST", "route": "/people/search", "headers": { "content-type": "application/json" }, "params": { "showInactive": true, "humanReadable": true }, "data": null } } } } } }, "CreateSandboxPaymentRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxPaymentRequest" } } } } }, "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" } }, "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 }, "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 ", "x-stainless-param": false } } } }