Native enum values

Normalized and native values

Merge maps each platform’s own enum values onto a fixed set of Common Model values. A Jira ticket whose status reads Work in progress comes back from Merge as IN_PROGRESS, and one that reads Fertig comes back as CLOSED. IN_PROGRESS is the normalized value, the one that means the same thing in every integration. Work in progress is the native value, the one the platform itself stores.

Your end users configure their own values in their own systems, and some of those have no Common Model equivalent. A Jira project can define a status called Pending customer, and an HRIS can define an employment status called ACTIVELOA. Merge exposes the native value for these fields so you can read what the platform actually holds and write a value the platform already recognizes.

Reading native values

Pass show_native_enum_values=true on a GET request. Merge adds a <field>_native field to the response next to the normalized field, so you get both.

curl -G https://api.merge.dev/api/ticketing/v1/tickets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Account-Token: YOUR_ACCOUNT_TOKEN" \
  -d show_native_enum_values=true

{
  "status": "IN_PROGRESS",
  "status_native": "Work in progress",
  "priority": "HIGH",
  "priority_native": "High"
}

show_enum_origins does something different. It takes a comma-separated list of field names and replaces the normalized value in the field itself, so status returns Work in progress rather than IN_PROGRESS. Use it when you want the native value in place of the normalized one rather than alongside it.

Writing native values

Pass <field>_native inside the model object on a POST or PATCH request, in place of its normalized sibling. Merge sends the value to the platform without normalizing it.

{
  "model": {
    "name": "Rotate the staging credentials",
    "collections": ["a72c2f41-40ad-48c4-9929-b00b3996a0b3"],
    "status_native": "Work in progress"
  }
}

Send either the normalized field or its native counterpart, never both. Merge validates this on every write, before it reaches the integration:

{
  "warnings": [],
  "errors": [
    {
      "source": { "pointer": "/model/status_native" },
      "title": "Invalid Request Shape",
      "detail": "Only one of status and status_native may be provided.",
      "problem_type": "INVALID_REQUEST_DATA_SHAPE"
    }
  ]
}

Which fields and which integrations

A Common Model enum field has a native counterpart when Merge normalizes its value from the platform. Merge’s own enums, such as Linked Account status, have none. The response schema for each endpoint in the API reference lists the <field>_native fields you can read, and the request schema lists the ones you can write.

Reading is available for every field that has a native counterpart, because Merge stores the value during the sync. Writing is built per field per integration. An integration with no handling for a native parameter ignores the value, and since you sent that parameter in place of its normalized sibling, the write carries no value for the field at all and the request succeeds without an error.

Neither the /meta response nor the supported-fields matrix distinguishes an integration that handles a native parameter from one that ignores it, so contact Merge support to confirm native writes for an integration before you depend on them.

Next steps