Skip to main content

​
Quick start checklist

  1. ✓ Identify supported providers
  2. ✓ Get, register, or create company-level deduction to receive benefit_id and job_id
  3. ✓ Wait for company-level deduction job to complete (poll GET /jobs/manual/ or use webhook)
  4. ✓ Call GET /jobs/manual/ to verify job succeeded (check response body for errors)
  5. ✓ If the job failed, alert personnel and retry with corrections — do not proceed to enrollments
  6. ✓ Enroll individuals using verified benefit_id from successful job
  7. ✓ Verify individual enrollment jobs succeeded (call GET /jobs/manual/ for each enrollment job)
As with all Finch API calls, these requests must be made from your backend — see Backend Security. Our Deductions product allows developers to write payroll contributions and deductions changes for retirement, medical, and other benefit use cases. Finch Deductions APIs operate at two levels: the company-level and the individual-level. Company-level APIs allow you to create and update deductions at the company-level. For automated integrations you can also read company-level deductions. Individual-level APIs allow you to enroll and un-enroll individuals in deductions, and update their individual-level configurations. For automated integrations you can also read individual-level enrollments.

​
Identify supported providers

Before implementing our Deductions APIs, make sure you identify providers that support the types of deductions and features your use case requires.

​
Assisted vs automated integrations deductions support

You can identify which providers are automated and assisted using our Provider Network. See Integration Types: Assisted for the current SLAs for configuration period and data syncs. This tells you what a provider supports. Which endpoint your application uses to get a benefit_id, and whether it can call the GET endpoints to read deductions and enrollments, depends on how a specific connection is authenticated — see Determine whether a connection is automated or assisted for Deductions. Create Deduction, enroll, and unenroll requests are the same for automated and assisted connections.

​
Use the providers endpoint or field support matrix to check provider capability

The types and features of each deduction can vary between providers. Providers have varying limitations on which operations are available and which actions can be performed. Finch provides two tools for this. Both describe the same thing — every provider, the deduction types it supports, and the features available for each type — because the Field Support Matrix is a browsable view of the providers endpoint. Pick whichever fits what you are doing. If you try to make a request using an access token that does not allow a certain configuration or deduction type, our API will respond with a 400 or 422 status code (see Errors), depending on the error.

​
Prepare for provider limitations when creating company level deductions

Some providers do not allow creation of company level deductions using the Finch API (Create Deduction). Use the providers endpoint or field support matrix explained above to identify providers that do not support this for deductions. For those providers, you should confirm with the employer that the correct deduction is set up in their system prior to enrolling individuals through Finch. Then get the benefit_id for the company level deduction from the endpoint that matches the connection’s status in /introspect: Get All Deductions for an automated connection, Register Deduction for an assisted one. Then you can enroll and update individual level deductions. If the deduction isn’t set up in the provider system:
  • Automated connection: Get All Deductions won’t return the deduction, so you won’t have a benefit_id for it.
  • Assisted connection: Register Deduction returns a benefit_id, but the job completes with an error. Enrollments sent with that benefit_id will fail, so verify the job succeeded before you enroll individuals.
In either case, ask the employer to set up the deduction, then get or register it again.

​
Verify successful deduction job completion using jobs endpoint

For all deduction write requests, both automated and assisted, call GET /jobs/manual/ to check the job status and response body which will include a message with details about the cause of any errors.

​
Getting and creating company level deductions

Before your application can manage individual enrollments and updates for individuals, your system needs the Finch benefit_id for the company wide deduction that the individual is or will be enrolled in. The Finch Deduction API has three endpoints that return a benefit_id in the response body. For example, a Create Deduction or Register Deduction request responds with:
Your application will use this benefit_id to perform enrollment, un-enrollment, and deduction retrieval actions on individuals. Your application can use the job_id and the Retrieve a Manual Job endpoint to get the status of the job. The valid job status responses will be either pending, in_progress, complete, or error with a response body further explaining the response.

​
Determine whether a connection is automated or assisted for Deductions

