> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Finch Sandbox

> Test automated and assisted integrations with mock connections. Use sandbox API endpoints to configure mock data and test scenarios before going live.

The Finch Sandbox is a testing environment with mock connections that mirror the field and functionality of Finch's production integrations. You can configure connections to test scenarios your application needs to handle.

New to Finch? Start with [How the Finch API is organized](/how-finch-works/data-model). The four-diagram tour covers every core entity and how they connect in about five minutes.

<Note>
  Sandbox connections require your **sandbox** `client_id` and `client_secret`. Find these in the [Finch Dashboard](https://dashboard.tryfinch.com) under your sandbox application's settings. Production credentials will not work for sandbox connections.
</Note>

## Creating a sandbox connection

| Method                                                          | How                                                           | Notes                                                                                              | To test assisted                                           |
| --------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Finch Dashboard                                                 | Connections tab → **Actions** → **Create a New Connect Link** | Does not test token exchange                                                                       | Enable **Show assisted providers** above the URL generator |
| [Finch Connect](/api-reference/connect/new-session)             | Create a session with `"sandbox": "finch"`, then launch       | Exercises the full auth code exchange flow                                                         | Set `manual=true`                                          |
| [Sandbox API](/api-reference/sandbox/create-sandbox-connection) | Call with your sandbox `client_id` and `client_secret`        | Bypasses Finch Connect — best for automated or repeatable testing. Cannot test multi-entity flows. | Include the `assisted` parameter                           |

<Warning>
  `finch` and `provider` are the only accepted values for the `sandbox` parameter. See [Provider Sandboxes](/implementation-guide/Test/Provider-Sandboxes) for `provider` mode.
</Warning>

## Sandbox credentials

Finch Connect presents the authentication method supported by the provider and handles the flow — your application has no logic to implement for authentication. Use the credentials below that match the authentication method shown in Finch Connect for your test.

<Note>
  In production, Finch Connect presents only the authentication method supported by the connected provider. Most providers support a single method. The sandbox exposes all flows so you can understand how each one behaves.
</Note>

### Credential flows

| Username    | Password       | Simulated flow                                   |
| ----------- | -------------- | ------------------------------------------------ |
| `good_user` | `good_pass`    | Standard credential flow                         |
| `good_user` | `mfa`          | Credential flow with MFA step                    |
| `good_user` | `multi_entity` | Account selection screen (multi-entity employer) |

### API token flows

| Field                     | Value                                                        |
| ------------------------- | ------------------------------------------------------------ |
| Token                     | `good_token` — any other value returns an error              |
| Client ID / Client Secret | `good_user` / `good_pass` — any other values return an error |

### OAuth flows

All OAuth auth methods bypass the provider OAuth flow in sandbox mode. Clicking **Connect** immediately succeeds. OAuth providers do not support multi-entity testing — use providers with credential-based authentication to test multi-entity flows.

## Testing multi-entity employers

Use the `multi_entity` password to simulate a payroll system where a single login manages multiple entities. Finch Connect displays an account selection screen with each entity as a separate option.

<Note>
  Providers that use OAuth flows cannot be used for multi-entity testing. The `multi_entity` password only applies to credential-based authentication.
</Note>

To create multiple connections with the same provider where each connection has entities available, use distinct company usernames — see [Testing distinct companies](#testing-distinct-companies).

An entity can only be authenticated on one connection at a time. Using the same base username across connections maps to the same underlying company — entities already connected under that company will not be available on new connections.

<Info>
  Additional technical detail on multi-entity testing behavior is available in the [Finch Help Center](https://support.tryfinch.com/articles/8146190155-how-multi-entity-works), accessible to current customers on any Finch plan.
</Info>

## Testing distinct companies

To test multiple distinct companies with the same provider, append a number to the base username when creating each connection:

| Username      | Result         |
| ------------- | -------------- |
| `good_user`   | First company  |
| `good_user_1` | Second company |
| `good_user_2` | Third company  |

Each numbered username generates a unique company with its own ID and data set. This mirrors production behavior — the username an employer uses to authenticate determines which company Finch connects to. Two connections authenticated with the same username will always map to the same company for that provider.

## Configuring sandbox data

Each sandbox connection is pre-populated with 20 randomly generated employees, corresponding `employment` and `individual` records, and one company payment dated to the current date with one pay statement per full-time employee.

Use the `/sandbox` endpoints to modify connection data:

* [`PUT /sandbox/company`](/api-reference/sandbox/update-sandbox-company) — modify company data
* [`POST /sandbox/directory`](/api-reference/sandbox/create-sandbox-employee) — add individuals
* [`PUT /sandbox/employment/{individual_id}`](/api-reference/sandbox/update-sandbox-individual) — modify employment data
* [`PUT /sandbox/individual/{individual_id}`](/api-reference/sandbox/update-sandbox-employment) — modify individual data
* [`POST /sandbox/payment`](/api-reference/sandbox/create-sandbox-payment) — add a payment
* [`PUT /sandbox/connections/accounts`](/api-reference/sandbox/update-sandbox-account) — modify connection status

<Note>
  After modifying data, run a [refresh data sync](/api-reference/sandbox/refresh-job) to see changes reflected in `/employer` API responses. Data syncs do not run automatically in the Finch Sandbox.
</Note>

## Testing job failures

Use the sandbox to test how your application handles asynchronous job failures before encountering them in production. This applies to [data syncs](/developer-resources/Data-Syncs) and [write-back operations](/implementation-guide/API-Calls/Write-Data) such as deductions enrollments.

Use [Configure Sandbox Job](/api-reference/sandbox/update-sandbox-jobs-configuration) to set the expected `completion_status` for a job type, then trigger it with [Enqueue a New Sandbox Job](/api-reference/sandbox/refresh-job). Verify your application handles the failure response correctly. Job configurations persist until you explicitly change them.

## Testing webhooks

The Finch Sandbox fires webhook events for sandbox connections the same way it does in production. See [Webhooks](/developer-resources/Webhooks) for the full list of events and payload shapes.

To receive webhook events, set up a webhook endpoint in the [Finch Dashboard](https://dashboard.tryfinch.com) under the **Webhooks** tab for the Sandbox application/environment.

<Note>
  If the Webhooks tab is not visible, confirm you have an Editor or Admin role in the dashboard — any Admin member can update your role. If you have the correct role and still don't see the tab, contact [developers@tryfinch.com](mailto:developers@tryfinch.com) with your `client_id` to request that webhooks be enabled.
</Note>

## Testing assisted integrations

Organization and Payroll endpoints behave the same way in sandbox regardless of integration type. Some Deductions endpoints are only available for automated integrations.

When an sandbox connection is created for an **automated integrations**, the connection is active immediately.

Assisted integration connections start in a `pending` state in sandbox, reflecting the manual processing they require in production. To simulate a full assisted integration:

1. Create a connection using any of the [three methods](#creating-a-sandbox-connection), following the assisted setup for each method in the table above.
2. The connection status starts as `pending`. For connections that are assisted for deductions and automated for organization and payroll, the organization and payroll statuses will be connected. If you do not complete the following steps within 3 days, the pending status will change to \`Error No Account Setup", which matches behavior in production.
3. Call [Update a sandbox account](/api-reference/sandbox/update-sandbox-account) to set the status to `connected`.
4. Call any `/employer` endpoint to retrieve data for the connection.
5. Use the `/sandbox` endpoints to [configure connection data](#configuring-sandbox-data). Run a refresh data sync after each change.

<Note>
  The `manual` parameter defaults to `false`, which excludes assisted integrations from the Finch Connect provider list. Set `manual=true` and `sandbox=finch` in your [session](/implementation-guide/Connect/Set-Up-Finch-Connect#session-configuration) to include them.
</Note>

## Testing deductions

<Note>
  Some integrations are automated for Organization and Payroll but assisted for Deductions. To test this scenario, create a connection using the assisted setup above, then follow the assisted path in step 1 below.
</Note>

1. Get a `benefit_id`:
   * **Automated** — Call Get All Deductions or Create Deduction. Get All Deductions returns the `benefit_id` directly with no job to track.
   * **Assisted** — Call Create Deduction or Register Deduction. This returns a `job_id` — call [Retrieve a Manual Job](/api-reference/management/retrieve-a-manual-job) and confirm the status is `complete` before continuing.
2. Call Enroll Individuals in Deduction with the `benefit_id`. This returns a `job_id`.
3. Call [Retrieve a Manual Job](/api-reference/management/retrieve-a-manual-job) with the `job_id` to verify enrollment status and result codes.

<Note>
  In the Finch Sandbox, benefits created through the deductions endpoints do not appear on pay statements. To add specific benefits to pay statements, use the [sandbox payment endpoints](/api-reference/sandbox/create-sandbox-payment) when configuring sandbox data.
</Note>

## Connection limits

The Finch Sandbox supports up to 100 connections. Disconnected and staged connections do not count toward the limit.

There is no disconnect option in the Finch Dashboard UI. Use the [Disconnect endpoint](/api-reference/management/disconnect) to disconnect a connection. Store your access tokens so you can disconnect connections when testing is complete.

## Rate limits

* API rate limits are doubled compared to production.
* Sandbox connections allow 10 [refresh data syncs](/api-reference/management/refresh-job) per hour (production allows 1).

***

## Checkpoint + Next Step

<Check>
  After completing this step, you can simulate the employment scenarios your application will encounter with live employers. Once your integration is ready, move on to [testing with provider demo accounts](/implementation-guide/Test/Provider-Sandboxes).
</Check>

## Learn more

* [Quickstart](/how-finch-works/quickstart)
* [Set Up Finch Connect](/implementation-guide/Connect/Set-Up-Finch-Connect)
* [Finch Sandbox — Advanced Testing](https://support.tryfinch.com/articles/8148933505-finch-sandbox-general-best-practices)