What is the show_enum_origins parameter?
Merge's Show Enum Origins feature allows you to obtain the value of common model enum fields in the original format that Merge received it in. This feature is available in all of Merge's common model API endpoints, where relevant.
If you include a common model enum field's name into the show_enum_origins query parameter, Merge will replace the normalized enum value of the specified common model field with the unnormalized value from the third-party in the response body. This is useful if you always want to return the original value of common model fields as they are represented in your customer's third-party platform, instead of in Merge's normalized format.
When using the show_enum_origins query parameter, Merge will map the unnormalized value of the field to the specified common model field so that you can reliably access that field's value in a consistent way, regardless of the integration your customer is using.
Below is an example response from Merge's /employees endpoint, where employment_status was passed into the query parameters. In this example, instead of returning the normalized enum value of "INACTIVE" in the employment_status field, we return the original value "Terminated" as it was received from the third-party.
{
"id": "0958cbc6-6040-430a-848e-aafacbadf4ae",
"remote_id": "19202938",
"employee_number": "2",
"display_full_name": "Cousin Greg Hirsch",
"employment_status": "Terminated",
...
...
}
Example Use Cases
Most Common: GET /Groups?show_enum_origins=type
Return the raw Group Types + Cost Centers to provide your customers the flexibility to identify which Cost Center they'd like to map in product
GET /Employees?show_enum_origins=employment_status
Return the non-normalized Employment Statuses for all Employees
GET /Tickets?show_enum_origins=status
Return the non-normalized Ticket Statuses for all Tickets
An example cURL
curl 'https://api.merge.dev/api/ticketing/v1/tickets?show_enum_origins=status' \
-H 'Authorization: Bearer [Insert your API key]' \
-H 'X-Account-Token: [Insert your Account token]'