Batch Render 2D barcodes

curl --request POST \
  --url https://api.thingidentity.com/codes/render/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.thingidentity.public.v1+json' \
  --data '
{
  "codes": [
    {
      "reference": "product-label",
      "mode": "QR_GS1_DIGITAL_LINK_URI",
      "digitalLinkStem": "https://gtin.at",
      "primaryKey": {
        "key": "01",
        "value": "09521234543213"
      },
      "ais": [
        {
          "key": "10",
          "value": "LOT42"
        }
      ]
    }
  ]
}
'

{
  "codes": [
    {
      "reference": "product-label",
      "barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
      "hri": "(01)09521234543213(10)LOT42",
      "image": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgdmlld0JveD0iMCAwIDE4IDE4Ij48bWV0YWRhdGEgeG1sbnM6ZGM9Imh0dHA6Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIj48ZGM6Y3JlYXRvcj5UaGluZyBJZGVudGl0eTwvZGM6Y3JlYXRvcj48ZGM6c291cmNlPmh0dHBzOi8vdGhpbmdpZGVudGl0eS5jb208L2RjOnNvdXJjZT48L21ldGFkYXRhPjxyZWN0IHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgZmlsbD0iI0ZGRkZGRiIvPjxwYXRoIGZpbGw9IiMwMDAwMDAiIGQ9Ik0xLDFoMXYxaC0xek0zLDFoMXYxaC0xek01LDFoMXYxaC0xek03LDFoMXYxaC0xek05LDFoMXYxaC0xek0xMSwxaDF2MWgtMXpNMTMsMWgxdjFoLTF6TTE1LDFoMXYxaC0xek0xLDJoMnYxaC0yek01LDJoNHYxaC00ek0xMCwyaDJ2MWgtMnpNMTUsMmgydjFoLTJ6TTEsM2gxdjJoLTF6TTUsM2gxdjFoLTF6TTcsM2gydjJoLTJ6TTEyLDNoMXYxaC0xek0zLDRoMnYxaC0yek0xMCw0aDF2MWgtMXpNMTIsNGgydjFoLTJ6TTE2LDRoMXYxaC0xek0xLDVoM3YxaC0zek01LDVoMnYxaC0yek05LDVoMXYxaC0xek0xMiw1aDR2MWgtNHpNMSw2aDF2MmgtMXpNMyw2aDF2MmgtMXpNNiw2aDJ2MWgtMnpNOSw2aDJ2MWgtMnpNMTIsNmg1djFoLTV6TTYsN2gzdjFoLTN6TTExLDdoMXYxaC0xek0xNCw3aDF2MWgtMXpNMSw4aDR2MWgtNHpNNyw4aDV2MWgtNXpNMTYsOGgxdjFoLTF6TTEsOWgxdjFoLTF6TTksOWgxdjFoLTF6TTExLDloMXYxaC0xek0xMyw5aDN2MWgtM3pNMSwxMGgydjFoLTJ6TTYsMTBoMnYxaC0yek0xMCwxMGgxdjJoLTF6TTEzLDEwaDR2MWgtNHpNMSwxMWgxdjFoLTF6TTQsMTFoMXYxaC0xek04LDExaDF2MWgtMXpNMTQsMTFoMXYxaC0xek0xLDEyaDV2MWgtNXpNNywxMmgxdjFoLTF6TTksMTJoMXYxaC0xek0xMSwxMmgydjFoLTJ6TTE1LDEyaDJ2MWgtMnpNMSwxM2gydjFoLTJ6TTUsMTNoM3YxaC0zek05LDEzaDJ2MWgtMnpNMTQsMTNoMXYxaC0xek0xLDE0aDF2MWgtMXpNNCwxNGgzdjFoLTN6TTEwLDE0aDV2MWgtNXpNMTYsMTRoMXYxaC0xek0xLDE1aDJ2MWgtMnpNOCwxNWgydjFoLTJ6TTEyLDE1aDF2MWgtMXpNMTUsMTVoMXYxaC0xek0xLDE2aDE2djFoLTE2eiIvPjwvc3ZnPg=="
    }
  ],
  "errors": []
}

POST

codes

render

batch

curl --request POST \
  --url https://api.thingidentity.com/codes/render/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.thingidentity.public.v1+json' \
  --data '
{
  "codes": [
    {
      "reference": "product-label",
      "mode": "QR_GS1_DIGITAL_LINK_URI",
      "digitalLinkStem": "https://gtin.at",
      "primaryKey": {
        "key": "01",
        "value": "09521234543213"
      },
      "ais": [
        {
          "key": "10",
          "value": "LOT42"
        }
      ]
    }
  ]
}
'

