---
title: "Find employee"
method: POST
path: "/v1/employees/find"
tags: ["Employees"]
---

# Find employee

`POST /v1/employees/find`

## Request

- Base URL: `https://api.clients.wellhub.com`
- URL: `https://api.clients.wellhub.com/v1/employees/find`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wellhub/apis/integrations-api/docs/v1/employees/find/post.ts> (a function with typed inputs; its response is checked against the schema)

Finds a single employee belonging to the authenticated single-entity client, by Eligibility Identifier.

## Request body

- FindEmployeeRequest
  - `identifier` string, required: The employee's Eligibility Identifier value, in the format configured for the company. Must match exactly what was submitted at ingestion — no normalization is applied. For a company configured with **Employee ID and National ID**, send only the `employee_id` value; omit `national_id` entirely.

## Response `200`

OK. Returns the matching employee.

- FindEmployeeResult: The employee matched by the given identifier.
  - `id` string: Internal Wellhub identifier for the employee.
  - `full_name` string: Employee's full name.
  - `email` string: Employee's email address.
  - `employee_id` string: Client-defined employee identifier.
  - `national_id` string: Employee's national identifier (e.g. CPF in Brazil).
  - `invitation_status` string: Current invitation status for the employee on the Wellhub platform.
  - `cost_center` string: Cost center associated with the employee.
  - `department` string: Department the employee belongs to.
  - `office_zip_code` string: ZIP code of the employee's office location.
  - `payroll_id` string: Payroll identifier for the employee.
  - `discount_subset_id` string, nullable: Identifier for the discount subset applicable to this employee, if any.
  - `employee_segment` string, nullable: Identifies the employee's segment for NR01, if set.
  - `eligible_to_payroll` boolean: Whether the employee is eligible for payroll deduction.
  - `deleted_at` string, date-time, nullable: Timestamp when the employee record was soft-deleted. `null` if active.
  - `updated_at` string, date-time: Timestamp of the last update to this employee record.

## Other responses

- `400`: Bad Request. The identifier is missing, blank, or rejected by the eligibility service for the company's configured identifier type.
- `401`: Unauthorized. Missing or invalid Bearer token.
- `403`: Forbidden. Either the credential lacks the required scope (standard `{"error":...}` body), or the request was rejected by payload security screening for a SQL-injection/XSS/control-character pattern anywhere in the body — in which case the body is `{"message":"Forbidden"}`, mimicking a WAF response.
- `404`: Not Found. No employee matches the given identifier.
- `413`: Content Too Large. Request body exceeds the 1 MB limit.
- `500`: Internal Server Error.
- `502`: Bad Gateway. The upstream eligibility service failed.

---

[API](https://skmtc.dev/wellhub/apis/integrations-api.md) - [All operations](https://skmtc.dev/wellhub/apis/integrations-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wellhub/apis/integrations-api/revisions/3e6a46a18a2e?raw)