Generate 2D barcode

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

{
  "barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
  "hri": "(01)09521234543213(10)LOT42"
}

{
  "errors": [
    {
      "code": "Validation.Invalid.primaryKey",
      "path": "primaryKey"
    }
  ]
}

POST

code

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

{
  "barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
  "hri": "(01)09521234543213(10)LOT42"
}

{
  "errors": [
    {
      "code": "Validation.Invalid.primaryKey",
      "path": "primaryKey"
    }
  ]
}

Example

{
  "digitalLinkStem": "https://gtin.at",
  "primaryKey": { "key": "01", "value": "09521234543213" },
  "ais": [{ "key": "10", "value": "LOT42" }]
}

{
  "barcodeText": "https://gtin.at/01/09521234543213/10/LOT42",
  "hri": "(01)09521234543213(10)LOT42"
}

Supply digitalLinkStem for a GS1 Digital Link URI, or omit it for a GS1 element string. ais and extensionParameters are optional and treated as empty lists when omitted or null. linkType and context are optional. Choose identifiers from the GS1 Application Identifiers directory. For linkType values, see the GS1 Web Vocabulary. The endpoint requires write:codes. Invalid definitions return 422 with JSON validation details. For multiple definitions in one request, use Batch Generate 2D barcodes. To download an SVG, use Render 2D barcode.

Compression

Set compression to encode a serialised GTIN in an EPC path:

Value	URI path
`EPC_BASE64`	`ex` followed by EPC binary encoded in URL-safe Base64.
`EPC_HEX`	`eh` followed by EPC binary encoded in hexadecimal.
Omitted or `null`	Uncompressed GS1 Digital Link URI.

Compression requires digitalLinkStem, primary key 01 (GTIN), and AI 21 (serial number). 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. The hri value stays unchanged. Example request:

{
  "digitalLinkStem": "https://thingidentity.com",
  "primaryKey": { "key": "01", "value": "09528765123457" },
  "ais": [{ "key": "21", "value": "123456789123" }],
  "compression": "EPC_BASE64"
}

Example response:

{
  "barcodeText": "https://thingidentity.com/ex9xCVKHZRI0VwwcvpkagwAA",
  "hri": "(01)09528765123457(21)123456789123"
}

An unknown compression value, a missing serial number, a primary key other than 01, or one of the AIs listed above returns 422 with Validation.Invalid.compression at path compression. Compression cannot be used for a GS1 element string.

Authorizations

Authorization

string

header

required

The access_token from POST /oauth/token.

Body

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

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"

primaryKey.value

string

required

Example:

"09521234543213"

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

ais.key

string

required

Example:

"01"

ais.value

string

required

Example:

"09521234543213"

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

extensionParameters.key

string

required

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

Example:

"batch"

extensionParameters.value

string

required

Example:

"A42"

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"

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"

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"

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.

Available options:

EPC_BASE64,

EPC_HEX,

null

Examples:

"EPC_BASE64"

"EPC_HEX"

Response

Generated code.

barcodeText

string

required

Payload to encode in a 2D barcode. With compression, this is the URI with an EPC ex or eh path.

hri

string

required

Human-readable interpretation of the GS1 data. Compression does not change this value.

Get Started

Guides

API Documentation

Authentication

2D Barcodes

GS1 Resolver

Example

Compression

Authorizations

Body

Response

​Example

​Compression

Authorizations

Body

Response

Example

Compression