---
title: "Directory"
method: GET
path: "/employer/directory"
tags: ["Organization"]
---

# Directory

`GET /employer/directory`

Read company directory and organization structure

## Query parameters

- `entity_ids` string[]
- `limit` integer
- `offset` integer

## Headers

- `Finch-API-Version` string, date, required

## Response `200`

Company directory and organization structure

- GetDirectoryResponse
  - `paging` Paging, required
    - `count` integer — The total number of elements for the entire query (not just the given page)
    - `offset` integer, required — The current start index of the returned list of elements
  - `individuals` object[], required — The array of employees.
    - `id` string, uuid, required — A stable Finch `id` (UUID v4) for an individual in the company.
    - `first_name` string, nullable, required — The legal first name of the individual.
    - `middle_name` string, nullable, required — The legal middle name of the individual.
    - `last_name` string, nullable, required — The legal last name of the individual.
    - `manager` object, nullable, required — The manager object.
      - `id` string, uuid, required — A stable Finch `id` (UUID v4) for an individual in the company.
    - `department` object, nullable, required — The department object.
      - `name` string, nullable — The name of the department.
    - `is_active` boolean, nullable, required — `true` if the individual is an active employee or contractor at the company.

## Other responses

- `202` — The request has been accepted for processing, but data is not yet available
- `422` — The request could not be processed due to a validation error

## Changes

> 53 revisions in range; 3 could not be searched.

- **2026-07-13** `09682ea25ac9` — 1 breaking, 1 warning, 1 info
  - for the `query` request parameter `limit`, default value `100` was added
  - for the `query` request parameter `limit`, the max was set to `10000.00`
  - added the non-success response with the status `422`
- **2025-10-27** `0105d239fcaf` — 1 info
  - added the new optional `query` request parameter `entity_ids`
- **2025-05-08** `f09e5f2c555d` — 10 info
  - the response property `individuals/items/department` became required for the status `200`
  - the response property `individuals/items/first_name` became required for the status `200`
  - the response property `individuals/items/id` became required for the status `200`
  - the response property `individuals/items/is_active` became required for the status `200`
  - …6 more
- **2025-04-22** `46640c1b4688` — 1 info
  - the endpoint scheme security `bearerAuth` was added to the API

[Change history](https://skmtc.dev/finch-api/apis/api-reference/changes/employer/directory/get.md)

---

[API](https://skmtc.dev/finch-api/apis/api-reference.md) · [All operations](https://skmtc.dev/finch-api/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/finch-api/api-reference/revisions/f1cca2cb0ef2/schema)