Finch API Rate Limits: Technical Guide

Overview

Finch enforces application-level rate limits per minute. Batch endpoints (10,000 individual_ids, 10 payment_ids) and webhook-driven fetches keep you under them. Please see Rate Limits for information about IP Level Rate Limits.

How Finch Data Syncing Works

Critical context: Finch syncs data from providers once every 24 hours per connection. The 24-hour timer starts after a sync completes (not when it begins). Sync duration varies from seconds to hours depending on company size, provider, and data type.

Implication: Calling the API more than once per day for the same connection returns identical data. There is no benefit to more frequent polling.

Webhook notification: job.data_sync_all.completed notifies you when fresh data is available.

How Batch Requests Affect Rate Limits

Several Finch endpoints (/individual, /employment, and /pay-statement ) are batch endpoints. You send multiple IDs in one request and receive one response containing an array of results. Rate limits count HTTP requests, not IDs: a request carrying many IDs counts once against your per-minute limit, so batching keeps the request volume per connection low. For a connection up to 10,000 individuals, that's one /individual and one /employment request each time you fetch the connection's data.

/pay-statement batches by payment_id (one payroll run), and each payment returns the pay statements for the individuals paid in that run; company size does not change the request count. Once a payment's pay date has passed, its pay statement data does not change, so fetch each payment_id only once: the historical backfill is a one-time set of requests, and steady state is only the new payments as they occur.

How often you fetch depends on your use case. Some applications fetch daily, others weekly or monthly. Finch does not sync all connections at the same time. For most providers, provider data syncs are spread throughout the day across your connections rather than completing all at once. If you listen for webhooks, the job.data_sync_all.completed events arrive throughout the day, so your fetches are naturally distributed and stay under the limits. If you don't use webhooks, avoid rate limit errors by scheduling cron jobs that spread your fetches over a longer window rather than fetching from every connection at the same time. Fetching all connections in one window or not batching are the most common causes of rate limit errors.

For request structure, limits, and batch error handling, see Batch Requests.

Rate Limit Math by Scale

The tables below show utilization of rate limits and total time to sync all your connections at the rate limit. If your contracted connection count pushes your utilization or total time above your use case requirements, reach out to your Developer Success Engineer to discuss adjusting your rate limits.

company and directory endpoints (20 requests/min)

Not batch endpoints: one request per connection.

individual and employment endpoints (20 requests/min)

Batch endpoints capped at 10,000 individual_ids. Make multiple requests per connection when company size exceeds 10,000 individuals.

payment and pay-groups (12 requests/min)

Not batch endpoints: one request per connection.

pay-statement: single pay run (12 requests/min)

One payment per connection, the normal case, a single pay run per data sync. The math is identical to the payment and pay-groups table above.

pay-statement: historical backfill, per connection (12 requests/min)

An application runs a historical backfill once, when a connection is first created. This table shows calculations for an application fetching the complete default 24-month look back period that Finch syncs from the provider on the first data sync. Most applications add only a few connections per day, so backfills rarely overlap; even a 1,000-connection contract won't backfill 1,000 connections on the same day. The times below are per connection. /pay-statement accepts batches up to 10 payment_ids per request, so a connection's payments are split into requests of 10, which the times below reflect.

Implementation Patterns

Webhook-Driven (Recommended)

Subscribe to job.data_sync_all.completed webhooks. When a webhook arrives, queue that connection for processing. Process the queue in parallel while respecting rate limits.

Staggered Cron Jobs

Divide connections into time-based batches. Process batches throughout the day or within specific windows. Use queue-based processing with rate limit awareness.

Paginating Pay Statements for Large Companies

Most companies have fewer than 500 employees, so a single /pay-statement request returns a payment's pay statements in one response. For a large company, send a single payment_id per request and paginate its individuals; batching multiple payment_ids is only useful when each payment has a small number of individuals.

