Finch Sandbox General Best Practices

Last updated: March 25, 2026

The Finch Sandbox provides a comprehensive testing environment for developing and validating payroll integrations. This guide covers essential practices for effectively using the sandbox across various testing scenarios.

Connection Management

Connection Limits and Capacity

Finch Sandbox allows 100 connections, providing ample capacity for comprehensive testing scenarios.

Important: Store your access tokens securely so you can properly disconnect connections when testing is complete. Disconnected connections do not count toward the 100 connection limit, allowing you to manage your sandbox capacity effectively.

Monitoring Connection Status

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

Creating Multiple Unique Companies

When testing multiple connections with the same provider, it's important to understand how company data is handled:

Default Behavior

If you use good_user for authentication across multiple connections with the same provider, each connection will share the same company data, including company ID and all associated information.

Creating Unique Companies

To create distinct companies for testing different scenarios, append a number to the username when using credential-based authentication:

  • First connection: good_user

  • Second connection: good_user_1

  • Third connection: good_user_2

  • And so on...

Each numbered username will generate a unique company with its own ID and data set, allowing you to test scenarios involving multiple distinct employers using the same payroll provider.

This approach is particularly useful when testing:

  • Multi-tenant applications

  • Company-specific data isolation

  • Different organizational structures within the same provider

  • Bulk operations across multiple companies

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

Sync Frequency Limits

Sandbox connections allow for 10 refresh data syncs per hour, as opposed to 1 per hour for production connections.

Error Handling and Debugging

Request Tracking

Always include the Finch-Request-Id header in your requests for debugging purposes. This helps track successful and unsuccessful requests across the sandbox environment.

Common Testing Scenarios

  • Connection failures and recovery

  • Data sync errors and retries

  • Authentication token expiration

  • Provider-specific error responses

  • Network timeout simulation

Best Practices Summary

  1. Plan your testing strategy: Define test scenarios before creating connections

  2. Manage connections efficiently: Track and disconnect unused connections

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

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

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

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

  7. Store tokens securely: Maintain access tokens for proper connection management

Conclusion

The Finch Sandbox provides powerful tools for comprehensive integration testing. By following these best practices, you can create robust test environments that accurately simulate production scenarios while efficiently managing your sandbox resources and thoroughly validating your integration's reliability and performance.