{
  "codes": [
    {
      "reference": "product-label",
      "barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
      "hri": "(01)09521234543213(10)LOT42",
      "image": "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgdmlld0JveD0iMCAwIDE4IDE4Ij48bWV0YWRhdGEgeG1sbnM6ZGM9Imh0dHA6Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIj48ZGM6Y3JlYXRvcj5UaGluZyBJZGVudGl0eTwvZGM6Y3JlYXRvcj48ZGM6c291cmNlPmh0dHBzOi8vdGhpbmdpZGVudGl0eS5jb208L2RjOnNvdXJjZT48L21ldGFkYXRhPjxyZWN0IHdpZHRoPSIxOCIgaGVpZ2h0PSIxOCIgZmlsbD0iI0ZGRkZGRiIvPjxwYXRoIGZpbGw9IiMwMDAwMDAiIGQ9Ik0xLDFoMXYxaC0xek0zLDFoMXYxaC0xek01LDFoMXYxaC0xek03LDFoMXYxaC0xek05LDFoMXYxaC0xek0xMSwxaDF2MWgtMXpNMTMsMWgxdjFoLTF6TTE1LDFoMXYxaC0xek0xLDJoMnYxaC0yek01LDJoNHYxaC00ek0xMCwyaDJ2MWgtMnpNMTUsMmgydjFoLTJ6TTEsM2gxdjJoLTF6TTUsM2gxdjFoLTF6TTcsM2gydjJoLTJ6TTEyLDNoMXYxaC0xek0zLDRoMnYxaC0yek0xMCw0aDF2MWgtMXpNMTIsNGgydjFoLTJ6TTE2LDRoMXYxaC0xek0xLDVoM3YxaC0zek01LDVoMnYxaC0yek05LDVoMXYxaC0xek0xMiw1aDR2MWgtNHpNMSw2aDF2MmgtMXpNMyw2aDF2MmgtMXpNNiw2aDJ2MWgtMnpNOSw2aDJ2MWgtMnpNMTIsNmg1djFoLTV6TTYsN2gzdjFoLTN6TTExLDdoMXYxaC0xek0xNCw3aDF2MWgtMXpNMSw4aDR2MWgtNHpNNyw4aDV2MWgtNXpNMTYsOGgxdjFoLTF6TTEsOWgxdjFoLTF6TTksOWgxdjFoLTF6TTExLDloMXYxaC0xek0xMyw5aDN2MWgtM3pNMSwxMGgydjFoLTJ6TTYsMTBoMnYxaC0yek0xMCwxMGgxdjJoLTF6TTEzLDEwaDR2MWgtNHpNMSwxMWgxdjFoLTF6TTQsMTFoMXYxaC0xek04LDExaDF2MWgtMXpNMTQsMTFoMXYxaC0xek0xLDEyaDV2MWgtNXpNNywxMmgxdjFoLTF6TTksMTJoMXYxaC0xek0xMSwxMmgydjFoLTJ6TTE1LDEyaDJ2MWgtMnpNMSwxM2gydjFoLTJ6TTUsMTNoM3YxaC0zek05LDEzaDJ2MWgtMnpNMTQsMTNoMXYxaC0xek0xLDE0aDF2MWgtMXpNNCwxNGgzdjFoLTN6TTEwLDE0aDV2MWgtNXpNMTYsMTRoMXYxaC0xek0xLDE1aDJ2MWgtMnpNOCwxNWgydjFoLTJ6TTEyLDE1aDF2MWgtMXpNMTUsMTVoMXYxaC0xek0xLDE2aDE2djFoLTE2eiIvPjwvc3ZnPg=="
    }
  ],
  "errors": []
}

Render up to 10 codes in one request. The response has the same codes and errors structure as batch generation. Each successful code also contains image, the SVG document encoded as Base64.

Request

{
  "codes": [
    {
      "reference": "product-label",
      "mode": "QR_GS1_DIGITAL_LINK_URI",
      "digitalLinkStem": "https://gtin.at",
      "primaryKey": { "key": "01", "value": "09521234543213" },
      "ais": [{ "key": "10", "value": "LOT42" }]
    }
  ]
}

The same modes, optional parameters and QR correction levels as single rendering apply. QR correction defaults to L. This endpoint requires write:codes.

Compression

Set compression on individual items to EPC_BASE64 or EPC_HEX, or omit it / send null for an uncompressed URI. Compressed and uncompressed items can share a batch. The single-rendering restrictions apply: Digital Link mode, digitalLinkStem, primary key 01, serial number AI 21, and EPC-supported additional AIs.

