Import shipments (JSON)

# Every accepted field. Required fields carry real values; optional fields are
# shown with their empty default. The four date fields (quoteDate, pickupDate,
# completedDate, expectedCompletedDate) are ISO-8601 validated, so use null (or
# omit) when blank — an empty string is rejected. Each item needs a real itemType.
curl -X POST https://api.dyspach.com/v1/org/shipments/imports \
  -H "x-api-key: $DYSPACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDetails": "",
    "shipments": [
      {
        "shipmentId": "SHIP-0001",
        "customerId": "",
        "originPostCode": "3000",
        "originSuburb": "Melbourne",
        "originState": "VIC",
        "originCountryCode": "AU",
        "originCompanyName": "",
        "originContactName": "",
        "originContactPhone": "",
        "originContactEmail": "",
        "originAddressStreet1": "",
        "originAddressStreet2": "",
        "originAddressStreet3": "",
        "originLocationType": "",
        "originRequiresTailLift": false,
        "destinationPostCode": "2000",
        "destinationSuburb": "Sydney",
        "destinationState": "NSW",
        "destinationCountryCode": "AU",
        "destinationCompanyName": "",
        "destinationContactName": "",
        "destinationContactPhone": "",
        "destinationContactEmail": "",
        "destinationAddressStreet1": "",
        "destinationAddressStreet2": "",
        "destinationAddressStreet3": "",
        "destinationLocationType": "",
        "destinationRequiresTailLift": false,
        "destinationGivesAuthorityToLeave": false,
        "destinationSignatureOnGlass": false,
        "quoteDate": null,
        "pickupDate": null,
        "completedDate": null,
        "expectedCompletedDate": null,
        "rateCardAlias": "",
        "totalCostReceived": 0,
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customFields": {},
        "items": [
          {
            "itemType": "Carton/Box",
            "itemId": "",
            "itemQuantity": 0,
            "itemPalletSpaces": 0,
            "itemLength": 0,
            "itemWidth": 0,
            "itemHeight": 0,
            "itemWeight": 0,
            "itemChargeableWeight": 0,
            "itemVolumetricWeight": 0,
            "itemValue": 0,
            "dangerousGoods": false,
            "customFields": {}
          }
        ]
      }
    ]
  }'

{
  "received": 2,
  "created": 1,
  "updated": 0,
  "failed": 1,
  "results": [
    { "shipmentId": "CONN-88213", "status": "created" },
    { "shipmentId": "CONN-88214", "status": "failed", "error": "Destination Zone(s) not found" }
  ]
}

{
  "statusCode": 400,
  "message": ["shipments.0.items should not be empty"],
  "error": "Bad Request"
}

# Every accepted field. Required fields carry real values; optional fields are
# shown with their empty default. The four date fields (quoteDate, pickupDate,
# completedDate, expectedCompletedDate) are ISO-8601 validated, so use null (or
# omit) when blank — an empty string is rejected. Each item needs a real itemType.
curl -X POST https://api.dyspach.com/v1/org/shipments/imports \
  -H "x-api-key: $DYSPACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDetails": "",
    "shipments": [
      {
        "shipmentId": "SHIP-0001",
        "customerId": "",
        "originPostCode": "3000",
        "originSuburb": "Melbourne",
        "originState": "VIC",
        "originCountryCode": "AU",
        "originCompanyName": "",
        "originContactName": "",
        "originContactPhone": "",
        "originContactEmail": "",
        "originAddressStreet1": "",
        "originAddressStreet2": "",
        "originAddressStreet3": "",
        "originLocationType": "",
        "originRequiresTailLift": false,
        "destinationPostCode": "2000",
        "destinationSuburb": "Sydney",
        "destinationState": "NSW",
        "destinationCountryCode": "AU",
        "destinationCompanyName": "",
        "destinationContactName": "",
        "destinationContactPhone": "",
        "destinationContactEmail": "",
        "destinationAddressStreet1": "",
        "destinationAddressStreet2": "",
        "destinationAddressStreet3": "",
        "destinationLocationType": "",
        "destinationRequiresTailLift": false,
        "destinationGivesAuthorityToLeave": false,
        "destinationSignatureOnGlass": false,
        "quoteDate": null,
        "pickupDate": null,
        "completedDate": null,
        "expectedCompletedDate": null,
        "rateCardAlias": "",
        "totalCostReceived": 0,
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customFields": {},
        "items": [
          {
            "itemType": "Carton/Box",
            "itemId": "",
            "itemQuantity": 0,
            "itemPalletSpaces": 0,
            "itemLength": 0,
            "itemWidth": 0,
            "itemHeight": 0,
            "itemWeight": 0,
            "itemChargeableWeight": 0,
            "itemVolumetricWeight": 0,
            "itemValue": 0,
            "dangerousGoods": false,
            "customFields": {}
          }
        ]
      }
    ]
  }'

{
  "received": 2,
  "created": 1,
  "updated": 0,
  "failed": 1,
  "results": [
    { "shipmentId": "CONN-88213", "status": "created" },
    { "shipmentId": "CONN-88214", "status": "failed", "error": "Destination Zone(s) not found" }
  ]
}

