# Couple a zimarker code to a new track

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).

Endpoint: POST /integration/rest/api/v1/track/couple
Version: v0
Security: X-AUTH-KEY

## Query parameters:

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

## Request fields (application/json):

  - `markerCode` (string, required)
    The zimarker code to couple.
    Example: 123456

  - `wmsId` (string, required)
    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"

  - `customFields` (array)
    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.

  - `customFields.fieldKey` (string, required)
    System key (name) of the custom field; must match a configured field.
    Example: "CARRIER"

  - `customFields.fieldValue` (string)
    Value to set. For NUMERIC fields send the number as a string; for DATE fields send an ISO-8601 date-time. A blank/null value clears the existing value.
    Example: "DHL Express"

## Response 400 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 403 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 500 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id