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=team,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
}

Using PATCH endpoints in Merge

Migrating from Teams to Groups

Advanced Java SDK Migration Guide

What is shell data filtering?

Building to QuickBooks Desktop