All Collections
Features
API
Using The Expand Parameter
Using The Expand Parameter

Description and Application of Expand Parameter

Yash Gogri avatar
Written by Yash Gogri
Updated over a week ago

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

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

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
}

Did this answer your question?