Load Status Validation

A load's required fields are a function of its status. Most constraints apply the same way at every status, but stop appointment windows are deliberately relaxed while a load is still being assembled and enforced once the load is committed.

This page covers the rules applied by the POST /v2/loads and PATCH /v2/loads endpoints under Load Management.

Load status lifecycle

CANCELED, ERROR, and ARCHIVED are terminal or administrative states rather than lifecycle stages. A load in any status can move to one of them.

If a load has no status set, Augment treats it as DRAFT.

Requirements that apply at every status

These requirements never relax. A DRAFT load with a single stop is rejected exactly like a DELIVERED one.

Status-conditional requirement: stop appointment windows

expectedArrivalWindowStart and expectedArrivalWindowEnd on each entry in route are the only fields whose requirement depends on the load's status.

Windows are relaxed at DRAFT because a draft assembled from a customer email or an attachment does not have confirmed appointment times yet. They become required at CUSTOMER_CONFIRMED — the point at which the load is committed — and stay required for every later lifecycle stage.

The terminal states are intentionally excluded so that a draft can be canceled or archived without inventing appointment times it never had.

The requirement is evaluated per stop: every stop in route must carry both expectedArrivalWindowStart and expectedArrivalWindowEnd. A route where only the pickup has windows is rejected at CUSTOMER_CONFIRMED and later.

Rules that apply whenever a window is present

These apply at every status, including DRAFT:

• The value must be a valid RFC 3339 date-time (for example 2025-09-01T12:00:00Z), or a local date-time with no offset (for example 2025-09-01T12:00:00) when the stop sets isLocalTime: true.
• expectedArrivalWindowStart must be at or before expectedArrivalWindowEnd.
• On POST /v2/loads, sending null for a window is treated the same as omitting it.

Status transitions are gated, not relaxed

Promoting a load from a status where windows are optional to one where they are required is checked against the stored load, not just the fields in your request.

If any stop on the stored load is missing an appointment window, the request that moves the load to CUSTOMER_CONFIRMED or later is rejected. Supply the windows either in the same request that sets the new status, or in an earlier request.

Moving in the other direction is never gated by windows. A DRAFT load with no appointment windows can always move to CANCELED, ERROR, or ARCHIVED.

What this means for your requests

Create or update load

POST /v2/loads validates the entire payload. When validation fails, the response is 422 Unprocessable Entity with errorCode set to VALIDATION_ERROR and details keyed by the field path that failed:

{
  "message": "Unprocessable Entity",
  "errorCode": "VALIDATION_ERROR",
  "details": {
    "_errors": [],
    "load": {
      "_errors": [],
      "route": {
        "_errors": [],
        "0": {
          "_errors": [],
          "expectedArrivalWindowStart": {
            "_errors": [
              "expectedArrivalWindowStart is required once a load reaches CUSTOMER_CONFIRMED"
            ]
          },
          "expectedArrivalWindowEnd": {
            "_errors": [
              "expectedArrivalWindowEnd is required once a load reaches CUSTOMER_CONFIRMED"
            ]
          }
        }
      }
    }
  }
}

The numeric keys under route are indexes into the route array you sent, so route.0 is the first stop in your payload.

Patch a load

PATCH /v2/loads applies your operations to the stored load and then validates the merged result. A patch that only replaces /status can therefore fail because of stops it never touched:

{
  "loadReference": "LOAD-12345",
  "operations": [{ "op": "replace", "path": "/status", "value": "CUSTOMER_CONFIRMED" }]
}

If the stored load is a draft whose stops have no appointment windows, this returns 400 Bad Request.

Validation failures on PATCH /v2/loads return 400 Bad Request rather than 422, and details carries the underlying validation output as a string.

Promoting a draft

To move a draft to CUSTOMER_CONFIRMED, use POST /v2/loads and send the new status together with the complete route, including appointment windows on every stop. Because POST /v2/loads upserts the whole load, the windows and the status land in the same validated request:

{
  "brokerage": {},
  "load": {
    "loadNumber": "LOAD-12345",
    "mode": "FTL",
    "status": "CUSTOMER_CONFIRMED",
    "route": [
      {
        "sequence": 1,
        "stopActivity": "PICKUP",
        "expectedArrivalWindowStart": "2025-09-01T12:00:00Z",
        "expectedArrivalWindowEnd": "2025-09-01T14:00:00Z",
        "address": {
          "street1": "1 Santa Monica Blvd",
          "city": "Santa Monica",
          "stateOrProvince": "CA",
          "postalCode": "90401",
          "country": "US"
        }
      },
      {
        "sequence": 2,
        "stopActivity": "DELIVERY",
        "expectedArrivalWindowStart": "2025-09-02T12:00:00Z",
        "expectedArrivalWindowEnd": "2025-09-02T14:00:00Z",
        "address": {
          "street1": "1 Market St",
          "city": "San Francisco",
          "stateOrProvince": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    ]
  }
}

Use PATCH /v2/loads with /status only when the stored load already carries appointment windows on every stop.

Integration guidance

• Send loads to Augment as soon as they exist in your TMS, even as DRAFT. You do not need appointment windows to get a load into Augment.
• If your TMS already has appointment windows at draft time, send them from the start. Doing so keeps the CUSTOMER_CONFIRMED transition from failing later.
• Treat the move to CUSTOMER_CONFIRMED as the point where your integration must have windows for every stop, and handle the rejection path if it does not.
• Prefer POST /v2/loads for any update that changes both the route and the status. It validates the whole load in one request, so there is no window in which the stored load is inconsistent.
• Do not retry a 400 or 422 unchanged. Both indicate a problem with the request that will reproduce on retry. See Rate Limits & Retries.