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

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 pay_date, start_date, and end_date.

2. Run a refresh data sync.

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"
  }'

Important Notes:

• 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

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"
  }'

When to contact support

Log the Finch-Request-Id header on every API request — successful and failed. When you open a support ticket, this ID is the fastest way for Finch to locate and diagnose what happened.

Reach out to your Implementation Engineer or submit a ticket if:

• A connection stays in pending after setting the status to connected

• Refresh syncs return consistent errors and your job configuration looks correct

• /employer endpoints return no data after a successful sync

• You need guidance on resetting your sandbox after reaching the 100-connection limit

Best Practices Summary

1. Manage connections efficiently: Track and disconnect unused connections

2. Always sync after changes: Remember to call refresh-job after data modifications

3. Use unique companies: Leverage numbered usernames for distinct test environments

4. Test edge cases: Include error scenarios and recovery testing

5. Monitor limits: Stay within rate limits and connection quotas