Overview

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

• GET /employees can expand company, groups, employments, home_location, work_location, managers, team, and pay_group

• GET /candidates can expand applications and attachments

• GET /tickets can expand assignees, creator, project, collections, account, contact, parent_ticket, and attachments

See the usage section below for syntax and an example.

Which Merge endpoints support the expand parameter?

In the API Reference section of the Merge Docs, you can review 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 the expand parameter in an API request?

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

To expand every available relation on Employees, pass the following as the value:

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

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 — expanding employments and manager on 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 in a single request, but it does not support expanding fields within already-expanded fields.

• Supported — multiple field expansion, e.g., expand=groups,employments,manager on employees.

• Not supported — expanding fields within already-expanded fields (nested expansion).

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

Note: When you need nested data, favor flat expansions and use a follow-up request to retrieve the sub-resource.

Who should I contact for help?

If you have questions about which fields are expandable on a specific endpoint or need help structuring a request, reach out to us at [email protected].