What is the expand parameter?

The expand parameter allows you to return multiple types of objects in a single GET request. Any relational object can be expanded, and multiple objects can be expanded in a single request. For example:

GET /employees can expand out company, groups, employments, locations, managers, team, and pay_group
GET /candidates can expand out applications and attachments
GET /tickets can expand out assignees, creator, project, collections, account, contact, parent_ticket, and attachments

You can see the usage of the expand parameter in the usage section!

Which Merge endpoints support the expand parameter?

In the API Reference section of the Merge Docs, you can review our endpoints by API category. Click on the object and operation of interest, and look for "expand", listed under the "Query & Path Parameters" section.

How do I use "expand" in an API request?

The expand parameter is a query parameter and follows standard REST formatting. Separate multiple expansions with a comma (ie. expand=groups,employments).

If you want to expand all the possibilities for Employees, you can input the following as the value for the query parameter!

company,groups,employments,work_location,home_location,manager,pay_group

An example cURL:

curl --location 'https://api.merge.dev/api/hris/v1/employees?expand=manager%2Cemployments' \
--header 'X-Account-Token: #{{account-token}}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer #{{production-key}}' \

Example response of expanding on Employments and Manager for GET /Employees:

{
  "id": "4ca57c49-bae1-4deb-939d-3d9d70e7d1c2",
  "remote_id": "252",
  "created_at": "2024-05-13T18:19:08.623204Z",
  "modified_at": "2024-05-16T19:09:10.384582Z",
  "employee_number": "35125",
  "company": null,
  "first_name": "Merge",
  "last_name": "Expand",
  "preferred_name": null,
  "display_full_name": "Merge Expand",
  "username": null,
  "groups": [],
  "work_email": "[email protected]",
  "personal_email": "[email protected]",
  "mobile_phone_number": "+11111111111",
  "employments": [
    {
      "id": "13a64120-43b0-4ef7-a66d-ba5873a0779f",
      "remote_id": null,
      "created_at": "2024-05-16T19:30:33.893081Z",
      "modified_at": "2024-05-16T19:30:33.893090Z",
      "employee": "4ca57c49-bae1-4deb-939d-3d9d70e7d1c2",
      "job_title": "Controller",
      "pay_rate": 12214,
      "pay_period": "WEEK",
      "pay_frequency": "Every other week",
      "pay_currency": "USD",
      "pay_group": null,
      "flsa_status": null,
      "effective_date": "2019-04-17T00:00:00Z",
      "employment_type": "CONTRACTOR",
      "remote_was_deleted": false,
      "field_mappings": {
        "organization_defined_targets": {},
        "linked_account_defined_targets": {}
      },
      "remote_data": null
    }
  ],
  "home_location": null,
  "work_location": null,
  "manager": {
    "id": "239e5f58-6d21-4d81-9797-14175f96bd78",
    "remote_id": "42",
    "created_at": "2024-05-13T18:18:41.606396Z",
    "modified_at": "2024-05-15T18:50:10.509929Z",
    "employee_number": "39",
    "company": null,
    "first_name": "Merge",
    "last_name": "Manager",
    "preferred_name": null,
    "display_full_name": "Merge Manager",
    "username": null,
    "groups": [],
    "work_email": "[email protected]",
    "personal_email": null,
    "mobile_phone_number": "+23456",
    "employments": ["9f284e42-df84-4aa3-92ad-8132aa4e25f4"],
    "home_location": null,
    "work_location": null,
    "manager": "f399b796-262e-4d70-b890-8559b4f65c0f",
    "team": "b6435410-c372-49a8-864f-2fe3234f2c9b",
    "pay_group": null,
    "ssn": null,
    "gender": "MALE",
    "ethnicity": "WHITE",
    "marital_status": "MARRIED_FILING_JOINTLY",
    "date_of_birth": "1979-06-09T00:00:00Z",
    "hire_date": null,
    "start_date": "2023-06-10T00:00:00Z",
    "remote_created_at": null,
    "employment_status": "ACTIVE",
    "termination_date": null,
    "avatar": null,
    "custom_fields": {},
    "remote_was_deleted": false,
    "field_mappings": {
      "organization_defined_targets": {},
      "linked_account_defined_targets": {}
    },
    "remote_data": null
  },
  "team": null,
  "pay_group": null,
  "ssn": null,
  "gender": "MALE",
  "ethnicity": "ASIAN_OR_INDIAN_SUBCONTINENT",
  "marital_status": "SINGLE",
  "date_of_birth": "1991-05-16T00:00:00Z",
  "hire_date": null,
  "start_date": "2019-04-17T00:00:00Z",
  "remote_created_at": null,
  "employment_status": "ACTIVE",
  "termination_date": null,
  "avatar": null,
  "custom_fields": {},
  "remote_was_deleted": false,
  "field_mappings": {
    "organization_defined_targets": {},
    "linked_account_defined_targets": {}
  },
  "remote_data": null
}

Multiple and nested field expansion

The expand parameter supports expanding multiple fields, but has important limitations for nested expansions.

What's supported

Multiple field expansion: expand=groups,employments,manager on employees for instance

What's not supported

Expanding fields within already expanded fields

Example

✅ This will work 

GET /employees/{id}?expand=groups,manager

❌ This won't work

GET /employees/{id}?expand=manager.employments

✅ Instead, use separate requests 

GET /employees/{id}?expand=manager 
GET /employees/{manager_id}?expand=employments

This approach ensures consistency with Merge’s current limitations on nested field expansions and helps avoid unexpected errors in your API requests. When working with nested data, favor clear and flat expansions, and use follow-up requests to retrieve additional sub-resources when needed.