{
  "statusCode": 400,
  "message": ["shipments.0.items should not be empty"],
  "error": "Bad Request"
}

POST /v1/org/shipments/imports

Send up to 100 shipments in one call, in the published structure, and get the outcome in the same response — no polling, no second call. By the time this returns, the shipments are in the ledger and you have a verdict for each one. Sized for how partners actually integrate: a step in your manifest-close flow, or an end-of-day scheduled job. For bigger runs send a file, which is queued instead.

Sending the same shipment twice is safe. A shipmentId already in the ledger is updated, not duplicated — its goods lines are replaced by the ones you send. Retries, re-runs and corrected re-sends all do the right thing.

Authorization

string

required

Your organisation API key (dzk_live_…).

Body

Shipment[]

required

1–100 shipments. See Shipment structure for every field. Each shipment needs at least one entry in items, at most 500, and the batch as a whole may carry at most 10,000 goods lines — send bigger runs as a file.

string

Your own reference for this push — a batch id, run date or filename. It is echoed on the import and recorded against every shipment it creates, so a shipment can be traced back to the run that sent it.

Unknown fields are rejected, not ignored. If you send weight where the structure says itemWeight, you get a 400 naming the field rather than a shipment that silently lost its weight.

Response

200 OK — the shipments are written.

Field	Description
`received`	Shipments in your request
`created`	Shipments new to the ledger
`updated`	Shipments that already existed and were replaced
`failed`	Shipments rejected — each one’s reason is in `results`
`results`	One entry per shipment: `created`, `updated` or `failed` (+ `error`)

created and updated both mean the shipment is in the ledger; only failed needs action. Valid shipments are never held back because others in the batch were wrong. There is no import id to poll: this response is the outcome. Your customer still sees the submission in their Dyspach Activity Center, and your own sourceDetails is recorded against every shipment, so a specific push can always be traced back later.

Errors

Status	When
`400`	Malformed body, more than 100 shipments, more than 10,000 goods lines in total, more than 500 lines on one shipment, a shipment with no items, an unrecognised field, or a custom field key your organisation has not configured
`401`	Missing or invalid API key
`429`	Rate limit exceeded — see Rate limits

# Every accepted field. Required fields carry real values; optional fields are
# shown with their empty default. The four date fields (quoteDate, pickupDate,
# completedDate, expectedCompletedDate) are ISO-8601 validated, so use null (or
# omit) when blank — an empty string is rejected. Each item needs a real itemType.
curl -X POST https://api.dyspach.com/v1/org/shipments/imports \
  -H "x-api-key: $DYSPACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDetails": "",
    "shipments": [
      {
        "shipmentId": "SHIP-0001",
        "customerId": "",
        "originPostCode": "3000",
        "originSuburb": "Melbourne",
        "originState": "VIC",
        "originCountryCode": "AU",
        "originCompanyName": "",
        "originContactName": "",
        "originContactPhone": "",
        "originContactEmail": "",
        "originAddressStreet1": "",
        "originAddressStreet2": "",
        "originAddressStreet3": "",
        "originLocationType": "",
        "originRequiresTailLift": false,
        "destinationPostCode": "2000",
        "destinationSuburb": "Sydney",
        "destinationState": "NSW",
        "destinationCountryCode": "AU",
        "destinationCompanyName": "",
        "destinationContactName": "",
        "destinationContactPhone": "",
        "destinationContactEmail": "",
        "destinationAddressStreet1": "",
        "destinationAddressStreet2": "",
        "destinationAddressStreet3": "",
        "destinationLocationType": "",
        "destinationRequiresTailLift": false,
        "destinationGivesAuthorityToLeave": false,
        "destinationSignatureOnGlass": false,
        "quoteDate": null,
        "pickupDate": null,
        "completedDate": null,
        "expectedCompletedDate": null,
        "rateCardAlias": "",
        "totalCostReceived": 0,
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customFields": {},
        "items": [
          {
            "itemType": "Carton/Box",
            "itemId": "",
            "itemQuantity": 0,
            "itemPalletSpaces": 0,
            "itemLength": 0,
            "itemWidth": 0,
            "itemHeight": 0,
            "itemWeight": 0,
            "itemChargeableWeight": 0,
            "itemVolumetricWeight": 0,
            "itemValue": 0,
            "dangerousGoods": false,
            "customFields": {}
          }
        ]
      }
    ]
  }'

{
  "received": 2,
  "created": 1,
  "updated": 0,
  "failed": 1,
  "results": [
    { "shipmentId": "CONN-88213", "status": "created" },
    { "shipmentId": "CONN-88214", "status": "failed", "error": "Destination Zone(s) not found" }
  ]
}

{
  "statusCode": 400,
  "message": ["shipments.0.items should not be empty"],
  "error": "Bad Request"
}

Getting Started

Guides

Quotes

Shipments

Fulfilment

Import shipments (JSON)

Authorization

Body

Response

Errors

​Authorization

​Body

​Response

​Errors

Authorization

Body

Response

Errors