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://api.zimark-staging.link/

https://api.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 pallet. The synchronous variant (async=false, default) additionally waits for coupling and returns the resulting pallet 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 pallet). 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 pallet 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 pallet. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.

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

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

curl -i -X POST \
  'https://docs.zimark.link/_mock/api/integration/rest/api/v1/pallet/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 pallet

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"
palletobject(PalletV1Dto)

The resulting coupled pallet (standard integration pallet 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"
trackobject(PalletV1Dto)Deprecated

Pallet resource exposed via the integration API.

Couple a zimarker code to a new pallet

Request

Couples an existing zimarker code with a WMS identifier and the pallet's custom fields, creating a new pallet. The synchronous variant (async=false, default) waits for coupling and returns the resulting pallet 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 pallet'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 pallet.

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 pallet. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.

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

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

curl -i -X POST \
  'https://docs.zimark.link/_mock/api/integration/rest/api/v1/pallet/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 pallet

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

Allocate a zimarker code and couple it in one callDeprecated

Request

Deprecated: legacy /track alias of POST /integration/rest/api/v1/pallet/get-and-couple, kept for backward compatibility and will be removed in a future release. Use that endpoint instead; request and response are identical.

Allocates the next zimarker code for the calling organization (always synchronous) and couples it to a new pallet. The synchronous variant (async=false, default) additionally waits for coupling and returns the resulting pallet 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 pallet). 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 pallet 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 pallet. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.

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

Custom field values to set on the pallet. Each fieldKey must match a configured pallet 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 pallet

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"
palletobject(PalletV1Dto)

The resulting coupled pallet (standard integration pallet 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"
trackobject(PalletV1Dto)Deprecated

Pallet resource exposed via the integration API.

Couple a zimarker code to a new palletDeprecated

Request

Deprecated: legacy /track alias of POST /integration/rest/api/v1/pallet/couple, kept for backward compatibility and will be removed in a future release. Use that endpoint instead; request and response are identical.

Couples an existing zimarker code with a WMS identifier and the pallet's custom fields, creating a new pallet. The synchronous variant (async=false, default) waits for coupling and returns the resulting pallet 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 pallet'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 pallet.

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 pallet. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.

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

Custom field values to set on the pallet. Each fieldKey must match a configured pallet 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 pallet

Body*/*
object

Manifest

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

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

Pallet

The /track/… paths are deprecated aliases of the /pallet/… endpoints, kept for backward compatibility. They will be removed in a future release; use /pallet/… for new integrations.

Operations

Gate

Operations

Client

Operations

Bulk Upsert Management

Operations

Audit Log

Operations

Alert Events

Operations

Printing Batch

Operations
Copyright 2026 Zimark Inc © All rights reserved.