​
Initial Data Syncs

After an employer connects through Finch Connect, Finch automatically initiates an initial sync to retrieve available data across supported endpoints.

Effective June 11, 2025 Finch will fetch the following for Pay data:

  • 2 full years of historical data
  • Year-to-date for the current calendar year

Example: If an employer connects on June 1, 2025, Finch will sync data starting from January 1, 2023. If am employer connects on January 2, 2026, Finch will sync data starting from January 1, 2024.

Finch defaults to a 2-year plus year-to-date lookback to ensure fast, reliable first-time syncs. Longer lookbacks are available on our Premier plan but may increase the risk of time-outs. To request a custom lookback, contact developers@tryfinch.com.

Finch will fetch Organization data going as far back as is available in the payroll system.

​
Provider limitations

Some providers restrict how much historical data is available.

  • Paychex Flex: up to 14 months of pay statement data
  • Paycom: up to 2 years of pay statement data

If a request is made before the initial sync is complete, Finch will attempt a live fetch from the provider. These requests may take longer, depending on the size and structure of the data.

​
Ongoing data syncs

After the initial sync, Finch keeps data fresh by syncing on the following schedule:

Finch API responses always return the most recent successful sync. Most requests complete in under 200 milliseconds.

​
Verify data freshness

Finch includes response headers that indicate the freshness of the data:

Response HeaderDescription
Finch-Data-RetrievedThe date/time that the data was retrieved from the employment system.
Finch-Last-Attempted-Update-DateThe date/time that Finch last attempted to sync the data for this endpoint.

​
Batch sync behavior

For batch endpoints like /employment, /individual, and /pay-statement, Finch syncs all records in a single operation. This ensures that all data returned in the response reflects the same point in time.

​
Pay statement sync behavior

Pay statements are larger and may take longer to sync than other data types. If you query a pay statement using a payment_id from the /payment endpoint before it has been fetched, Finch will return a 202 Accepted status with the following response:

{
  "responses": [
    {
      "payment_id": "9c8626e3-6d97-48a0-883c-f4c65e736321",
      "code": 202,
      "body": {
        "code": 202,
        "name": "accepted",
        "finch_code": "data_sync_in_progress",
        "message": "The pay statements for this payment are being fetched. Please check back later."
      }
    },
    ...
  ]
}