Skip to content
/
Allocate one or a batch o...

Zimark Integration API (v0)

Download OpenAPI description
api.json
api.yaml
Languages
Servers
Mock server

https://docs.zimark.link/_mock/api/

https://{organizationSubdomain}.zimark-staging.link/

https://{organizationSubdomain}.zimark.link/

Zimarker

Allocate zimarker code(s) on demand for the calling organization, each with a printable, inline base64 marker image. Allocation is synchronous, atomic, and exactly-once per organization.

Render a zimarker code's marker image on demand. Public, stateless, and addressable by code at a stable URL — no authentication required.

Operations

Allocate one or a batch of zimarker codes

Request

Allocates the next unassigned zimarker code(s) for the calling organization. quantity defaults to 1 when omitted; quantity greater than 1 allocates a batch, reserved atomically as a single block (all-or-nothing). quantity is capped at a configurable maximum batch size. Returns an ordered list of allocated entries, each with the marker code and its marker image. imageDelivery selects the image form: BASE64 (default) returns a 1-bit, 600x600 black-and-white PNG inline as base64 in markerImage; URL returns the marker's public image URL in markerImageUrl instead of inline bytes.

Security
X-AUTH-KEY
Query
quantityinteger(int32)

Number of codes to allocate. Defaults to 1 when omitted.

Example: quantity=1
imageDeliverystring

Marker image delivery form: BASE64 (default) returns the image inline as base64 in markerImage; URL returns the public image URL in markerImageUrl.

Enum"BASE64""URL"
curl -i -X POST \
  'https://docs.zimark.link/_mock/api/integration/rest/api/v1/zmarker-code/allocate?quantity=1&imageDelivery=BASE64' \
  -H 'X-AUTH-KEY: YOUR_API_KEY_HERE'

Responses

OK

Body*/*Array [
markerCodestring

The allocated zimarker code.

Example: 123456
markerImagestring

The marker rendered as a 1-bit, 600x600 black-and-white PNG, base64-encoded (inline). Present only when imageDelivery is BASE64 (the default).

markerImageUrlstring

The marker image's public, stable URL ({base-path}/{markerCode}.png). Present only when imageDelivery is URL.

Example: "https://acme.zimark.link/integration/rest/api/v1/zmarker-code/image/123456.png"
]

Allocate a zimarker code and couple it in one call

Request

Allocates the next zimarker code for the calling organization (always synchronous) and couples it to a new track. The synchronous variant (async=false, default) additionally waits for coupling and returns the resulting track alongside the allocated code and its marker image with 200. The asynchronous variant (async=true) couples in the background and returns 202 with the allocated code, its marker image and an operation identifier (no track). imageDelivery selects the image form: BASE64 (default) returns the marker inline as base64 in markerImage; URL returns its public image URL in markerImageUrl instead of inline bytes. The supplied WMS identifier is stored as-is and NOT validated against any WMS connector.

Security
X-AUTH-KEY
Query
asyncboolean

When true, couple in the background and return 202 with the allocated code, image and an operation identifier; when false (default), wait and return 200 with the track too.

Default false
imageDeliverystring

Marker image delivery form: BASE64 (default) returns the image inline as base64 in markerImage; URL returns the public image URL in markerImageUrl.

Enum"BASE64""URL"
Bodyapplication/jsonrequired
wmsIdstring[ 0 .. 512 ] charactersrequired

External asset identifier (WMS id) stored on the track. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.

Example: "PAL-001"
customFieldsArray of objects(TrackCustomFieldUpsertV1Dto)

Custom field values to set on the track. Each fieldKey must match a configured track custom field; unknown keys are rejected with CUSTOM_FIELD_MISSING.

curl -i -X POST \
  'https://docs.zimark.link/_mock/api/integration/rest/api/v1/track/get-and-couple?async=false&imageDelivery=BASE64' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "wmsId": "PAL-001",
    "customFields": [
      {
        "fieldKey": "CARRIER",
        "fieldValue": "DHL Express"
      }
    ]
  }'

Responses

Ok (synchronous): allocated code, image and track

Body*/*
markerCodestring

