Read Organization and Payroll Data

1. Choose the appropriate Finch API endpoints: Pick the endpoint(s) that match the data your application needs. See Verify Product Scopes for what each product/endpoint returns, or How Finch’s API is organized for the full data model.
2. Batch your requests: For endpoints that accept multiple IDs — /individual, /employment, /pay-statement — send all the IDs you need in a single call instead of one request per ID. This reduces the number of API calls your application makes and, as a result, helps you stay within your rate limits. See Batch Requests for the request and response format.
3. Set up the HTTP request: Use an HTTP library such as Fetch or Axios (or another suitable package) to create an HTTP request. Include the access token in the Authorization header using the format Bearer <your_access_token>. Make sure the HTTP request uses the appropriate method (GET, POST, etc.) and includes any required parameters.
   const url = 'https://api.tryfinch.com/employer/directory?entity_ids[]=64267987-6213-42d1-af2f-d2aa0614e222'; // Replace with the desired endpoint
   const accessToken = '<your_access_token>';
   
   fetch(url, {
     method: 'GET',
     headers: {
       'Authorization': `Bearer ${accessToken}`,
       'Content-Type': 'application/json',
     },
   })
   .then(response => response.json())
   .then(data => console.log(data))
   .catch(error => console.error('Error:', error));
   
   import requests
   
   def fetch_data_from_endpoint():
       url = 'https://api.tryfinch.com/employer/directory?entity_ids[]=64267987-6213-42d1-af2f-d2aa0614e222'
       access_token = '<your_access_token>'
       
       headers = {
           'Authorization': f'Bearer {access_token}',
           'Content-Type': 'application/json',
       }
       
       try:
           response = requests.get(url, headers=headers)
           response.raise_for_status()
           data = response.json()
           print(data)
       except requests.RequestException as error:
           print(f'Error: {error}')
   
   # Call the function to test
   # fetch_data_from_endpoint()
   
   import java.io.BufferedReader;
   import java.io.InputStreamReader;
   import java.net.HttpURLConnection;
   import java.net.URL;
   
   public class APIClient {
   
       private static final String ENDPOINT_URL = "https://api.tryfinch.com/employer/directory?entity_ids[]=64267987-6213-42d1-af2f-d2aa0614e222";
       private static final String ACCESS_TOKEN = "<your_access_token>";
   
       public static void main(String[] args) {
           fetchFromEndpoint();
       }
   
       public static void fetchFromEndpoint() {
           try {
               URL url = new URL(ENDPOINT_URL);
               HttpURLConnection connection = (HttpURLConnection) url.openConnection();
               connection.setRequestMethod("GET");
               connection.setRequestProperty("Authorization", "Bearer " + ACCESS_TOKEN);
               connection.setRequestProperty("Content-Type", "application/json");
   
               int responseCode = connection.getResponseCode();
               if (responseCode == HttpURLConnection.HTTP_OK) { // success
                   BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
                   String inputLine;
                   StringBuilder response = new StringBuilder();
   
                   while ((inputLine = in.readLine()) != null) {
                       response.append(inputLine);
                   }
                   in.close();
                   System.out.println(response.toString());
               } else {
                   System.out.println("GET request failed. Response code: " + responseCode);
               }
           } catch (Exception e) {
               System.out.println("Error: " + e.getMessage());
           }
       }
   }
   
4. Include entity_ids query parameter in requests: When using an access token associated with multiple entities, you must include the entity_ids query parameter in all API requests. If you do not provide the entity_ids query parameter, Finch will return the following error:

{
  "error": "entity_id_required",
  "message": "Multi-entity connection requires entity_ids query parameter when multiple entities exist"
}

5. Handle API responses: When Finch returns a response, parse the JSON data and extract the relevant information needed for your application. All API responses include a header that includes date the data was retrieved. See our Development Guide on Headers for more details. Store or display the data as needed for your application.
   Example response

   {
     "paging": {
       "count": 15,
       "offset": 0
     },
     "individuals": [
       {
         "id": "01220ee6-d32e-4973-8646-c5a197935535",
         "first_name": "Adrian",
         "middle_name": "Kylo",
         "last_name": "Baumbach",
         "manager": {
           "id": "c0e619df-77b7-481c-8669-210ba2af97ad"
         },
         "department": {
           "name": "Quality"
         },
         "is_active": true
       },
       ...
       {
         "id": "daac88bc-6ade-459b-9630-68ed7bac5ae9",
         "first_name": "Glen",
         "middle_name": "Beckham",
         "last_name": "Blanda",
         "manager": {
           "id": "94917285-773f-4e9f-9018-d919af77c997"
         },
         "department": {
           "name": "Quality"
         },
         "is_active": true
       }
     ]
   }
   
   The id values in a response (like the individual and manager IDs above) stay constant across access tokens generated via the same authentication method. If a connection has multiple access tokens from different authentication methods — for example, one from credentials and another from an API token — those IDs can differ between tokens, since Finch maps its IDs to the underlying employment system’s own identifiers, which vary by authentication method. Responses can include null field values or, for some requests, a 202 status instead of the shape above. See Handling API Responses for why these occur and how to handle each.
6. Paginate GET /directory and POST /pay-statement responses: GET /directory and each entry in a POST /pay-statement request return paginated results using limit and offset. Set limit explicitly — if you omit it, Finch returns only the default page size, not the full result set.

   Endpoint	Default limit	Max limit
   GET /directory	10,000	10,000
   POST /pay-statement (per payment_id)	5,000	5,000

   Loop on offset, adding the number of items received each time, until the response’s paging.count shows there are no more records to fetch:
   async function fetchAllDirectory(accessToken) {
     const individuals = [];
     const limit = 10000;
     let offset = 0;
   
     while (true) {
       const url = `https://api.tryfinch.com/employer/directory?limit=${limit}&offset=${offset}`;
       const response = await fetch(url, {
         headers: { 'Authorization': `Bearer ${accessToken}` },
       });
       const data = await response.json();
       individuals.push(...data.individuals);
   
       if (data.individuals.length < limit) break;
       offset += limit;
     }
   
     return individuals;
   }
   
   A limit above the max returns a 422 with a finch_code of page_size_limit_exceeded. See Mitigate Errors for the error format.
7. Handle errors and edge cases: Finch returns 4XX or 5XX error types when a request fails, sometimes due to an unsupported response from the underlying employment system. See Server errors in Mitigate Errors for a retry-with-backoff implementation and when to contact support with the Finch-Request-ID.
8. Handle 401 re-authentication errors: A 401 response with a finch_code of reauthenticate_user means Finch lost access to the employer’s provider and the employer must reauthenticate. See Reauthentication errors in Mitigate Errors for the full flow.
9. Manage rate limits: Finch enforces rate limits per product on a rolling 60-second basis, for both applications and access tokens. Batching your requests (see step 2 above) is the main way to stay within these limits. If Finch returns a 429 HTTP status code, back off and retry — see Rate limit errors in Mitigate Errors for the full model and a retry implementation.

​

Learn more

• Handling API Responses
• Mitigate Errors
• Monitor Usage