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 /employeescan expand outcompany,groups,employments,locations,managers,team, andpay_groupGET /candidatescan expand outapplicationsandattachmentsGET /ticketscan expand outassignees,creator,project,collections,account,contact,parent_ticket, andattachments
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
}