> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thingidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate 2D barcode

> Generate the payload and human-readable interpretation for one 2D barcode.

## Example

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

```json theme={null}
{
  "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](https://ref.gs1.org/ai/).
For `linkType` values, see the [GS1 Web Vocabulary](https://ref.gs1.org/voc/).

The endpoint requires `write:codes`. Invalid definitions return `422` with JSON validation details.
For multiple definitions in one request, use
[Batch Generate 2D barcodes](/api-reference/endpoints/generate-codes).
To download an SVG, use [Render 2D barcode](/api-reference/endpoints/render-code).


## OpenAPI

````yaml openapi.json POST /code
openapi: 3.1.0
info:
  title: Thing Identity Public API
  version: 1.0.0
  description: >-
    Machine-to-machine API for Thing Identity. Authenticate with client
    credentials, then call the endpoints below with the resulting bearer token.
servers:
  - url: https://api.thingidentity.com
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Exchange client credentials for an access token.
  - name: Codes
    description: Generate GS1 barcode payloads and GS1 Digital Link URIs.
paths:
  /code:
    post:
      tags:
        - Codes
      summary: Generate 2D barcode
      description: >-
        Generate the payload and human-readable interpretation for one 2D
        barcode.
      operationId: generateSingleCode
      requestBody:
        required: true
        content:
          application/vnd.thingidentity.public.v1+json:
            schema:
              $ref: '#/components/schemas/GenerateSingleCodeRequest'
            example:
              digitalLinkStem: https://gtin.at
              primaryKey:
                key: '01'
                value: '09521234543213'
              ais:
                - key: '10'
                  value: LOT42
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSingleCodeRequest'
            example:
              digitalLinkStem: https://gtin.at
              primaryKey:
                key: '01'
                value: '09521234543213'
              ais:
                - key: '10'
                  value: LOT42
      responses:
        '200':
          description: Generated code.
          content:
            application/vnd.thingidentity.public.v1+json:
              schema:
                $ref: '#/components/schemas/GenerateSingleCodeResponse'
              example:
                barcodeText: https://gtin.at/01/09521234543213/10/LOT42
                hri: (01)09521234543213(10)LOT42
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateSingleCodeResponse'
              example:
                barcodeText: https://gtin.at/01/09521234543213/10/LOT42
                hri: (01)09521234543213(10)LOT42
        '400':
          description: Malformed request or missing primaryKey.
        '401':
          description: Missing or invalid bearer token.
        '403':
          description: Token lacks write:codes or API access.
        '422':
          description: Invalid GS1 definition.
          content:
            application/vnd.thingidentity.public.v1+json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                errors:
                  - code: Validation.Invalid.primaryKey
                    path: primaryKey
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                errors:
                  - code: Validation.Invalid.primaryKey
                    path: primaryKey
components:
  schemas:
    GenerateSingleCodeRequest:
      type: object
      required:
        - primaryKey
      example:
        digitalLinkStem: https://gtin.at
        primaryKey:
          key: '01'
          value: '09521234543213'
        ais:
          - key: '10'
            value: LOT42
      properties:
        primaryKey:
          allOf:
            - $ref: '#/components/schemas/Ai'
          description: >-
            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.
        ais:
          type:
            - array
            - 'null'
          description: >-
            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.
          items:
            $ref: '#/components/schemas/Ai'
        extensionParameters:
          type:
            - array
            - 'null'
          description: >-
            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.
          items:
            $ref: '#/components/schemas/ExtensionParameter'
        digitalLinkStem:
          type:
            - string
            - 'null'
          description: >-
            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.
          examples:
            - https://gtin.at
        linkType:
          type:
            - string
            - 'null'
          description: >-
            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](https://ref.gs1.org/voc/) page types;
            `gs1:defaultPage`, `gs1:defaultPageMulti` and `gs1:handledBy` are
            not selectable. Any other value must be an absolute `http` or
            `https` URI.
          examples:
            - gs1:pip
        context:
          type:
            - string
            - 'null'
          description: >-
            Value for the GS1 Digital Link `context` query parameter. Only with
            a `digitalLinkStem`, same character rules as extension parameter
            values.
          examples:
            - dpp
    GenerateSingleCodeResponse:
      type: object
      required:
        - barcodeText
        - hri
      properties:
        barcodeText:
          type: string
          description: Payload to encode in a 2D barcode.
        hri:
          type: string
          description: Human-readable interpretation of the GS1 data.
    ErrorEnvelope:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - code
            properties:
              code:
                type: string
                examples:
                  - Forbidden
              path:
                type:
                  - string
                  - 'null'
                description: >-
                  The offending field when the error is about input, `null`
                  otherwise.
              message:
                type: string
    Ai:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: >-
            GS1 application identifier. Browse the official [GS1 Application
            Identifiers directory](https://ref.gs1.org/ai/) 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.
          examples:
            - '01'
        value:
          type: string
          examples:
            - '09521234543213'
    ExtensionParameter:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: >-
            Query parameter name. Not `linkType` or `context`, and it must
            contain at least one non-digit.
          examples:
            - batch
        value:
          type: string
          examples:
            - A42
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The `access_token` from `POST /oauth/token`.

````