> ## 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 codes > 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 `failures` rather than the status code. Requires the `write:codes` scope. ## Partial success Every item of a batch is validated on its own, so a rejected item does not fail the request. The status stays `200 OK` even when every item was rejected and `codes` comes back empty, which means you should **check `failures` 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 `failures`. 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. ```json theme={null} { "codes": [], "failures": [ { "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.` | 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..digitalLink` | The AI is neither a qualifier of the primary key nor a permitted GS1 Digital Link data attribute. | | `Validation.Invalid.relations..requires` | The AI requires another AI that is absent. | | `Validation.Invalid.relations..excludes.` | 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.` | Reserved or malformed key, or a value outside the allowed characters. | | `Validation.Invalid.context` | Value outside the allowed characters. | ## OpenAPI ````yaml openapi.json POST /codes 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: /codes: post: tags: - Codes summary: Generate codes description: >- 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 `failures` rather than the status code. Requires the `write:codes` scope. operationId: generateCodes requestBody: required: true content: application/vnd.thingidentity.public.v1+json: schema: $ref: '#/components/schemas/CodesRequest' example: codes: - reference: gs1-digital-link-product digitalLinkStem: https://gtin.at primaryKey: key: '01' value: '09521234543213' ais: - key: '10' value: LOT42 extensionParameters: - key: batch value: A42 linkType: null context: null - reference: datamatrix-product primaryKey: key: '01' value: '09521234543213' ais: - key: '10' value: LOT42 extensionParameters: [] linkType: null context: null application/json: schema: $ref: '#/components/schemas/CodesRequest' example: codes: - reference: gs1-digital-link-product digitalLinkStem: https://gtin.at primaryKey: key: '01' value: '09521234543213' ais: - key: '10' value: LOT42 extensionParameters: - key: batch value: A42 linkType: null context: null - reference: datamatrix-product primaryKey: key: '01' value: '09521234543213' ais: - key: '10' value: LOT42 extensionParameters: [] linkType: null context: null responses: '200': description: >- Generated codes in `codes`, rejected definitions in `failures`. Both carry `reference`, which ties an entry back to the item you sent. content: application/vnd.thingidentity.public.v1+json: schema: $ref: '#/components/schemas/CodesResponse' example: codes: - reference: gs1-digital-link-product barcodeText: https://gtin.at/01/09521234543213/10/LOT42?batch=A42 hri: (01)09521234543213(10)LOT42 - reference: datamatrix-product barcodeText: (01)09521234543213(10)LOT42 hri: (01)09521234543213(10)LOT42 failures: [] application/json: schema: $ref: '#/components/schemas/CodesResponse' example: codes: - reference: gs1-digital-link-product barcodeText: https://gtin.at/01/09521234543213/10/LOT42?batch=A42 hri: (01)09521234543213(10)LOT42 - reference: datamatrix-product barcodeText: (01)09521234543213(10)LOT42 hri: (01)09521234543213(10)LOT42 failures: [] '400': description: The body is not valid JSON, or a required field is absent. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing, malformed or expired token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: The token lacks the `write:codes` scope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: CodesRequest: type: object required: - codes properties: codes: type: array description: >- The definitions to generate. Items are processed in order and each one is validated on its own. items: $ref: '#/components/schemas/CodeDefinition' CodesResponse: type: object required: - codes - failures properties: codes: type: array items: $ref: '#/components/schemas/GeneratedCode' failures: type: array items: $ref: '#/components/schemas/GenerateCodeFailure' 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 CodeDefinition: type: object required: - primaryKey - ais - extensionParameters properties: reference: type: - string - 'null' description: >- 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. examples: - product-label 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 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 description: >- Custom query parameters appended to a GS1 Digital Link URI. 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 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 GeneratedCode: type: object required: - reference - barcodeText - hri properties: reference: type: string description: >- The supplied reference unchanged, or the zero-based input position as a string when omitted or null. barcodeText: type: string description: >- 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. examples: - https://gtin.at/01/09521234543213 hri: type: string description: >- Human readable interpretation, the `(AI)value` text printed under the symbol. examples: - (01)09521234543213 GenerateCodeFailure: type: object required: - reference - errors properties: reference: type: string description: >- The supplied reference unchanged, or the zero-based input position as a string when omitted or null. errors: type: array items: type: object required: - code - args properties: code: type: string description: '`Validation.Invalid.`.' examples: - Validation.Invalid.primaryKey path: type: - string - 'null' description: The field at fault, so `ais.2` is the third entry of `ais`. examples: - primaryKey args: type: array items: type: string Ai: type: object required: - key - value properties: key: type: string description: GS1 application identifier. 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`. ````