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"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/vnd.thingidentity.public.v1+json'
  },
  body: JSON.stringify({
    digitalLinkStem: 'https://gtin.at',
    primaryKey: {key: '01', value: '09521234543213'},
    ais: [{key: '10', value: 'LOT42'}]
  })
};

fetch('https://api.thingidentity.com/code', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.thingidentity.com/code"

payload = {
    "digitalLinkStem": "https://gtin.at",
    "primaryKey": {
        "key": "01",
        "value": "09521234543213"
    },
    "ais": [
        {
            "key": "10",
            "value": "LOT42"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/vnd.thingidentity.public.v1+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

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

POST

code

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"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/vnd.thingidentity.public.v1+json'
  },
  body: JSON.stringify({
    digitalLinkStem: 'https://gtin.at',
    primaryKey: {key: '01', value: '09521234543213'},
    ais: [{key: '10', value: 'LOT42'}]
  })
};

fetch('https://api.thingidentity.com/code', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.thingidentity.com/code"

payload = {
    "digitalLinkStem": "https://gtin.at",
    "primaryKey": {
        "key": "01",
        "value": "09521234543213"
    },
    "ais": [
        {
            "key": "10",
            "value": "LOT42"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/vnd.thingidentity.public.v1+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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.

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.

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"

Response

Generated code.

barcodeText

string

required

Payload to encode in a 2D barcode.

hri

string

required

Human-readable interpretation of the GS1 data.

Get Started

Guides

API Documentation

Authentication

2D Barcodes

Generate 2D barcode

Example

Authorizations

Body

Response

​Example

Authorizations

Body

Response

Example