The allocated zimarker code.

Example: 123456
markerImagestring

The allocated marker rendered as a 1-bit, 600x600 black-and-white PNG, base64-encoded (inline). Present only when imageDelivery is BASE64 (the default).

markerImageUrlstring

The allocated marker image's public, stable URL ({base-path}/{markerCode}.png). Present only when imageDelivery is URL.

Example: "https://acme.zimark.link/integration/rest/api/v1/zmarker-code/image/123456.png"
trackobject(TrackV1Dto)

The resulting coupled track (standard integration track representation). Present only on the synchronous variant; omitted on the asynchronous variant, which couples in the background.

operationIdstring

Operation identifier correlating the eventual coupling outcome (delivered via the COUPLING_SUCCEEDED / COUPLING_FAILED webhook) to this request. Present only on the asynchronous variant.

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Couple a zimarker code to a new track

Request

Couples an existing zimarker code with a WMS identifier and the track's custom fields, creating a new track. The synchronous variant (async=false, default) waits for coupling and returns the resulting track with 200. The asynchronous variant (async=true) validates up front, then couples in the background and returns 202 with an operation identifier correlating the outcome (delivered via the COUPLING_SUCCEEDED / COUPLING_FAILED webhook). The supplied WMS identifier is stored as the track's external asset identifier and is NOT validated against any WMS connector. Existing coupling rules and concurrency safeguards apply (marker uniqueness, the already-coupled rule, duplicate-creation protection).

Security
X-AUTH-KEY
Query
asyncboolean

When true, couple in the background and return 202 with an operation identifier; when false (default), wait and return 200 with the track.

Default false
Bodyapplication/jsonrequired
markerCodestring[ 0 .. 512 ] charactersrequired

The zimarker code to couple.

Example: 123456
wmsIdstring[ 0 .. 512 ] charactersrequired

External asset identifier (WMS id) stored on the track. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.

Example: "PAL-001"
customFieldsArray of objects(TrackCustomFieldUpsertV1Dto)

Custom field values to set on the track. Each fieldKey must match a configured track custom field; unknown keys are rejected with CUSTOM_FIELD_MISSING.

curl -i -X POST \
  'https://docs.zimark.link/_mock/api/integration/rest/api/v1/track/couple?async=false' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "markerCode": 123456,
    "wmsId": "PAL-001",
    "customFields": [
      {
        "fieldKey": "CARRIER",
        "fieldValue": "DHL Express"
      }
    ]
  }'

Responses

Ok (synchronous): the resulting track

Body*/*
object

Render a zimarker code's marker image (PNG)

Request

Returns the marker for the given zimarker code as a 1-bit, 600x600 black-and-white PNG, identical to the image the allocation endpoint returns inline for that code. Public (no authentication), stateless, and deterministic — the same code always yields the same image.

Security
X-AUTH-KEY
Path
codestringrequired

The zimarker code to render.

Example: 123456
curl -i -X GET \
  https://docs.zimark.link/_mock/api/integration/rest/api/v1/zmarker-code/image/123456.png \
  -H 'X-AUTH-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyimage/png

Manifest

API endpoints for managing manifests and their associated assets/tracks.

A manifest is a container that groups assets/pallets for tracking purposes.

Operations

Shipment

API endpoints for managing shipments (multi-manifest dispatch grouping). A shipment groups one or more manifests for dispatch at a single gate; only available to organizations configured with the shipment dispatch strategy.

Operations

Track

Operations

Gate

Operations

Client

Operations

Scanner

Operations

Printing Batch

Operations

Agent

Operations

Local Manager

Operations

User

Operations

Audit Log

Operations

Alert Events

Operations

Calibration Integration

External API for integration systems with token-based authentication

Operations

Bulk Upsert Management

Operations
Copyright 2026 Zimark Inc © All rights reserved.