> This page is for Unified.

> 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/{id}

GET https://api.merge.dev/api/hris/v1/employees/{id}

Returns an `Employee` object with the given `id`.

Reference: https://docs.merge.dev/merge-unified/hris/common-models/employees/retrieve

## Authentication

- `Authorization` header (bearer token, required) — Token-based authentication with required prefix "Bearer"

## Servers

- `https://api.merge.dev/api` (Production, default)
- `https://api-eu.merge.dev/api` (ProductionEU)
- `https://api-ap.merge.dev/api` (ProductionAPSE1)

## Request

### Path parameters

- `id` (string, required)

### Query parameters

- `expand` (list of enum, optional) — Which relations should be returned in expanded form. Multiple relation names should be comma separated without spaces.
  - Allowed values: `company`, `employments`, `groups`, `home_location`, `manager`, `pay_group`, `team`, `work_location`
- `include_remote_data` (boolean, optional) — Whether to include the original data Merge fetched from the third-party to produce these models.
- `include_sensitive_fields` (boolean, optional) — Whether to include sensitive fields (such as social security numbers) in the response.
- `include_shell_data` (boolean, optional) — Whether to include shell records. Shell records are empty records (they may contain some metadata but all other fields are null).
- `remote_fields` (enum, optional) — Deprecated. Use show_enum_origins.
  - Allowed values: `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`
- `show_enum_origins` (enum, optional) — 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)
  - Allowed values: `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`

### Headers

- `X-Account-Token` (string, required) — Token identifying the end user.

## Response

### 200

- `id` (string, optional)
- `remote_id` (string, optional, nullable) — The third-party API ID of the matching object.
- `created_at` (datetime, optional) — The datetime that this object was created by Merge.
- `modified_at` (datetime, optional) — The datetime that this object was modified by Merge.
- `employee_number` (string, optional, nullable) — The employee's number that appears in the third-party integration's UI.
- `company` (string, optional, nullable) — The ID of the employee's company.
- `first_name` (string, optional, nullable) — The employee's first name.
- `last_name` (string, optional, nullable) — The employee's last name.
- `preferred_name` (string, optional, nullable) — The employee's preferred first name.
- `display_full_name` (string, optional, nullable) — 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` (string, optional, nullable) — The employee's username that appears in the remote UI.
- `groups` (list of string, optional)
- `work_email` (string, optional, nullable) — The employee's work email.
- `personal_email` (string, optional, nullable) — The employee's personal email.
- `mobile_phone_number` (string, optional, nullable) — The employee's mobile phone number.
- `employments` (list of string, optional) — Array of `Employment` IDs for this Employee.
- `home_location` (string, optional, nullable) — The employee's home address.
- `work_location` (string, optional, nullable) — The employee's work address.
- `manager` (string, optional, nullable) — The employee ID of the employee's manager.
- `pay_group` (string, optional, nullable) — The employee's pay group
- `ssn` (string, optional, nullable) — The employee's social security number.
- `gender` (enum, optional, nullable) — The employee's gender. This field is an open enum: Merge can return a value outside this list when an integration provides one it does not map. Pass `show_enum_origins=gender` to receive the integration's own value instead.
  - Allowed values: `MALE`, `FEMALE`, `NON-BINARY`, `OTHER`, `PREFER_NOT_TO_DISCLOSE`
- `ethnicity` (enum, optional, nullable) — The employee's ethnicity. This field is an open enum: Merge can return a value outside this list when an integration provides one it does not map. Pass `show_enum_origins=ethnicity` to receive the integration's own value instead.
  - Allowed values: `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`
- `marital_status` (enum, optional, nullable) — The employee's filing status as related to marital status. This field is an open enum: Merge can return a value outside this list when an integration provides one it does not map. Pass `show_enum_origins=marital_status` to receive the integration's own value instead.
  - Allowed values: `SINGLE`, `MARRIED_FILING_JOINTLY`, `MARRIED_FILING_SEPARATELY`, `HEAD_OF_HOUSEHOLD`, `QUALIFYING_WIDOW_OR_WIDOWER_WITH_DEPENDENT_CHILD`
- `date_of_birth` (datetime, optional, nullable) — The employee's date of birth.
- `start_date` (datetime, optional, nullable) — The date that the employee started working. If an employee was rehired, the most recent start date will be returned.
- `remote_created_at` (datetime, optional, nullable) — When the third party's employee was created.
- `employment_status` (enum, optional, nullable) — The employment status of the employee. This field is an open enum: Merge can return a value outside this list when an integration provides one it does not map. Pass `show_enum_origins=employment_status` to receive the integration's own value instead.
  - Allowed values: `ACTIVE`, `PENDING`, `INACTIVE`
- `termination_date` (datetime, optional, nullable) — The employee's termination date.
- `avatar` (string, optional, nullable) — The URL of the employee's avatar image.
- `employee_url` (string, optional, nullable) — The 3rd party URL of the employee.
- `custom_fields` (map from string to any, optional, nullable) — Custom fields configured for a given model.
- `remote_was_deleted` (boolean, optional) — 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` (EmployeeFieldMappings, optional, nullable)
- `remote_data` (list of RemoteData, optional, nullable)
- `team` (string, optional, nullable, deprecated) — The employee's team.
- `hire_date` (datetime, optional, nullable, deprecated) — 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.

## Types

### EmployeeFieldMappings

- `organization_defined_targets` (map from string to any, optional)
- `linked_account_defined_targets` (map from string to any, optional)

### RemoteData

# 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

- `path` (string, required) — The third-party API path that is being called.
- `data` (any, optional) — The data returned from the third-party for this object in its original, unnormalized format.

## Examples

**Response**

```json
{
  "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/id"

querystring = {"include_remote_data":"true"}

headers = {
    "X-Account-Token": "X-Account-Token",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.merge.dev/api/hris/v1/employees/id?include_remote_data=true';
const options = {
  method: 'GET',
  headers: {'X-Account-Token': 'X-Account-Token', Authorization: 'Bearer <token>'}
};

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/id?include_remote_data=true"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Account-Token", "X-Account-Token")
	req.Header.Add("Authorization", "Bearer <token>")

	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/id?include_remote_data=true")

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 <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.merge.dev/api/hris/v1/employees/id?include_remote_data=true")
  .header("X-Account-Token", "X-Account-Token")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.merge.dev/api/hris/v1/employees/id?include_remote_data=true', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Account-Token' => 'X-Account-Token',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.merge.dev/api/hris/v1/employees/id?include_remote_data=true");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Account-Token", "X-Account-Token");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Account-Token": "X-Account-Token",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.merge.dev/api/hris/v1/employees/id?include_remote_data=true")! 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()
```