Which endpoint your application uses to get a benefit_id, and whether it can call the GET endpoints, depends on whether this specific connection authenticates Deductions through an automated or an assisted method. Create Deduction, enroll, and unenroll requests are the same for both. Read the connection’s method from /introspect, not from /providers or the Provider Network. Call GET /introspect with the connection’s access_token, find the entry in authentication_methods whose products array includes benefits, and read that entry’s type: Branch on assisted explicitly rather than allow-listing the automated values, so a new authentication method added to the enum doesn’t silently route an automated connection down the assisted path. authentication_methods is an array because a connection can use a different method per product — reading Organization data over credential while writing deductions over assisted, for example. Match on the entry that covers benefits rather than reading the first entry. See the Introspect endpoint reference for the full response shape.
Do not derive automated versus assisted from /providers or the Provider Network page. When Finch migrates a provider’s Deductions support from assisted to automated, the provider manifest and existing connections aren’t updated at the same moment. During a migration, /providers may report a provider as automated while a connection you hold is still assisted, or report it as assisted while your connection has already moved to automated. /introspect always reflects the connection’s current method. Routing write calls off /providers during a migration risks sending a connection down the wrong path: an assisted connection treated as automated calls Get All Deductions, which is unavailable and fails; an automated connection treated as assisted calls Register Deduction, which fails too.
Create Deduction, Register Deduction, and Get All Deductions are the endpoints that return a benefit_id to use for enrolling and updating individual deductions and contributions. Your application should use the appropriate endpoint based on if the connection is automated or assisted for deductions and if the deduction already exists in the provider system, as determined above.
Always verify job success before enrolling individualsAfter receiving a benefit_id from Create Deduction or Register Deduction, verify the job completed successfully before making any enrollment requests with that benefit_id.How to verify:
  1. Wait for the job to complete by either:
  2. Once complete, call GET /jobs/manual/ to check the response body for error codes and messages
  3. If the job has an error, alert appropriate personnel and do not proceed with enrollments
Why this matters: A job status of complete does not mean success — it means the job finished processing. The job could complete with an error. If there was an error, the response body will contain details about what went wrong. Correct the issue and submit a new request. Finch does not automatically retry failed jobs.If you enroll individuals using a benefit_id from a failed job, all enrollment requests will fail. Recovering from this scenario requires complex retry logic that most applications are not designed to handle.Always call the jobs endpoint to verify success after completion.

​
Enrolling and unenrolling individuals

These endpoints change deductions and contributions in the payroll system only. Enrolling an employee in the benefit itself, such as with a health insurance carrier or a 401(k) recordkeeper, is usually a separate process. Confirm that your system handles any steps outside payroll.

​
Creating new individual enrollments

To enroll a new individual for a contribution or deduction, use the benefit_id returned from the appropriate deductions endpoints above, and make a request to POST /benefits/{benefit_id}/individuals request. This is a batch request endpoint. In the request body, you should provide a list of objects. Each object will specify the individual_id (from the directory endpoint in Organization), and a configuration object which specifies the enrollment configuration to applies to that individual Use the API Reference to identify which fields should be included in the object for specific types of deductions. Note that none are required by our API, but the provider may require specific fields and return an error if they are not included.

​
Updating existing individual enrollments

To update the enrollment for currently enrolled individuals, use the same POST /benefits/{benefit_id}/individuals endpoint that you use to enroll new individuals. When updating an existing enrollment for an individual, the enrollment configuration will be completely overwritten with the new configuration provided in the request, so please make sure to include the entire desired configuration. Since they both use the same endpoint, these update requests can be submitted in the same batch request as new enrollment requests.

​
Un-enrolling individuals

You can unenroll individuals by using the DELETE /benefits/{benefit_id}/individuals endpoint. This will remove the enrollment configuration for an individual.

​
Deduction sequence diagram

The following diagram shows the basic deductions flow. It can be used with either the Register (assisted connections only) or Create endpoints to obtain the benefit_id. The flow is very similar for use with the Get All Deductions (automated integrations only) except that your application will need to handle a response with multiple benefit objects (see the API reference for response fields and examples). deductions flow.png

