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 outcompany
,groups
,employments
,locations
,managers
,team
, andpay_group
GET /candidates
can expand outapplications
andattachments
GET /tickets
can 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
}