> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # /employees GET https://api.merge.dev/api/hris/v1/employees Returns a list of `Employee` objects.{/* BEGIN_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} Reference: https://docs.merge.dev/merge-unified/hris/common-models/employees/list ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: hris_v2 version: 1.0.0 paths: /hris/v1/employees: get: operationId: list summary: List description: >- Returns a list of `Employee` objects.{/* BEGIN_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */}{/* END_HRIS_EMPLOYEE_FETCH_SUPPORTED_FIELDS */} tags: - employees parameters: - name: company_id in: query description: If provided, will only return employees for this company. required: false schema: type: string - name: created_after in: query description: If provided, will only return objects created after this datetime. required: false schema: type: string format: date-time - name: created_before in: query description: If provided, will only return objects created before this datetime. required: false schema: type: string format: date-time - name: cursor in: query description: The pagination cursor value. required: false schema: type: string - name: display_full_name in: query description: If provided, will only return employees with this display name. required: false schema: type: string - name: employee_number in: query description: If provided, will only return employees with this employee number. required: false schema: type: string - name: employment_status in: query description: |+ If provided, will only return employees with this employment status. required: false schema: $ref: '#/components/schemas/EmployeesGetParametersEmploymentStatus' - name: employment_type in: query description: >- If provided, will only return employees that have an employment of the specified employment type. required: false schema: type: string - name: expand in: query description: >- Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces. required: false schema: type: array items: $ref: '#/components/schemas/EmployeesGetParametersExpandSchemaItems' - name: first_name in: query description: If provided, will only return employees with this first name. required: false schema: type: string - name: groups in: query description: >- If provided, will only return employees matching the group ids; multiple groups can be separated by commas. required: false schema: type: string - name: home_location_id in: query description: If provided, will only return employees for this home location. required: false schema: type: string - name: include_deleted_data in: query description: >- Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). required: false schema: type: boolean - name: include_remote_data in: query description: >- Whether to include the original data Merge fetched from the third-party to produce these models. required: false schema: type: boolean - name: include_sensitive_fields in: query description: >- Whether to include sensitive fields (such as social security numbers) in the response. required: false schema: type: boolean - name: include_shell_data in: query description: >- Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null). required: false schema: type: boolean - name: job_title in: query description: >- If provided, will only return employees that have an employment of the specified job title. required: false schema: type: string - name: last_name in: query description: If provided, will only return employees with this last name. required: false schema: type: string - name: manager_id in: query description: If provided, will only return employees for this manager. required: false schema: type: string - name: modified_after in: query description: >- If provided, only objects synced by Merge after this date time will be returned. required: false schema: type: string format: date-time - name: modified_before in: query description: >- If provided, only objects synced by Merge before this date time will be returned. required: false schema: type: string format: date-time - name: page_size in: query description: Number of results to return per page. The maximum limit is 100. required: false schema: type: integer - name: pay_group_id in: query description: If provided, will only return employees for this pay group required: false schema: type: string - name: personal_email in: query description: If provided, will only return Employees with this personal email required: false schema: type: string - name: remote_fields in: query description: Deprecated. Use show_enum_origins. required: false schema: $ref: '#/components/schemas/EmployeesGetParametersRemoteFields' - name: remote_id in: query description: The API provider's ID for the given object. required: false schema: type: string - name: show_enum_origins in: query description: >- A comma separated list of enum field names for which you'd like the original values to be returned, instead of Merge's normalized enum values. [Learn more](https://help.merge.dev/en/articles/8950958-show_enum_origins-query-parameter) required: false schema: $ref: '#/components/schemas/EmployeesGetParametersShowEnumOrigins' - name: started_after in: query description: >- If provided, will only return employees that started after this datetime. required: false schema: type: string format: date-time - name: started_before in: query description: >- If provided, will only return employees that started before this datetime. required: false schema: type: string format: date-time - name: team_id in: query description: If provided, will only return employees for this team. required: false schema: type: string - name: terminated_after in: query description: >- If provided, will only return employees that were terminated after this datetime. required: false schema: type: string format: date-time - name: terminated_before in: query description: >- If provided, will only return employees that were terminated before this datetime. required: false schema: type: string format: date-time - name: work_email in: query description: If provided, will only return Employees with this work email required: false schema: type: string - name: work_location_id in: query description: If provided, will only return employees for this location. required: false schema: type: string - name: Authorization in: header description: Token-based authentication with required prefix "Bearer" required: true schema: type: string - name: X-Account-Token in: header description: Token identifying the end user. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PaginatedEmployeeList' servers: - url: https://api.merge.dev/api description: Production - url: https://api-eu.merge.dev/api description: ProductionEU - url: https://api-ap.merge.dev/api description: ProductionAPSE1 components: schemas: EmployeesGetParametersEmploymentStatus: type: string enum: - ACTIVE - INACTIVE - PENDING title: EmployeesGetParametersEmploymentStatus EmployeesGetParametersExpandSchemaItems: type: string enum: - company - employments - groups - home_location - manager - pay_group - team - work_location title: EmployeesGetParametersExpandSchemaItems EmployeesGetParametersRemoteFields: type: string enum: - employment_status - employment_status,ethnicity - employment_status,ethnicity,gender - employment_status,ethnicity,gender,marital_status - employment_status,ethnicity,marital_status - employment_status,gender - employment_status,gender,marital_status - employment_status,marital_status - ethnicity - ethnicity,gender - ethnicity,gender,marital_status - ethnicity,marital_status - gender - gender,marital_status - marital_status title: EmployeesGetParametersRemoteFields EmployeesGetParametersShowEnumOrigins: type: string enum: - employment_status - employment_status,ethnicity - employment_status,ethnicity,gender - employment_status,ethnicity,gender,marital_status - employment_status,ethnicity,marital_status - employment_status,gender - employment_status,gender,marital_status - employment_status,marital_status - ethnicity - ethnicity,gender - ethnicity,gender,marital_status - ethnicity,marital_status - gender - gender,marital_status - marital_status title: EmployeesGetParametersShowEnumOrigins GenderEnum: type: string enum: - MALE - FEMALE - NON-BINARY - OTHER - PREFER_NOT_TO_DISCLOSE title: GenderEnum EthnicityEnum: type: string enum: - AMERICAN_INDIAN_OR_ALASKA_NATIVE - ASIAN_OR_INDIAN_SUBCONTINENT - BLACK_OR_AFRICAN_AMERICAN - HISPANIC_OR_LATINO - NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER - TWO_OR_MORE_RACES - WHITE - PREFER_NOT_TO_DISCLOSE title: EthnicityEnum MaritalStatusEnum: type: string enum: - SINGLE - MARRIED_FILING_JOINTLY - MARRIED_FILING_SEPARATELY - HEAD_OF_HOUSEHOLD - QUALIFYING_WIDOW_OR_WIDOWER_WITH_DEPENDENT_CHILD title: MaritalStatusEnum EmploymentStatusEnum: type: string enum: - ACTIVE - PENDING - INACTIVE title: EmploymentStatusEnum EmployeeFieldMappings: type: object properties: organization_defined_targets: type: object additionalProperties: description: Any type linked_account_defined_targets: type: object additionalProperties: description: Any type title: EmployeeFieldMappings RemoteData: type: object properties: path: type: string description: The third-party API path that is being called. data: description: >- The data returned from the third-party for this object in its original, unnormalized format. required: - path description: >- # The RemoteData Object ### Description The `RemoteData` object is used to represent the full data pulled from the third-party API for an object. ### Usage Example TODO title: RemoteData Employee: type: object properties: id: type: string format: uuid remote_id: type: - string - 'null' description: The third-party API ID of the matching object. created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. employee_number: type: - string - 'null' description: >- The employee's number that appears in the third-party integration's UI. company: type: - string - 'null' format: uuid description: The ID of the employee's company. first_name: type: - string - 'null' description: The employee's first name. last_name: type: - string - 'null' description: The employee's last name. preferred_name: type: - string - 'null' description: The employee's preferred first name. display_full_name: type: - string - 'null' description: >- The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name. username: type: - string - 'null' description: The employee's username that appears in the remote UI. groups: type: array items: type: string format: uuid work_email: type: - string - 'null' format: email description: The employee's work email. personal_email: type: - string - 'null' format: email description: The employee's personal email. mobile_phone_number: type: - string - 'null' description: The employee's mobile phone number. employments: type: array items: type: string format: uuid description: Array of `Employment` IDs for this Employee. home_location: type: - string - 'null' format: uuid description: The employee's home address. work_location: type: - string - 'null' format: uuid description: The employee's work address. manager: type: - string - 'null' format: uuid description: The employee ID of the employee's manager. team: type: - string - 'null' format: uuid description: The employee's team. pay_group: type: - string - 'null' format: uuid description: The employee's pay group ssn: type: - string - 'null' description: The employee's social security number. gender: oneOf: - $ref: '#/components/schemas/GenderEnum' - type: 'null' description: The employee's gender. ethnicity: oneOf: - $ref: '#/components/schemas/EthnicityEnum' - type: 'null' description: The employee's ethnicity. marital_status: oneOf: - $ref: '#/components/schemas/MaritalStatusEnum' - type: 'null' description: The employee's filing status as related to marital status. date_of_birth: type: - string - 'null' format: date-time description: The employee's date of birth. hire_date: type: - string - 'null' format: date-time description: >- The date that the employee was hired, usually the day that an offer letter is signed. If an employee has multiple hire dates from previous employments, this represents the most recent hire date. Note: If you're looking for the employee's start date, refer to the start_date field. start_date: type: - string - 'null' format: date-time description: >- The date that the employee started working. If an employee was rehired, the most recent start date will be returned. remote_created_at: type: - string - 'null' format: date-time description: When the third party's employee was created. employment_status: oneOf: - $ref: '#/components/schemas/EmploymentStatusEnum' - type: 'null' description: The employment status of the employee. termination_date: type: - string - 'null' format: date-time description: The employee's termination date. avatar: type: - string - 'null' format: uri description: The URL of the employee's avatar image. employee_url: type: - string - 'null' format: uri description: The 3rd party URL of the employee. custom_fields: type: - object - 'null' additionalProperties: description: Any type description: Custom fields configured for a given model. remote_was_deleted: type: boolean description: >- Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). field_mappings: oneOf: - $ref: '#/components/schemas/EmployeeFieldMappings' - type: 'null' remote_data: type: - array - 'null' items: $ref: '#/components/schemas/RemoteData' description: >- # The Employee Object ### Description The `Employee` object is used to represent any person who has been employed by a company. By default, it returns all employees. To filter for only active employees, set the `employment_status` query parameter to `ACTIVE`. ### Usage Example Fetch from the `LIST Employee` endpoint and filter by `ID` to show all employees. title: Employee PaginatedEmployeeList: type: object properties: next: type: - string - 'null' previous: type: - string - 'null' results: type: array items: $ref: '#/components/schemas/Employee' title: PaginatedEmployeeList securitySchemes: tokenAuth: type: http scheme: bearer description: Token-based authentication with required prefix "Bearer" ``` ## Examples **Response** ```json { "next": "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw", "previous": "cj1sZXdwd2VycWVtY29zZnNkc2NzUWxNMEUxTXk0ME16UXpNallsTWtJ", "results": [ { "id": "0958cbc6-6040-430a-848e-aafacbadf4ae", "remote_id": "19202938", "created_at": "2021-09-15T00:00:00Z", "modified_at": "2021-10-16T00:00:00Z", "employee_number": "2", "company": "8d9fd929-436c-4fd4-a48b-0c61f68d6178", "first_name": "Greg", "last_name": "Hirsch", "preferred_name": "Greg the egg", "display_full_name": "Cousin Greg Hirsch", "username": "cousingreg", "groups": [ "21a54124-397f-494d-985e-3c5b330b8a68" ], "work_email": "greg@merge.dev", "personal_email": "greg@gmail.com", "mobile_phone_number": "+1234567890", "employments": [ "17a54124-287f-494d-965e-3c5b330c9a68" ], "home_location": "d2f972d0-2526-434b-9409-4c3b468e08f0", "work_location": "9efbc633-3387-4306-aa55-e2c635e6bb4f", "manager": "0048ea5b-911e-4dff-9364-92070dea62ff", "pay_group": "ad1264e2-39be-4787-b749-f1aade9e3405", "ssn": "1234567890", "gender": "MALE", "ethnicity": "WHITE", "marital_status": "SINGLE", "date_of_birth": "1990-11-10T00:00:00Z", "start_date": "2020-10-11T00:00:00Z", "remote_created_at": "2020-10-11T00:00:00Z", "employment_status": "INACTIVE", "termination_date": "2021-10-12T00:00:00Z", "avatar": "http://alturl.com/h2h8m", "employee_url": "https://www.workday.com/wday/v2/employee/19202938", "custom_fields": {}, "remote_was_deleted": true, "field_mappings": { "organization_defined_targets": { "custom_key": "custom_value" }, "linked_account_defined_targets": { "custom_key": "custom_value" } }, "remote_data": [ { "path": "/people", "data": null } ], "team": "string", "hire_date": "2020-10-10T00:00:00Z" } ] } ``` **SDK Code** ```python import requests url = "https://api.merge.dev/api/hris/v1/employees" querystring = {"company_id":"company_id","cursor":"cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw","expand":"company","home_location_id":"home_location_id","manager_id":"manager_id","pay_group_id":"pay_group_id","remote_fields":"employment_status,ethnicity,gender,marital_status","show_enum_origins":"employment_status,ethnicity,gender,marital_status","team_id":"team_id","work_location_id":"work_location_id"} headers = { "X-Account-Token": "X-Account-Token", "Authorization": "Bearer " } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id'; const options = { method: 'GET', headers: {'X-Account-Token': 'X-Account-Token', Authorization: 'Bearer '} }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-Account-Token", "X-Account-Token") req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-Account-Token"] = 'X-Account-Token' request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id") .header("X-Account-Token", "X-Account-Token") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id', [ 'headers' => [ 'Authorization' => 'Bearer ', 'X-Account-Token' => 'X-Account-Token', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id"); var request = new RestRequest(Method.GET); request.AddHeader("X-Account-Token", "X-Account-Token"); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Account-Token": "X-Account-Token", "Authorization": "Bearer " ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.merge.dev/api/hris/v1/employees?company_id=company_id&cursor=cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw&expand=company&home_location_id=home_location_id&manager_id=manager_id&pay_group_id=pay_group_id&remote_fields=employment_status%2Cethnicity%2Cgender%2Cmarital_status&show_enum_origins=employment_status%2Cethnicity%2Cgender%2Cmarital_status&team_id=team_id&work_location_id=work_location_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```