> ## 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. # Directory > Read company directory and organization structure ## OpenAPI ````yaml get /employer/directory openapi: 3.1.0 info: title: API Reference version: '2020-09-17' contact: {} description: >- The Finch HRIS API provides a unified way to connect to a multitide of HRIS systems. The API requires an access token issued by Finch. By default, Organization and Payroll requests use Finch's [Data Syncs](/developer-resources/Data-Syncs). If a request is made before the initial sync has completed, Finch will request data live from the provider. The latency on live requests may range from seconds to minutes depending on the provider and batch size. For automated integrations, Deductions requests (both read and write) are always made live to the provider. Latencies may range from seconds to minutes depending on the provider and batch size. Employer products are specified by the product parameter, a space-separated list of products that your application requests from an employer authenticating through Finch Connect. Valid product names are— - `company`: Read basic company data - `directory`: Read company directory and organization structure - `individual`: Read individual data, excluding income and employment data - `employment`: Read individual employment and income data - `payment`: Read payroll and contractor related payments by the company - `pay_statement`: Read detailed pay statements for each individual - `benefits`: Create and manage deductions and contributions and enrollment for an employer [![Open in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4?action=collection%2Ffork&collection-url=entityId%3D21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4%26entityType%3Dcollection%26workspaceId%3D1edf19bc-e0a8-41e9-ac55-481a4b50790b) servers: - url: https://api.tryfinch.com description: '' security: [] tags: - name: Organization - name: Payroll - name: Deductions - name: Management - name: Sandbox paths: /employer/directory: get: tags: - Organization summary: Directory description: Read company directory and organization structure operationId: get-directory parameters: - name: entity_ids in: query required: false description: The entity IDs to specify which entities' data to access. schema: type: array items: type: string format: uuid minItems: 1 maxItems: 1 example: - 550e8400-e29b-41d4-a716-446655440000 style: form explode: true - name: limit in: query description: Number of employees to return (defaults to all) required: false schema: type: integer - name: offset in: query description: Index to start from (defaults to 0) required: false schema: type: integer - $ref: '#/components/parameters/API-Version' responses: '200': description: Company directory and organization structure content: application/json: schema: $ref: '#/components/schemas/GetDirectoryResponse' examples: Success: value: paging: count: 25 offset: 10 individuals: - id: 5d0b10a1-a09a-430f-81f1-20be735dc5e9 first_name: Jane middle_name: null last_name: Doe manager: id: c205b3fa-b626-4346-bf0f-ca065ab88d31 department: name: Product is_active: true '202': description: >- The request has been accepted for processing, but data is not yet available content: application/json: schema: $ref: '#/components/schemas/AcceptedResponse' examples: DataSyncInProgress: value: code: 202 name: sync_in_progress finch_code: data_sync_in_progress message: >- The data being requested is being fetched. Please check back later. AuthorizationPending: value: code: 202 name: authorization_pending finch_code: pending message: Authorization to this company's data is pending security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: >- import Finch from '@tryfinch/finch-api'; const client = new Finch({ accessToken: 'My Access Token', }); // Automatically fetches more pages as needed. for await (const individualInDirectory of client.hris.directory.list()) { console.log(individualInDirectory.id); } - lang: Python source: |- from finch import Finch client = Finch( access_token="My Access Token", ) page = client.hris.directory.list() page = page.individuals[0] print(page.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go\"\n\t\"github.com/Finch-API/finch-api-go/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithAccessToken(\"My Access Token\"),\n\t)\n\tpage, err := client.HRIS.Directory.List(context.TODO(), finchgo.HRISDirectoryListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Java source: |- package com.tryfinch.api.example; import com.tryfinch.api.client.FinchClient; import com.tryfinch.api.client.okhttp.FinchOkHttpClient; import com.tryfinch.api.models.HrisDirectoryListPage; import com.tryfinch.api.models.HrisDirectoryListParams; public final class Main { private Main() {} public static void main(String[] args) { FinchClient client = FinchOkHttpClient.builder() .fromEnv() .accessToken("My Access Token") .build(); HrisDirectoryListPage page = client.hris().directory().list(); } } - lang: Kotlin source: |- package com.tryfinch.api.example import com.tryfinch.api.client.FinchClient import com.tryfinch.api.client.okhttp.FinchOkHttpClient import com.tryfinch.api.models.HrisDirectoryListPage import com.tryfinch.api.models.HrisDirectoryListParams fun main() { val client: FinchClient = FinchOkHttpClient.builder() .fromEnv() .accessToken("My Access Token") .build() val page: HrisDirectoryListPage = client.hris().directory().list() } - lang: Ruby source: |- require "finch_api" finch = FinchAPI::Client.new(access_token: "My Access Token") page = finch.hris.directory.list puts(page) components: parameters: API-Version: name: Finch-API-Version in: header required: true schema: type: string default: '2020-09-17' format: date pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) description: >- Header used to specify the version for a given API request. Current version is 2020-09-17. schemas: GetDirectoryResponse: type: object properties: paging: $ref: '#/components/schemas/Paging' individuals: type: array items: type: object properties: id: type: string description: >- A stable Finch `id` (UUID v4) for an individual in the company. pattern: '[0-9a-fA-F]{8}[-]?(?:[0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12}' format: uuid first_name: type: string description: The legal first name of the individual. nullable: true middle_name: type: string description: The legal middle name of the individual. nullable: true last_name: type: string description: The legal last name of the individual. nullable: true manager: type: object nullable: true properties: id: type: string description: >- A stable Finch `id` (UUID v4) for an individual in the company. pattern: '[0-9a-fA-F]{8}[-]?(?:[0-9a-fA-F]{4}[-]?){3}[0-9a-fA-F]{12}' format: uuid required: - id description: The manager object. department: type: object nullable: true properties: name: type: string nullable: true description: The name of the department. description: The department object. is_active: type: boolean nullable: true description: >- `true` if the individual is an active employee or contractor at the company. required: - id - first_name - middle_name - last_name - manager - department - is_active description: The array of employees. required: - paging - individuals AcceptedResponse: type: object properties: code: type: number default: 202 name: type: string finch_code: type: string message: type: string required: - name - finch_code - message Paging: type: object properties: count: type: integer description: >- The total number of elements for the entire query (not just the given page) offset: type: integer description: The current start index of the returned list of elements required: - offset title: Paging x-tags: - Models securitySchemes: bearerAuth: type: http scheme: bearer description: Please use your Access Token ````