Use the Finch Directory endpoint to retrieve each individual's department and manager relationship and reconstruct employee reporting lines for an org-chart integration.
domain: developer.tryfinch.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Run Finch Connect for the employer requesting the 'directory' product scope specifically (distinct from the 'company', 'individual', or 'employment' scopes) so the resulting token can read directory data.
Exchange the Finch Connect authorization code for an access token.
Call GET https://api.tryfinch.com/employer/directory with header Authorization: Bearer <access token> and the required Finch-API-Version header (date-formatted, current version 2020-09-17).
Page through the individuals array using the limit and offset query parameters; each record includes id, first_name, last_name, is_active, a department object (name), and a manager object (manager's Finch id).
For multi-entity employers, pass entity_ids (exactly one UUID) to scope the request to a single legal entity.
Join each individual's manager.id back to another individual's id in the same response set to reconstruct reporting lines, since Directory exposes manager relationships rather than a nested org tree.
Known gotchas
The Directory response only nests a department name per individual, not a parent/child department hierarchy — use the separate Company endpoint's departments[].parent structure if you need department-level (not person-level) hierarchy.
If the initial data sync hasn't completed, Finch returns HTTP 202 with finch_code data_sync_in_progress or pending instead of data — treat this as 'retry later', not an error.
manager can be null for top-level employees or when the source HRIS doesn't expose a manager relationship, so don't assume every individual resolves to a manager id.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?