> ## 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.mode", "path": "mode", "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.mode` | `mode` is not one of the four supported values. | | `Validation.Invalid.primaryKey` | Unknown AI, an AI this mode does not accept as a primary key, 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 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` | Missing in a Digital Link mode, or not an acceptable origin. | | `Validation.Invalid.linkType` | Not an offered `gs1:` link type and not an absolute HTTP(S) URI. | | `Validation.Invalid.extensionParameters` | Sent in an element string mode, 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' application/json: schema: $ref: '#/components/schemas/CodesRequest' 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' application/json: schema: $ref: '#/components/schemas/CodesResponse' '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: - mode - 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 mode: type: string enum: - GS1_QR - GS1_DATAMATRIX - QR_GS1_DIGITAL_LINK_URI - DATAMATRIX_GS1_DIGITAL_LINK_URI description: >- Which symbol and payload format to build. `GS1_QR` and `GS1_DATAMATRIX` produce a GS1 element string; the two `..._DIGITAL_LINK_URI` values produce a GS1 Digital Link URI and are referred to below as Digital Link modes. primaryKey: allOf: - $ref: '#/components/schemas/Ai' description: >- The identifying application identifier. In Digital Link modes it must be a Digital Link primary key in the GS1 Barcode Syntax Dictionary; element string modes additionally accept `03`, 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. In Digital Link modes 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 Digital Link URI. Pass `[]` for none. Digital Link modes only; a non-empty list in an element string mode 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/Ai' digitalLinkStem: type: - string - 'null' description: >- The origin the Digital Link path is appended to. Required in Digital Link modes, ignored otherwise. 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. Digital Link modes only. 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 Digital Link `context` query parameter. Digital Link modes only, same character rules as extension parameter values. language: type: - string - 'null' description: Locale tag for the code. Recorded as sent and not validated. examples: - en-us GeneratedCode: type: object required: - reference - mode - primaryKey - barcodeText - hri properties: reference: type: string description: >- The supplied reference unchanged, or the zero-based input position as a string when omitted or null. mode: type: string primaryKey: $ref: '#/components/schemas/Ai' barcodeText: type: string description: >- The payload to encode. For Digital Link modes the URI; for element string modes the AI 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?linkType=gs1%3Apip 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.mode path: type: - string - 'null' description: The field at fault, so `ais.2` is the third entry of `ais`. examples: - mode 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' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: The `access_token` from `POST /oauth/token`. ````