curl --request POST \
--url https://api.thingidentity.com/codes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.thingidentity.public.v1+json' \
--data '
{
"codes": [
{
"reference": "gs1-digital-link-product",
"digitalLinkStem": "https://gtin.at",
"primaryKey": {
"key": "01",
"value": "09521234543213"
},
"ais": [
{
"key": "10",
"value": "LOT42"
}
],
"extensionParameters": [],
"linkType": null,
"context": null
},
{
"reference": "datamatrix-product",
"primaryKey": {
"key": "01",
"value": "09521234543213"
},
"ais": [
{
"key": "10",
"value": "LOT42"
}
],
"extensionParameters": [],
"linkType": null,
"context": null
}
]
}
'{
"codes": [
{
"reference": "gs1-digital-link-product",
"barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
"hri": "(01)09521234543213(10)LOT42"
},
{
"reference": "datamatrix-product",
"barcodeText": "(01)09521234543213(10)LOT42",
"hri": "(01)09521234543213(10)LOT42"
}
],
"errors": []
}Batch Generate 2D barcodes
Takes a batch of code definitions and returns, for each one, the payload to encode in a symbol plus its human readable interpretation. Nothing is rendered as an image: you get the text and feed it to your own 2D barcode renderer.
A definition that fails validation does not fail the request. The status is 200 OK even when every item was rejected and codes comes back empty, so check errors rather than the status code.
Requires the write:codes scope.
Set compression on each definition to EPC_BASE64 or EPC_HEX for a compressed Digital Link. Omit or send null for an uncompressed URI. Compression requires a GTIN and serial number.
curl --request POST \
--url https://api.thingidentity.com/codes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.thingidentity.public.v1+json' \
--data '
{
"codes": [
{
"reference": "gs1-digital-link-product",
"digitalLinkStem": "https://gtin.at",
"primaryKey": {
"key": "01",
"value": "09521234543213"
},
"ais": [
{
"key": "10",
"value": "LOT42"
}
],
"extensionParameters": [],
"linkType": null,
"context": null
},
{
"reference": "datamatrix-product",
"primaryKey": {
"key": "01",
"value": "09521234543213"
},
"ais": [
{
"key": "10",
"value": "LOT42"
}
],
"extensionParameters": [],
"linkType": null,
"context": null
}
]
}
'{
"codes": [
{
"reference": "gs1-digital-link-product",
"barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
"hri": "(01)09521234543213(10)LOT42"
},
{
"reference": "datamatrix-product",
"barcodeText": "(01)09521234543213(10)LOT42",
"hri": "(01)09521234543213(10)LOT42"
}
],
"errors": []
}Optional parameters
ais, linkType, context and extensionParameters may be omitted. Omitting linkType or
context (or sending null) adds no corresponding query parameter. Omitting
ais or extensionParameters (or sending null) is equivalent to an empty list ([]).
Compression
Each item may independently setcompression to EPC_BASE64 or EPC_HEX.
Omit it or send null for an uncompressed URI. Compressed and uncompressed codes can share a batch.
The same prerequisites as single generation apply:
digitalLinkStem, primary key 01, serial number AI 21, and none of the AIs 03, 717, 8014 or 8040–8043.
{
"codes": [
{
"reference": "base64-label",
"digitalLinkStem": "https://thingidentity.com",
"primaryKey": { "key": "01", "value": "09528765123457" },
"ais": [{ "key": "21", "value": "123456789123" }],
"compression": "EPC_BASE64"
},
{
"reference": "hex-label",
"digitalLinkStem": "https://thingidentity.com",
"primaryKey": { "key": "01", "value": "09528765123457" },
"ais": [{ "key": "21", "value": "123456789123" }],
"compression": "EPC_HEX"
}
]
}
barcodeText uses an ex or eh path; hri keeps the original GS1 data.
Invalid compression is reported for the affected item in errors, with code
Validation.Invalid.compression and path compression. The batch status remains 200 OK.
GS1 Application Identifiers
Browse the official GS1 Application Identifiers directory to choose identifiers forprimaryKey and ais. It describes their meaning, value format, mandatory
associations, invalid pairings and permitted use in GS1 Digital Link URIs.
The API validates against its bundled GS1 Barcode Syntax Dictionary. Not every identifier in
the directory can be used as a primary key or combined with every other AI.
Partial success
Every item of a batch is validated on its own, so a rejected item does not fail the request. The status stays200 OK even when every item was rejected and codes comes back empty, which means you
should check errors rather than the status code.
Each request item may include a string reference of your choice. The API echoes it unchanged
in either codes or errors. If omitted or null, the reference is the item’s zero-based position
in the original request, returned as a string: "0", "1", and so on. Empty strings are preserved.
Use distinct references and avoid collisions with generated references within a batch.
References do not provide deduplication or idempotency.
{
"codes": [],
"errors": [
{
"reference": "product-label",
"errors": [
{
"code": "Validation.Invalid.primaryKey",
"path": "primaryKey",
"args": []
}
]
}
]
}
Validation codes
path matches the part of the definition at fault, so ais.2 is the third entry of ais.
| Code | Meaning |
|---|---|
Validation.Invalid.primaryKey | Unknown AI, an AI not accepted as a primary key here, or a value that fails its format or check digit. |
Validation.Invalid.ais | Duplicate AI keys in ais. |
Validation.Invalid.ais.<index> | Unknown AI, a value that fails its format, or an AI repeating the primary key. |
Validation.Invalid.ais.qualifiers | The path qualifiers do not all come from one qualifier sequence of the chosen primary key. |
Validation.Invalid.ais.<index>.digitalLink | The AI is neither a qualifier of the primary key nor a permitted GS1 Digital Link data attribute. |
Validation.Invalid.relations.<ai>.requires | The AI requires another AI that is absent. |
Validation.Invalid.relations.<ai>.excludes.<other> | Two mutually exclusive AIs were sent together. |
Validation.Invalid.digitalLinkStem | Not an acceptable origin. |
Validation.Invalid.linkType | Not an offered gs1: link type and not an absolute HTTP(S) URI. |
Validation.Invalid.extensionParameters | Sent without a digitalLinkStem, or duplicate keys. |
Validation.Invalid.extensionParameters.<index> | Reserved or malformed key, or a value outside the allowed characters. |
Validation.Invalid.context | Value outside the allowed characters. |
Validation.Invalid.compression | Unknown compression, missing GTIN or serial, or an AI that cannot be stored in EPC binary. |
Authorizations
The access_token from POST /oauth/token.
Body
The definitions to generate. Items are processed in order and each one is validated on its own.
Hide child attributes
Hide child attributes
The identifying application identifier. With a digitalLinkStem it must be a GS1 Digital Link primary key in the GS1 Barcode Syntax Dictionary; without one, 03 is additionally accepted, the identifier for made-to-order trade items.
GTIN (01) accepts 8, 12, 13 or 14 digits, verifies the mod-10 check digit and normalises the value to 14 digits, so the value you get back may be longer than the one you sent.
Hide child attributes
Hide child attributes
GS1 application identifier. Browse the official GS1 Application Identifiers directory for meanings, value formats, required associations and Digital Link usage. The API validates identifiers against its bundled GS1 Barcode Syntax Dictionary; not every AI is valid as a primary key or in every combination.
"01"
"09521234543213"
Optional correlation identifier, echoed unchanged on success or failure. When omitted or null, the API returns the zero-based input position as a string, e.g. 0 becomes "0". Empty strings are preserved. Avoid collisions with generated references. This is not an idempotency key.
"product-label"
Further application identifiers. Pass [] for none.
Each key must exist in the GS1 Barcode Syntax Dictionary and its value must match the format that dictionary declares. An AI may not repeat the primary key, keys may not repeat each other, and GS1 "requires" and "excludes" relations between AIs are enforced.
With a digitalLinkStem every AI must be either a path qualifier of the chosen primary key, taken from a single consistent qualifier sequence, or a data attribute that GS1 Digital Link URI Syntax allows in the query string. Qualifiers keep the order GS1 defines, not the order you send.
Temperature AIs (4330 to 4333) are normalised for you: the magnitude is padded to six digits and a negative value keeps its trailing minus.
When compression is selected, the EPC path carries these AIs instead of separate path and query fields.
Hide child attributes
Hide child attributes
GS1 application identifier. Browse the official GS1 Application Identifiers directory for meanings, value formats, required associations and Digital Link usage. The API validates identifiers against its bundled GS1 Barcode Syntax Dictionary; not every AI is valid as a primary key or in every combination.
"01"
"09521234543213"
Optional custom query parameters appended to a GS1 Digital Link URI. Omit, send null or pass [] for none.
Only with a digitalLinkStem; a non-empty list without one is rejected. Keys must not be linkType or context, must contain at least one non-digit, must be unique, and both keys and values are limited to unreserved ASCII and URI punctuation.
The origin a GS1 Digital Link path is appended to. Supplying it is what makes this a GS1 Digital Link: send a stem and you get a URI, leave it out and you get a GS1 element string. Must be http or https with a host, and carry no userinfo, query or fragment. A single trailing slash is stripped; empty path segments are rejected.
"https://gtin.at"
The GS1 link type the URI resolves to. Only with a digitalLinkStem. A gs1: value must be one the generator offers from the GS1 Web Vocabulary page types; gs1:defaultPage, gs1:defaultPageMulti and gs1:handledBy are not selectable. Any other value must be an absolute http or https URI.
"gs1:pip"
Value for the GS1 Digital Link context query parameter. Only with a digitalLinkStem, same character rules as extension parameter values.
"dpp"
Optional EPC compression of a GS1 Digital Link URI. EPC_BASE64 encodes the EPC binary in URL-safe Base64 (an ex path); EPC_HEX uses hexadecimal (an eh path). Omit or send null for an uncompressed URI.
Requires primary key 01 (GTIN), AI 21 (serial number), and digitalLinkStem. AIs 03, 717, 8014 and 8040–8043 cannot be stored in EPC binary, so a code that contains any of them cannot be compressed. The EPC path carries the AIs; extensionParameters, linkType, and context remain query parameters. Human-readable interpretation (hri) is unchanged.
An unknown or inapplicable value produces Validation.Invalid.compression: HTTP 422 for a single code, or a per-item error in the batch HTTP 200 response.
EPC_BASE64, EPC_HEX, null "EPC_BASE64"
"EPC_HEX"
Response
Generated codes in codes, rejected definitions in errors. Both carry reference, which ties an entry back to the item you sent.
Hide child attributes
Hide child attributes
The supplied reference unchanged, or the zero-based input position as a string when omitted or null.
The payload to encode. With a digitalLinkStem the GS1 Digital Link URI; without one, the GS1 element string, where parentheses inside a value are escaped as ^040 and ^041 so that a renderer places the FNC1 separators correctly. With compression, this is the URI with an EPC ex or eh path.
"https://gtin.at/01/09521234543213"
Human readable interpretation, the (AI)value text printed under the symbol. Compression does not change this value.
"(01)09521234543213"
Hide child attributes
Hide child attributes
The supplied reference unchanged, or the zero-based input position as a string when omitted or null.