Sandbox: Advanced Testing

Finch Sandbox vs. Provider Sandbox: which to use

Start with the Finch Sandbox to test the full range of scenarios, including assisted integrations, and to iterate quickly with controlled data. Use the Provider Sandbox when you need to validate that data flows correctly end-to-end for automated integrations.

Testing large data sets

For guidance on configuring and testing with large numbers of employees or payments, see Testing Large Datasets in the Finch Sandbox.

Recommended Scenarios to Test

Use the /sandbox endpoints to configure specific employment scenarios before making API calls. Always run a refresh data sync after modifying data to see changes reflected in /employer responses.

Test Your Finch Connect Flow

• Successful connection — does your application correctly receive and store the authorization code, and exchange it for an access token?

• Reauthentication — when an employer reauthenticates an existing connection, confirm your system stores and uses the new access token. Test this by setting the connection status to error_reauth using Update a sandbox account, then walking through the reconnect flow.

Test specific data scenarios

Build test cases around:

• Null field values — Finch always returns the fields defined in the schema, but values may be null if a provider doesn't support the field or the employer hasn't populated it. Your application should handle null values without breaking.

• Reauthentication errors — connections can require reauth when a provider credential expires or changes. Test that your application detects and responds correctly to a 401 with REAUTHENTICATE_USER. The application should then generate a reauth session for that connection and then update your system with the new access_token after the employer completes the reauthentication session.

• Deductions edge cases — if you're using the Deductions product, test enrollment submissions and validate that your error handling surfaces the right feedback to your team and employers.

• Rate limits — Finch enforces rate limits per connection. Test that your request patterns stay within bounds and that your application handles 429 responses correctly.

Test Employee Onboarding

1. Call POST /sandbox/directory to add a new individual. Set employment_status to active.

2. Run a refresh data sync.

3. Call /employer/directory to confirm the individual appears.

4. Call /employer/individual/{individual_id} and /employer/employment/{individual_id} to verify their full record is populated correctly.

Test Employee Offboarding/Termination

1. Call PUT /sandbox/employment/{individual_id} to update employment_status to inactive and set a termination_date.

2. Run a refresh data sync.

3. Call /employer/employment/{individual_id} to confirm the termination is reflected.

4. Verify your application handles the status change correctly — for example, confirm that deductions enrollment no longer applies to terminated individuals.

Test Payments and Pay Statements

1. Call POST /sandbox/payment to add a payment. Specify start_date and end_date.

2. Run a refresh data sync. Confirm the job completes using the jobs endpoint.

3. Call /employer/payment to confirm the payment appears.

4. Call /employer/pay-statement with the payment_id to verify pay statement data for each individual.

Test Connection Status Changes

Use the Update Sandbox Account endpoint to simulate various connection states:

curl -X PUT "https://api.tryfinch.com/sandbox/connections/accounts" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_status": "error_reauth"
  }'

• If a connection shows as reauth in the Finch Sandbox, use this endpoint to update the status to connected for continued testing

• For all assisted integrations in sandbox, you are required to call this endpoint to set the status to connected. This replicates how assisted integrations in production must be manually set up by Finch after the initial connection is created

Testing logic that spans multiple pay statements

For logic that depends on a history of pay statements, such as year-to-date totals, annual contribution limits, or eligibility thresholds, create a small set of payments in the Finch Sandbox, save the responses, and build the rest of your scenarios as fixtures in your own test suite. Configuring every scenario as live sandbox data takes longer and runs into sandbox constraints.

Why fixtures work better for multi-pay-statement logic

• Sandbox pay history is generated once, when the connection is created. New payrolls don't accrue over time; you add each one with POST /sandbox/payment.

• A sync includes only payments with a pay date inside the connection's sync window, about 3 months back through 6 months ahead. Backdated payments can't build up a full year of history.

• Each sandbox scenario requires a create, refresh sync, and read cycle. Fixtures run in seconds and return the same result on every run.

How to build fixtures from sandbox data

1. Call POST /sandbox/payment to create 2–3 payments that include the earnings, employee_deductions, and employer_contributions types your logic reads. Set end_date (the pay date) inside the sync window.

2. Run a refresh data sync.

3. Call /employer/payment and /employer/pay-statement and save the raw JSON responses.

4. In your test suite, copy and edit those responses to build each scenario: change amounts, pay dates, the number of pay statements, or deduction types.

5. Keep one end-to-end test against the Finch Sandbox that runs the full flow, so you confirm your code reads the live response shape.

Example use cases for pay statement fixtures

Data Synchronization Requirements

Critical Step: Refresh Data Sync

Sandbox connections function just like production connections in that a sync is required in order for data updates to be reflected by Finch's /employer API endpoints. However, the data syncs do not run automatically every 24 hours in the Sandbox.

After adding or updating any data, always call the Refresh Job endpoint:

curl -X POST "https://api.tryfinch.com/sandbox/jobs" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "data_sync_all"
  }'