# Attach one or more manifests to the shipment (all-or-nothing batch)

All supplied manifests must exist, must be in PLANNED status, and must not be attached to another shipment. If any fails validation, the entire batch is rolled back.

Endpoint: POST /integration/rest/api/v1/shipment/{shipmentExternalId}/manifest
Version: v0
Security: X-AUTH-KEY

## Path parameters:

  - `shipmentExternalId` (string, required)
    Shipment external identifier or uuid.
    Example: "SHIP-2024-001"

## Request fields (application/json):

  - `manifests` (array, required)
    List of manifest references to attach. Exactly one of manifestExternalId / manifestUuid must be set per reference. The entire batch is rolled back on any single validation failure.

  - `manifests.manifestExternalId` (string)
    Caller-assigned manifest external identifier.

  - `manifests.manifestUuid` (string)
    Internal manifest identifier (uuid).

## Response 200 fields (*/*):

  - `createDate` (string)

  - `updateDate` (string)

  - `deepLink` (string)
    Deep link URL to open this entity in Ops.App.

  - `externalIdentifier` (string)
    Caller-assigned external identifier, unique per organization within the Shipment namespace.

  - `status` (string)
    Lifecycle status of the shipment.
    Enum: "PLANNED", "TO_DO", "IN_PROGRESS", "COMPLETED", "CANCELLED"

  - `gate` (object)
    Gate currently assigned to the shipment, if any.

  - `gate.name` (string)
    Human-readable gate name.

  - `gate.externalIdentifier` (string)
    External unique identifier of the gate.

  - `gate.status` (string)
    Current operational status of the gate.
    Enum: "AVAILABLE", "LOADING", "OUT_OF_SERVICE"

  - `gate.gateType` (string)
    Gate type. SINGLE_MANIFEST allows one active manifest at a time; MULTI_MANIFEST allows several manifests active simultaneously.
    Enum: "SINGLE_MANIFEST", "MULTI_MANIFEST"

  - `manifests` (array)
    Manifests currently attached to the shipment.

  - `manifests.uuid` (string)
    Internal manifest identifier (uuid).

  - `manifests.externalIdentifier` (string)
    Caller-assigned manifest external identifier, if any.

  - `manifests.manifestStatus` (string)
    Current manifest status.
    Enum: "PLANNED", "TO_DO", "IN_PROGRESS", "COMPLETED", "CANCELLED"

  - `tracksCount` (integer)
    Planning view: total tracks (assets) currently included across this shipment's manifests, regardless of loading state. For Total/Loaded execution counts use totalAssetsCount and loadedAssetsCount.

  - `totalAssetsCount` (integer)
    Total assets attached to the shipment, excluding invalid loadings (WRONGLY_LOADED, UNKNOWN_LOADING) and records belonging to cancelled manifests.

  - `loadedAssetsCount` (integer)
    Successfully loaded assets, excluding invalid loadings and records belonging to cancelled manifests.

  - `notes` (string)
    Optional free-text notes.

  - `activateDate` (string)
    Timestamp when the shipment transitioned to IN_PROGRESS, null if not yet activated.

  - `closeDate` (string)
    Timestamp when the shipment transitioned to a terminal status (COMPLETED or CANCELLED), null if still active.

  - `deleted` (boolean)
    Soft-delete flag. Deleted shipments are excluded from list and get endpoints.

  - `customFields` (array)
    Custom field values set on this shipment. Omitted when the organization's dispatch strategy is not SHIPMENT.

  - `customFields.fieldKey` (string, required)
    Unique key (name) of the custom field. This must match the configured field name.

  - `customFields.fieldValue` (string)
    Value of the custom field as a string. For numeric fields, send the number as a string.

## Response 400 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

  - `errors` (array)
    Per-item failure list for batch manifest attach/detach operations. The whole batch is rolled back when this list is non-empty.

  - `errors.identifier` (string)
    Identifier of the failed batch item as supplied by the caller (external id or uuid).

  - `errors.code` (string)
    Stable error code for programmatic handling, e.g. NOT_FOUND, INVALID_STATUS, ALREADY_IN_SHIPMENT, DUPLICATE, REFERENCE_INVALID.

  - `errors.message` (string)
    Human-readable explanation of why this item failed.

## Response 403 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 404 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