Why the mapping lives on our side
The conventional design is for an API to publish a schema and require callers to conform to it. It is simple to document and simple to validate, and it pushes the entire cost of integration onto the caller — who now maintains a transformation layer, in their codebase, that breaks when either side changes.
For this particular problem that trade is a bad one. The systems that hold employee data — HRIS platforms, CRMs, internal directories — emit their own deeply nested shapes, and those shapes are not negotiable. Requiring a flat, prescribed body means every customer writes the same adapter.
Configuring the mapping on the QRBold side moves that work into a UI where a non-developer can inspect and adjust it, and where the sample payload makes the available paths explicit rather than a guess. When your HRIS adds a field, you point at it in the dashboard rather than shipping code.
What dry-run returns
Dry-run is the difference between integrating confidently and integrating by creating test records you then have to clean up. Post a real payload and QRBold answers with what would have happened.
- Resolved fields. Every card field with the value your payload produced for it. The fastest way to catch a path pointing one level too deep.
- External ID. The key extracted for idempotency, or null if the path did not resolve — which is the usual cause of accidental duplicate cards.
- Short code. The link this card would receive, so custom short-link schemes can be verified before going live.
- Unmapped paths. Paths present in your payload that no field consumes. Usually harmless, occasionally the signal that a field you meant to map is silently being dropped.
- Warnings. Non-fatal problems — a value that will be truncated, a field the template locks — that would not stop ingestion but that you probably want to know about.
Configuration versioning and stale configs
The API configuration is validated against a specific card template. Templates are editable, and someone will eventually edit one in a way the mapping did not anticipate — locking a field the API writes into, most commonly.
QRBold marks the configuration stale rather than rejecting traffic. That is a deliberate choice: refusing live ingestion because an administrator edited a template in another tab would turn a cosmetic change into an outage, and the integration would fail at the worst possible moment for reasons the caller cannot see. Ingestion continues, the dashboard says clearly that the configuration was validated against a template the campaign no longer uses, and you re-validate when convenient.
When to use the API instead of CSV import
Both create cards from structured data, and for a one-off batch the spreadsheet is genuinely faster to get working. The API earns its integration cost when the data has an owner that is a system rather than a person.
The concrete test: if a human has a recurring calendar reminder to export a file, that is a job for the API. If the export happens once for a specific event and then never again, it is a job for CSV import. Most organisations end up running both — the API for the continuous employee card programme, imports for the event batches alongside it.