# Mapping

The Quinyx **Mapping API** manages the link between identifiers in your systems (your "external" IDs) and identifiers used internally by Quinyx. The mapping database is the **single source of truth** for integration keys — most other v2 endpoints take Quinyx internal IDs (`groupId`, `employeeId`, `shiftId`, etc.), and the only supported way to translate from your external values to those internal IDs is through this API.

If you're starting an integration from scratch, this is usually the first API you'll call. Resolve your external IDs to Quinyx internal IDs once, then use the internal IDs everywhere else.

## Mapping types

Each mapping carries a `mappingType` that identifies what kind of entity it points at. The supported types are:

| `mappingType` | Use |
|  --- | --- |
| `GROUP_ID` | Map external IDs to Quinyx internal Group IDs in the organizational structure. |
| `DISTRICT_ID` | Map a District to an external value. |
| `UNIT_ID` | Map a Unit to an external value. |
| `SECTION_ID` | Map a Section to an external value. Unique **per Unit** — see Uniqueness below. |
| `EMPLOYEE_ID` | Fetch Quinyx internal employee IDs that map to badge numbers or external employee identifiers. |
| `SKILL_ID` | Map skills to external representations. |
| `ROLE_ID` | Map Quinyx roles. |
| `ABSENCE_ID` | Map an external absence occasion to the corresponding absence in Quinyx (added December 2024). |
| `AGREEMENT` | Map an Agreement to an external value. |
| `AGREEMENT_TEMPLATE_ID` | Map an Agreement Template. |
| `SHIFT_ID` | Map a shift. |
| `COST_CENTER_ID` | Map a cost center. |
| `STAFF_CATEGORY_ID` | Map a staff category. |
| `FORECAST_VARIABLE_IDS` | Map forecast variables. |
| `TRANSFER_TO_PAYROLL` | Map the transfer-to-payroll integration key. |
| `WEBPUNCH_LINKS` | Map a Webpunch link to an external value. |
| `EXTERNAL_COMPANY_CODE` | Map an external company code. |


The mapping types catalog is also discoverable at runtime — call `GET /v2/mapping/mappingTypes` for the live list.

## Uniqueness

Mappings are unique on the tuple **(`mappingType`, `domainId`, `externalValue`)**. Submitting a duplicate triple is rejected.

`SECTION_ID` is the one exception: a Section's external value must be unique **within the parent Unit**, not globally. The same external value can be reused across different Units.

## Operating on mappings

The Mapping API endpoints in the spec all live under `/v2/mapping/`:

- `GET /v2/mapping/mappingTypes` — list of supported mapping types.
- `GET /v2/mapping/mappingTypes/{mappingType}/mappings` — list mappings of a given type. Pass either `quinyxValue` or `externalValue` as a query parameter; passing both returns an error.
- `POST /v2/mapping/groups/{domainGroupId}` — create a mapping. The body is `{ "quinyxValue": "...", "externalValue": "...", "mappingType": "..." }`. The API validates that `quinyxValue` exists for the given mapping type. The response includes the new mapping ID — you'll need it (combined with the domain ID) to update or delete the mapping later.
- `PUT /v2/mapping/{mappingId}` — update a mapping. Only `externalValue` is mutable.
- `DELETE /v2/mapping/{mappingId}` — delete a mapping (returns `204 No Content` on success).


## Access rights

To call any Mapping endpoint, your integration credentials need the **Mapping** scope. Configure this in **Account Settings → Integration credentials**.

## "Mapping is the source of truth"

Two practical consequences:

1. **When external IDs change in your system, update Mapping first.** Don't try to update the entity directly via another API and assume the linkage will follow — the mapping database is what other integrations and SOAP updates resolve against.
2. **SOAP updates also write to Mapping.** If you are running both REST and SOAP integrations, expect the Mapping database to be the convergence point.


## Next steps

- Browse the [Mappings tag in the API reference](/api/v2/specs/quinyx-public-api-v2) to see exact request/response shapes.
- Once your mappings are in place, return to the [REST API getting started](/api/v2) for authentication and environment details.