API Reference

API: Resolver

Programmatic access — early access

The

tieback

API is available to selected workspaces during early access. Endpoints in production today are authenticated with an authenticated session. Standalone API-key access is being onboarded per workspace. Contact

tieback

to enable API credentials for your workspace.

What does the resolver API do?

The resolver provides public endpoints that map product identifiers to the correct Digital Product Passport destination. It powers the GS1 Digital Link scan path and is the entry point for every QR, NFC and RFID scan.

Who it is for

Systems that resolve a barcode or identifier to a tieback product reference without authentication.

Resolve identifier

Resolves a product identifier to a destination URL.

Authentication: none required. The resolver is a public endpoint.

Inputs

ParameterTypeRequiredDescription
Host headertextYesThe brand’s resolver domain (e.g. acme.tieback.io or passport.brand.com)
GTINtextNoGTIN identifier
LottextNoLot or batch code (GS1 AI 10)
SerialtextNoSerial number (GS1 AI 21)
Fallback typetextNoNon-GS1 fallback: mu (unit), mb (batch), ml (lot)
Fallback IDtextNoUUID identifier for non-GS1 resolution

Resolution strategy

1

Tenant validation

The hostname is mapped to a brand through a verified custom domain or platform subdomain.

2

Non-GS1 fallback

If a fallback type and ID are supplied, resolution runs directly by entity ID with a brand ownership check.

3

GS1 serial

If GTIN and serial are supplied, resolution targets the specific unit.

4

GS1 lot

If GTIN and lot are supplied, resolution targets the lot.
5

GTIN only

Resolution targets the product, taking active identifiers first with a retired fallback.

Activation state

Resolution returns the destination for the identifier. Activation state is managed by the brand, either at issue or later, and is reported in the response rather than changed by the scan.

Response

1{
2  "ok": true,
3  "outcome": "resolved",
4  "destination_url": "/p/<passport-id>",
5  "activation_state": "active | inactive | not_applicable",
6  "cache_policy": "no_store | cache_public_3600"
7}

Error responses return { "ok": false, "outcome": "brand_not_found" | "not_found" }.

Cache semantics

The public layer uses the cache policy to set HTTP headers: no_store for a unit whose state has recently changed, and cache_public_3600 for stable resolutions.

Scan telemetry

Scan events are recorded asynchronously after each resolution. Telemetry never delays the consumer redirect.

Recorded data includes:

  • Resolved product and unit references
  • Original request path and query parameters
  • Geographic information (country, with region and city where available)
  • User agent metadata, including a coarse summary of browser family, operating system and device class
  • Traffic classification: human, link preview unfurler, crawler or unknown
  • Resolution outcome

Traffic classification. Each resolved scan is classified so that human activity, link preview unfurlers and search crawlers can be reported separately. Classification is conservative and based on the request’s user agent. Unknown traffic is reported distinctly in analytics.

Privacy. Scanning requires no consumer account and builds no personal profile. IP data is retained for a defined retention period and then masked. The parsed user agent summary holds only coarse browser, operating system and device fields. See Data and Privacy.

Legacy resolver

The original resolution endpoint remains available for backward compatibility. It resolves a product identifier to a product reference using the brand’s platform subdomain.

Inputs:

ParameterTypeDescription
SubdomaintextThe brand’s resolver subdomain (e.g. acme)
Identifier typetextCurrently: gtin
Identifier valuetextThe identifier to resolve (e.g. 05060012345678)

Returns: the product reference on match, or null when there is no match.

Minimal disclosure

The resolver returns only a destination URL or product reference. Product names, descriptions and pricing stay private. The resolver is deliberately a routing primitive with the narrowest possible response.

Limits and notes

  • Public access. No authentication is required.
  • GTIN normalisation. GTIN values are normalised to digits only before resolution.
  • Brand scoped. Resolution is scoped to the brand identified by the hostname.
  • Fallback IDs. These must be valid UUID strings. Invalid values return not_found.

FAQ

No. Only the destination URL is returned. Product data access requires authentication through separate APIs.

The resolver falls back to the most recently retired match, so previously issued codes remain resolvable.

The public resolver supports GTIN for GS1 paths today. Non-GS1 fallback paths resolve by internal ID.

Telemetry is recorded asynchronously after each scan and never delays the consumer redirect. No consumer account is required, IP data is masked after a defined retention period, and reporting stays aggregate.