> 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.

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`.

### The Employee Object

```json
{
  "id": "string",
  "remote_id": "string",
  "created_at": "2023-01-01T00:00:00Z",
  "modified_at": "2023-01-01T00:00:00Z",
  "employee_number": "string",
  "company": "string",
  "first_name": "string",
  "last_name": "string",
  "preferred_name": "string",
  "display_full_name": "string",
  "username": "string",
  "groups": [
    "string"
  ],
  "work_email": "string",
  "personal_email": "string",
  "mobile_phone_number": "string",
  "employments": [
    "string"
  ],
  "home_location": "string",
  "work_location": "string",
  "manager": "string",
  "team": "string",
  "pay_group": "string",
  "ssn": "string",
  "gender": "MALE",
  "ethnicity": "AMERICAN_INDIAN_OR_ALASKA_NATIVE",
  "marital_status": "SINGLE",
  "date_of_birth": "2023-01-01T00:00:00Z",
  "hire_date": "2023-01-01T00:00:00Z",
  "start_date": "2023-01-01T00:00:00Z",
  "remote_created_at": "2023-01-01T00:00:00Z",
  "employment_status": "ACTIVE",
  "termination_date": "2023-01-01T00:00:00Z",
  "avatar": "string",
  "employee_url": "string",
  "custom_fields": {
    "string": {}
  },
  "remote_was_deleted": true,
  "field_mappings": {
    "organization_defined_targets": {
      "string": {}
    },
    "linked_account_defined_targets": {
      "string": {}
    }
  },
  "remote_data": [
    {
      "path": "string",
      "data": {}
    }
  ]
}
```

### Schema (`Employee`)

```yaml
components:
  schemas:
    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
          maxLength: 254
          description: The employee's work email.
        personal_email:
          type:
            - string
            - 'null'
          format: email
          maxLength: 254
          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.
          deprecated: true
        pay_group:
          type:
            - string
            - 'null'
          format: uuid
          description: The employee's pay group
        ssn:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The employee's social security number.
        gender:
          oneOf:
            - $ref: '#/components/schemas/GenderEnum'
            - type: 'null'
          description: >-
            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.
        ethnicity:
          oneOf:
            - $ref: '#/components/schemas/EthnicityEnum'
            - type: 'null'
          description: >-
            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.
        marital_status:
          oneOf:
            - $ref: '#/components/schemas/MaritalStatusEnum'
            - type: 'null'
          description: >-
            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.
        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.
          deprecated: true
        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. 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.
        termination_date:
          type:
            - string
            - 'null'
          format: date-time
          description: The employee's termination date.
        avatar:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2000
          description: The URL of the employee's avatar image.
        employee_url:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2000
          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'
      title: Employee
```