> ## 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.

# Read Organization and Payroll Data

> In this guide, you'll learn how to read data from Finch's company, directory, individual, employment, payment, and pay statement API endpoints.

You can now make API requests to Finch's various endpoints, such as `/company`, `/directory`, `/individual`, `/employment`, `/payment`, and `/pay-statement`. These endpoints only allow the reading of data from employment providers; they do not permit the writing of data back to the system. Writing deductions and contributions back to the provider is covered in [Write Data](/implementation-guide/API-Calls/Write-Data) step.

These calls must be made from your backend using the access token obtained after Finch Connect — see [Backend Security](/implementation-guide/Backend-Application/Backend-Security) for why the access token should never be exposed to your frontend.

In this step, you will learn how to make API requests, handle responses, and manage request rate limits.

1. **Choose the appropriate Finch API endpoints**: Pick the endpoint(s) that match the data your application needs. See [Verify Product Scopes](/implementation-guide/Connect/Create-Account#verify-product-scopes) for what each product/endpoint returns, or [How Finch's API is organized](/how-finch-works/data-model) 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](/api-reference/development-guides/Rate-Limits). See [Batch Requests](/implementation-guide/API-Calls/Batch-Requests) for the request and response format.

3. **Set up the HTTP request**: Use an HTTP library such as [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) or [Axios](https://axios-http.com/docs/intro) (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.

   ```js theme={null}
   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));
   ```

   ```python theme={null}
   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()
   ```

   ```java theme={null}
   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"
}
```

Despite the plural name, the API currently accepts exactly one entity ID per request (`entity_ids[]=<entity_id>`) — to fetch data for multiple entities, make one request per entity.

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](/api-reference/development-guides/Headers#response-headers) for more details. Store or display the data as needed for your application.

   ```json Example response theme={null}
   {
     "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](/api-reference/development-guides/Handling-API-Responses) for why these occur and how to handle each.

6. **Handle errors and edge cases**: Finch returns `4XX` or `5XX` [error types](/api-reference/development-guides/errors/Error-Types) when a request fails, sometimes due to an unsupported response from the underlying employment system. See [Server errors](/implementation-guide/Backend-Application/Mitigate-Errors#server-errors) in Mitigate Errors for a retry-with-backoff implementation and when to contact support with the `Finch-Request-ID`.

7. **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](/implementation-guide/Backend-Application/Mitigate-Errors#reauthentication-errors) in Mitigate Errors for the full flow.

8. **Manage rate limits**: Finch enforces [rate limits](/api-reference/development-guides/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](/implementation-guide/Backend-Application/Mitigate-Errors#rate-limit-errors) in Mitigate Errors for the full model and a retry implementation.

***

<Check>
  ### Checkpoint + Next Step

  After completing this step, your application will be able to interact with the Finch API endpoints, read the necessary data, and handle various error scenarios. If all you need is to read data, the next step is to [batch requests](/implementation-guide/API-Calls/Batch-Requests). If you need the ability to write data back to the provider, follow the [Write Data](/implementation-guide/API-Calls/Write-Data) step. Otherwise, you can move on to [Prepare the Employer Experience](/implementation-guide/Integration-Preparation/Manage-Integrations).
</Check>

## Learn more

* [Handling API Responses](/api-reference/development-guides/Handling-API-Responses)
* [Mitigate Errors](/implementation-guide/Backend-Application/Mitigate-Errors)
* [Monitor Usage](/implementation-guide/Backend-Application/Monitor-Usage)