Pagination and rate limits are separate things. Pagination is how you retrieve a result set that's too large for one response; the rate limit caps how many requests you can make per minute. Each paginated request is an ordinary HTTP request that counts against your per-minute limit, so a large company just spends more of that budget. There is no separate "pagination limit."

The table below shows the request volume for a single large payment. The counts are per payment, so for a historical backfill you multiply by the number of payments. Page size is a value you control; paging in larger or smaller chunks scales the request count inversely.

Single payment (12 requests/min, 100 individuals per request)

How Pay Statement Pagination Works

/pay-statement accepts multiple payment_ids in one request, but pagination applies separately to each payment. You page through a single payment sequentially, since each page tells you whether more records remain. Across different connections and payments, you can paginate in parallel until you approach the rate limit.

Troubleshooting Slow Syncs

"My system takes 4 hours to sync 4,000 connections"

Math check: 4,000 calls at 20/min = 200 minutes = 3.3 hours. Rate limits alone can't account for more than that, so if a sync takes longer, the bottleneck is your architecture, not rate limits.

Common causes:

• Sequential processing: making one call, processing it, then the next (not parallelized)

• Synchronous database writes: blocking on DB operations before the next request

• No connection pooling: creating a new HTTP connection per request

• Inefficient data transformation: heavy processing in the request path

How to identify: time each request end to end (network + processing + database). If total time per request exceeds 2 seconds, you need parallel processing.

Fix: implement parallel processing (10–20 concurrent requests), async database operations, and webhook-driven architecture.

Testing Rate Limits in Sandbox

Sandbox limit: 100 connections per application. You don't need thousands of connections to test rate limiting:

Option 1: Large employee datasets. Standard is 20 employees per connection; extended is up to 10,000 employees (requires approval from developers@tryfinch.com). 10 connections × 50 paginated requests (5,000 employees ÷ 100 per page) = 500 API calls. See Testing Large Datasets Guide.

Option 2: Small page sizes. Use smaller page sizes to force pagination with standard sandbox datasets. For example, 100 employees with limit=5 creates 20 pages per connection. With 100 connections, that's 2,000 paginated requests to test your rate limiting logic.

Option 3: Concurrent processing. Process all 100 sandbox connections in parallel to test queue management and rate limiting.

Option 4: Intentional rate limit triggering. Make rapid concurrent requests to the same endpoint to trigger 429 responses. Validate your retry logic and exponential backoff handling.

FAQ

Can we request higher rate limits?

Yes, if you have several thousand connections and have already implemented webhook-driven or queue-based architecture, enabled parallel processing, and optimized your data pipeline. Contact your Developer Success Engineer with your current connection count and architecture, the rate limit errors you're experiencing, and how you've optimized your system.

We only sync weekly/monthly. Do rate limits matter?

No. Weekly, 10,000 connections average 1 call/min (5% of limit); monthly, 10,000 connections average 0.23 calls/min (1% of limit).

What if many employers connect simultaneously through Finch Connect?

Extremely unlikely. Employer authentication happens organically across business hours and days, rarely exceeding 10–20 connections per minute even during peak onboarding. Initial syncs run automatically, and you pull data after receiving the job.data_sync_all.completed webhook, by which point connections are distributed over time. With webhook-driven architecture this is never an issue.

Should I implement rate limiting in my code?

Yes. Implement request queuing with a controlled processing rate, retry logic with exponential backoff for 429 responses, monitoring of API calls per minute, and circuit breakers for consistent limit hits. This makes your integration resilient to growth and edge cases.

Summary

Finch's rate limits accommodate standard integration patterns because data only refreshes once per 24 hours. Properly designed systems operate well below the limits: webhook-driven fetches distribute naturally across 24 hours, 10,000 connections average about 7 calls/minute (35% utilization), and pagination processing time naturally spaces requests. Rate limits become a constraint only when you batch all requests simultaneously instead of distributing them.

For questions or custom rate limit discussions, contact support or your Developer Success Engineer.