​
Handling failures

Managing deductions and contributions is a time and money-sensitive activity. In the unlikely event that a request through Finch fails, your team should have a process in place to handle enrollments or to inform employers. Leave enough time between submitting a request and the payroll close date to address any issues. See Timing submissions for recommended lead times. Enrollment and un-enrollment requests and responses are batched. This means that some enrollments/un-enrollments could succeed while others fail. For both automated and assisted integrations expect a job_id in the response body. You can use this job_id to get the status of the job and see which individuals were successfully enrolled or un-enrolled.
Top-level

​
General deductions schedule

Since enrolling individuals in deductions and contributions can be a sensitive activity, it is helpful to understand some of the nuances around payroll in general.

​
How do payroll deductions work?

Each payroll contains four important dates to know.
  1. Payroll Start Date - The first day of the pay period
  2. Payroll End Date - The last day of the pay period
  3. Payroll Close Date - The last date to make changes for that pay period
  4. Paycheck Date - The date on which employees are paid
Note - You can get the payroll start_date, end_date, and the pay_date for past pay statements using our pay statement API, but our system cannot provide the payroll close date. You will need to either get that information from the employer or set expectations for update based on their close date generically

​
Timing submissions

Submit deduction and contribution changes before the payroll close date for them to take effect in the current pay period. Changes submitted after the close date apply to the next pay period. Close dates vary by provider and employer, so know the close date and set expectations with your customers. Leave at least 1 day between Finch’s response and the close date, so you have time to address any errors:
  • Automated connections: Submit at least 24 hours before the close date.
  • Assisted connections: Submit at least 3 days before the close date to account for the 2 business day SLA.
To schedule a change for a future pay period instead, include an effective_date. Example For a payroll period of June 1–15, the payroll close date might be June 16, so payroll can be processed before the June 17 pay date. Submit payroll deductions to the Finch API by June 11 for them to take effect in that June 1–15 payroll. 
June 2022
Su Mo Tu We Th Fr Sa
01 02 03 04 05 06 07
08 09 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30

​
Coordinate with payroll representatives

Some payroll providers offer a dedicated payroll representative to help with making payroll changes. If a payroll rep is helping your customer’s HR admin with changes in their system, it is important that you make it explicitly clear who does what so that the payroll rep does not overwrite any changes Finch has previously made. Calling out Benefit Code types and using thoughtful descriptions (e.g. with your company name) help.

​
Effective date

The effective_date parameter allows you to control when deduction or contribution changes take effect in an employee’s payroll. Use this parameter to schedule changes for an employee that will apply in future pay periods. effective_date sets which pay period a change starts in. Payroll systems don’t prorate a deduction or contribution by date, so the critical thing is that the effective_date falls in the correct pay period. It may not exactly match the date the employee’s benefit coverage starts.

​
How to use effective dates

When you submit a deduction or contribution change with an effective_date, Finch processes your request within 2 business days of the specified effective date. Immediate Changes
  • Scenario: You need a change to take effect as soon as possible.
  • How to do it: Don’t specify any effective_date parameter.
  • What happens
    • Finch submits the change to the payroll provider immediately for Automated providers, or within the 2 day SLA for Assisted providers.
    • The change should be reflected in the current or next pay period, depending on the provider’s payroll cutoff date
Example
Top-level
Scheduled Changes
  • Scenario: You want a change to begin on a specific date.
  • How to do it: Set effective_date to a date more than 2 business days in the future.
  • What happens
    • Finch schedules the change and submits it to the payroll provider on or up to 1 business day before your specified date.
    • The change will be included in the pay period containing your effective_date. If that pay period has already closed by the time Finch submits the change, it will apply to the next available pay period instead.
    • Your job will show a pending status until Finch submits it.
Example
Top-level
Scheduling Limits
  • Effective dates in the past or within the next 2 business days will be processed immediately for Automated providers and within the 2 day SLA for Assisted providers.
  • There is no hard limit on how far in the future you can schedule changes, but we recommend scheduling changes no more than 90 days in advance. The job will be stay in pending for this duration.