{
  "codes": [
    {
      "reference": "compressed-qr",
      "mode": "QR_GS1_DIGITAL_LINK_URI",
      "digitalLinkStem": "https://thingidentity.com",
      "primaryKey": { "key": "01", "value": "09528765123457" },
      "ais": [{ "key": "21", "value": "123456789123" }],
      "compression": "EPC_BASE64"
    },
    {
      "reference": "compressed-data-matrix",
      "mode": "DATAMATRIX_GS1_DIGITAL_LINK_URI",
      "digitalLinkStem": "https://thingidentity.com",
      "primaryKey": { "key": "01", "value": "09528765123457" },
      "ais": [{ "key": "21", "value": "123456789123" }],
      "compression": "EPC_HEX"
    }
  ]
}

Each success contains the compressed URI in barcodeText, the unchanged GS1 data in hri, and the rendered SVG encoded as Base64 in image. An invalid compression produces an item error Validation.Invalid.compression at path compression; the batch remains 200 OK.

Results

Successful entries contain reference, barcodeText, hri and image. Decode the Base64 value in image to UTF-8 SVG bytes and save them as an .svg file. Invalid items appear in errors with reference and an errors list containing code, path and args. They do not prevent other items from rendering. The response remains 200 OK, including when all items fail. Your reference is echoed unchanged. If omitted or null, the original zero-based position is returned as a string. Empty references are preserved. More than 10 items returns 422 with Validation.TooMany.codes before any rendering starts.

Authorizations

Authorization

string

header

required

The access_token from POST /oauth/token.

Body

codes

object[]

required

Maximum array length: 10

Hide child attributes

codes.mode

enum<string>

required

Barcode type. Digital Link modes require digitalLinkStem.

Available options:

GS1_DATAMATRIX,

DATAMATRIX_GS1_DIGITAL_LINK_URI,

GS1_QR,

QR_GS1_DIGITAL_LINK_URI

Example:

"QR_GS1_DIGITAL_LINK_URI"

codes.primaryKey

object

required

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

codes.primaryKey.key

string

required

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.

Example:

"01"

codes.primaryKey.value

string

required

Example:

"09521234543213"

codes.errorCorrectionLevel

enum<string> | null

QR only: L, M, Q or H. Omitted or null selects L for QR. For Data Matrix omit or send null.

Available options:

L,

M,

Q,

H,

null

codes.ais

object[] | null

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

codes.ais.key

string

required

Example:

"01"

codes.ais.value

string

required

Example:

"09521234543213"

codes.extensionParameters

object[] | null

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.

Hide child attributes

codes.extensionParameters.key

string

required

Query parameter name. Not linkType or context, and it must contain at least one non-digit.

Example:

"batch"

codes.extensionParameters.value

string

required

Example:

"A42"

codes.digitalLinkStem

string | null

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.

Example:

"https://gtin.at"

codes.linkType

string | null

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.

Example:

"gs1:pip"

codes.context

string | null

Value for the GS1 Digital Link context query parameter. Only with a digitalLinkStem, same character rules as extension parameter values.

Example:

"dpp"

codes.compression

enum<string> | null

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.

Only available for QR_GS1_DIGITAL_LINK_URI and DATAMATRIX_GS1_DIGITAL_LINK_URI; not for GS1 element-string modes.

Available options:

EPC_BASE64,

EPC_HEX,

null

Examples:

"EPC_BASE64"

"EPC_HEX"

codes.reference

string | null

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.

Example:

"product-label"

Response

Successful codes and per-item errors. Inspect errors even when the HTTP status is 200.

codes

object[]

required

Hide child attributes

codes.reference

string

required

The supplied reference unchanged, or the zero-based input position as a string when omitted or null.

codes.barcodeText

string

required

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.

Example:

"https://gtin.at/01/09521234543213"

codes.hri

string

required

Human readable interpretation, the (AI)value text printed under the symbol. Compression does not change this value.

Example:

"(01)09521234543213"

codes.image

file

required

Base64-encoded SVG document (UTF-8).

errors

object[]

required

Hide child attributes

errors.reference

string

required

The supplied reference unchanged, or the zero-based input position as a string when omitted or null.

errors.errors

object[]

required

Hide child attributes

errors.errors.code

string

required

Validation.Invalid.<field>.

Example:

"Validation.Invalid.primaryKey"

errors.errors.args

string[]

required

errors.errors.path

string | null

The field at fault, so ais.2 is the third entry of ais.

Example:

"primaryKey"

Get Started

Guides

API Documentation

Authentication

2D Barcodes

GS1 Resolver

Request

Compression

Results

Authorizations

Body

Response

​Request

​Compression

​Results

Authorizations

Body

Response

Request

Compression

Results