Print API

Supported integration surface

The documented external integration is POST /v2/jobs. It accepts a saved template ID, printer route, format, orientation, copy count, and dynamic data.

Other API routes are used by the Labels web application and Print Agent. Treat them as internal unless your deployment contract explicitly exposes them.

Obtain an access token

1. 1

   Copy the integration config

   Record the token URL, audience, scope, tenant ID, print endpoint, API key, and one-time API secret.

2. 2

   Request a client-credentials token

   Send the API key as client_id and API secret as client_secret to the token URL shown in the integration configuration.

3. 3

   Keep the token short-lived

   Cache it only until expiry, then request a new one. Never put the API secret in a URL or log.

curl --request POST "$DOORMAN_TOKEN_URL" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$LABELS_API_KEY" \
  --data-urlencode "client_secret=$LABELS_API_SECRET" \
  --data-urlencode "audience=$DOORMAN_AUDIENCE" \
  --data-urlencode "scope=$DOORMAN_SCOPE"

Request headers

Print-job payload

Validate without printing

Send the same payload to POST /v2/jobs/validate before enqueueing. It verifies payload shape, workspace access, template, printer routing, agent assignment, and dynamic field names.

Validation is non-destructive: it does not create or print a job and does not consume print allowance. Review its missing and unknown field warnings before production use.

curl --request POST "$LABELS_API_BASE/v2/jobs/validate" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "x-tenant: $LABELS_TENANT_ID" \
  --data @print-job.json

Enqueue a job

With dynamic data the successful response is an array containing the queued job ID. A template-only request can return a single job ID. Store the returned ID for support and status correlation.

curl --request POST "$LABELS_PRINT_ENDPOINT" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "x-tenant: $LABELS_TENANT_ID" \
  --header "Idempotency-Key: shipment-2026-0042" \
  --data '{
    "idT": "template-id",
    "printerId": "printer-id",
    "printer": "Production Printer",
    "format": "100 x 50 mm",
    "orientation": "landscape",
    "numberCopies": 1,
    "data": [
      {
        "batch": "A1",
        "lotNumber": "LOT-2026-0042"
      }
    ]
  }'

Common responses