Batch Requests with Effective Dates You can include an effective date when submitting multiple deduction or contribution changes in a single batch request. Note that the entire batch should have the same effective date. When all updates in a batch share the same effective date:
  • All changes are processed together as a group
  • They follow the same timing rules as single requests:
    • Historical dates: Submitted immediately
    • Future dates: Scheduled and submitted on or shortly before the effective date
    • No date: Submitted immediately
If a batch includes more than one effective date, Finch returns a single job_id for the whole batch. The job stays pending until the change with the latest effective date is processed, so you won’t get success or error results for any individual in the batch until then. Sandbox connections reject batches with more than one effective date.

​
Tracking request status

Monitoring Scheduled Changes Use the manual job status endpoint to check on scheduled changes:
Top-level

​
Understanding request states

When you submit a change with a future effective date, you can check the status of that change via the manual job status endpoint:
  1. pending: The change is scheduled but not yet submitted to the provider
  2. in_progress: Finch is submitting the change to the provider
  3. complete: The change has been successfully submitted into the payroll system
  4. error: Something went wrong (see error details for resolution steps)
For batch requests, ensure that all individuals in the batch have been processed successfully. Submit another request for any individuals that were not successful. Best Practices Do:
  • Use future effective dates for planned changes like new hire benefits or scheduled contribution increases
  • Omit effective_date for urgent changes that should apply as soon as possible
  • Allow at least 2 business days lead time when scheduling future changes
  • Monitor job status for scheduled requests to ensure they’re processed on time
  • Check provider-specific behavior if you need precise timing guarantees
Don’t:
  • Rely on retroactive processing for past effective dates - most providers don’t support this
  • Specify effective dates within 2 business days if you need a guaranteed future date (they’ll be processed immediately)
  • Assume immediate application even without an effective date - payroll cutoff dates may delay application to the next period
  • Create a batch request with different effective dates - the job stays pending, with no results for any individual, until the latest effective date is processed
  • Send conflicting requests for the same individual and benefit while an earlier request is still pending

​
Cancel or modify a request

Finch doesn’t offer an endpoint to cancel or edit a deduction request after you submit it. A request stays in pending status until Finch submits the change to the payroll provider. To cancel a pending request, contact Finch Support with the job_id, connection_id, benefit_id, and the affected individual_ids. If Finch hasn’t processed the request yet, we’ll close it without making the change. Once a change has been submitted to the provider, it can’t be canceled. Send a new enroll or unenroll request to reverse it. To correct a pending request, ask Finch Support to cancel it, then submit the corrected request. Don’t send a second, conflicting request for the same individual and benefit while the first is still pending. For assisted integrations, Finch doesn’t guarantee the order in which pending requests are processed. To change a completed request, send a new enroll or unenroll request.

​
FAQs

It depends on the integration type and whether you include an effective_date.
  • Automated integrations, no effective_date: Requests are processed in the order received. The last request processed is the one reflected in payroll.
  • Assisted integrations: Finch’s operations team enters requests in the provider system within 2 business days. Requests aren’t guaranteed to be processed in the order received, even when they share the same effective_date. If two conflicting requests for the same individual and benefit are pending at the same time, Finch can’t guarantee which one is applied last.
  • Requests with different effective_dates: Finch holds each request until its effective date and processes requests in effective_date order. The request with the latest effective_date is the one reflected in payroll.
To get a predictable result:
  • Batch requests by effective_date. Every request in a batch should share the same effective_date.
  • Send one request per individual, per benefit, per effective_date.
  • Wait for a job to reach complete (GET /jobs/manual/) before you send another change for the same individual and benefit.
  • If you need to change a pending request, cancel it through Finch Support first. See Cancel or modify a request.
Finch doesn’t offer an endpoint to cancel or edit a request. See Cancel or modify a request for how to cancel, correct, or reverse a request.
If you submit an enroll request for an individual who is already enrolled in a deduction, the existing enrollment will be updated with the new configuration provided in the request. The status of the request will be a 200 instead of a 201.
The effective_date parameter determines when the request is processed in the provider system. The request will be processed on the effective_date, which must be in the future. Requests should be batched by effective_date, and the order of processing will be based on the effective_date rather than the order in which they are received. If you submit multiple requests with different effective_dates for the same individual, the last request with the latest effective_date will overwrite any previous requests.
For assisted integrations The effective_date that is submitted will be entered into the provider system if the provider has the capabilities to ingest a future effective date and the date is within the allowed range. In case the provider does not have this capability, we will apply the change on the effective date. Note that effective_date is not supported across all providers, some do not accept past effective dates, and some have a limited future window for dates.For automated integrations, we apply the changes on the effective date and do not enter an effective date into the provider system.You can expect that the enrollment will be effective for the pay period that the request is processed if it is processed before the close date of that pay period. Include an effective_date in a future pay period if you want the enrollment to be effective for that pay period.

​
Why job verification matters

When you create or register a company-level deduction, Finch returns both a benefit_id and a job_id immediately. However, this does not mean the deduction has been successfully created in the provider system yet. The job may still be processing (pending or in_progress status), or it could complete with an error. Understanding Job Status: A critical distinction exists between job completion and job success:
  • status: complete means the job finished processing — it does not guarantee success
  • You must call GET /jobs/manual/ and inspect the response body for error code and message fields to determine if the job actually succeeded
  • Common failure scenarios include: provider validation errors, missing required fields, duplicate deductions, or provider system issues
Determining When to Check: You have two options for knowing when to check the job status:
  • Polling: Repeatedly call GET /jobs/manual/ until status changes to complete, then examine the response body. This is not recommended. If you opt to use the approach we recommend polling every 1 hour for automated integrations and once per day for assisted integrations.
  • Webhooks: RECOMMENDED Subscribe to the job completion webhook event job.benefit_*.completed to be notified when the job completes, then call GET /jobs/manual/ to examine the response body
Both approaches require calling the jobs endpoint to verify success and read error details. The webhook removes the need to poll repeatedly. The Problem: If you use the benefit_id to enroll individuals before confirming the company-level deduction job succeeded, you’re submitting enrollment requests for a deduction that may not exist or may have failed to create. These enrollment attempts will be queued as jobs, but they will all fail because the underlying benefit_id is invalid. Handling Failures: If the company-level deduction register or create job completes with an error:
  1. Review the code and message in the response body to understand what went wrong
  2. Alert appropriate personnel (e.g., log the error, notify your support team, or surface the error to the user) so the issue can be addressed promptly
  3. Correct the issue in your request (e.g., fix validation errors, adjust deduction configuration)
  4. Submit a new Create Deduction or Register Deduction request
  5. Finch will not automatically retry failed jobs—you must handle retries in your application
Important: Do not silently fail. Many developers discover job failures only after attempting enrollments and wondering why nothing worked. Implement proper error handling and alerting when company-level deduction jobs fail. Why This Is Complex to Fix After the Fact: Once you’ve sent 50+ enrollment requests based on a failed benefit_id, you must:
  1. Detect that the original deduction creation failed (by finally checking the job body)
  2. Retry creating the company-level deduction with corrections based on the error message
  3. Track which individual enrollments failed
  4. Retry all failed enrollments with the new benefit_id
  5. Handle any individuals whose status may have changed during this process
Most applications are not designed to queue and retry batch operations in this way, leading to incomplete enrollments and data inconsistencies. The Solution: Always verify job success before proceeding with individual enrollments by calling GET /jobs/manual/ after the job completes. This check prevents cascading failures and keeps your enrollments anchored to valid deductions.

​
Checkpoint + next step

After completing this step, you can use the Finch Deductions API to manage company-level deductions and employee-level enrollments while accommodating provider limitations. Now that you have everything in place for full 360° read/write integrations, you can Prepare the Employer Experience.

​
Learn more