TMS B2B Integration Specifications

Authentication

Every programmatic call made by a third-party TMS must include your unique Tenant API Key inside the request header. This maps the request to your tenant partition and verifies authorization.

Headers:
  Content-Type: application/json
  X-API-Key: [YOUR_TENANT_API_KEY]

1. Auto-Scheduling Appointments

This endpoint automatically analyzes your target shipment payload, computes the slot duration needed, checks the facility operating queues and breaks, and locks in the earliest available conflict-free slot.

POST /api/appointments/auto-schedule

Request Payload Fields

Example Request JSON

{
  "facilityId": "5cf768dc-ce6b-4be7-a284-1db27a7db55f",
  "type": "delivery",
  "carrierName": "Swift Transport",
  "referenceNumber": "PO-98213",
  "targetDate": "2026-07-27",
  "palletCount": 15,
  "equipmentId": "TR-998"
}

Example Response (201 Created)

{
  "status": "success",
  "message": "Appointment auto-scheduled successfully.",
  "data": {
    "id": "b90c1322-a9b0-4ce0-8e15-fa12ebde41cc",
    "facilityId": "5cf768dc-ce6b-4be7-a284-1db27a7db55f",
    "facilityName": "Dallas Distribution Center",
    "facilityCode": "A106",
    "doorId": "78fcb11a-0ccb-449e-ba78-2289cbde19b9",
    "doorName": "Door 2",
    "type": "delivery",
    "startTime": "2026-07-27T08:00:00.000Z",
    "endTime": "2026-07-27T09:00:00.000Z",
    "carrierName": "Swift Transport",
    "referenceNumber": "PO-98213",
    "status": "scheduled",
    "palletCount": 15,
    "durationMinutes": 50,
    "equipmentId": "TR-998",
    "trailerId": "TR-998"
  }
}

Closed & Full Date Auto-Rollover

By default, if the requested targetDate falls on a date when the facility is closed (e.g. Sunday) or when all door slots are fully booked, the auto-scheduler does not fail. Instead, it automatically advances day-by-day (up to a limit of 30 days) to locate and book the earliest open slot.

If you prefer to reject bookings when the target date is closed or full, you can disable this rollover behavior on the facility configurations panel by unchecking the "Automatically advance to next open day" option. When disabled, the API returns a 400 Bad Request status code with a descriptive error message:

{
  "status": "error",
  "message": "Facility is closed on 2026-08-02 (Sunday)."
}

Duplicate Reference Validation

To prevent double-booking or accidental duplicate requests due to network retries, the auto-scheduler checks if an active scheduled appointment already exists for the given referenceNumber at the target facility. If a duplicate is found, the system rejects the creation, returning a 400 Bad Request status code with the following structure:

{
  "status": "error",
  "message": "An active scheduled appointment already exists for reference number PO-55489."
}

2. Checking / Querying Existing Appointments

Use this query endpoint to check if an appointment has been scheduled, monitor status changes (e.g. marked as completed or cancelled), or pull daily scheduling queues by facility.

GET /api/appointments

Query Parameters

Example Lookup Request

GET /api/appointments?facility_id=5cf768dc-ce6b-4be7-a284-1db27a7db55f&reference_number=PO-98213

Example Response (200 OK)

[
  {
    "id": "b90c1322-a9b0-4ce0-8e15-fa12ebde41cc",
    "facilityId": "5cf768dc-ce6b-4be7-a284-1db27a7db55f",
    "doorId": "78fcb11a-0ccb-449e-ba78-2289cbde19b9",
    "doorName": "Door 2",
    "type": "delivery",
    "startTime": "2026-07-27T08:00:00.000Z",
    "endTime": "2026-07-27T09:00:00.000Z",
    "carrierName": "Swift Transport",
    "referenceNumber": "PO-98213",
    "status": "scheduled",
    "palletCount": 15,
    "weight": null,
    "loadDescription": null
  }
]

3. Rescheduling Appointments

If a shipment's estimated arrival changes, use this endpoint to shift the appointment to a different target date. The engine automatically releases the old slot and books the first free slot on the new date.

PUT /api/appointments/:id/reschedule

Path Parameters

Request Body Fields

Example Request

PUT /api/appointments/b90c1322-a9b0-4ce0-8e15-fa12ebde41cc/reschedule

Body:
{
  "targetDate": "2026-07-28"
}

Example Response (200 OK)

{
  "status": "success",
  "message": "Appointment rescheduled successfully.",
  "data": {
    "id": "b90c1322-a9b0-4ce0-8e15-fa12ebde41cc",
    "doorId": "78fcb11a-0ccb-449e-ba78-2289cbde19b9",
    "doorName": "Door 2",
    "type": "delivery",
    "startTime": "2026-07-28T09:30:00.000Z",
    "endTime": "2026-07-28T10:20:00.000Z",
    "carrierName": "Swift Transport",
    "referenceNumber": "PO-98213",
    "status": "scheduled",
    "palletCount": 15,
    "durationMinutes": 50
  }
}

4. Cancelling Appointments

If a load is cancelled, use this endpoint to terminate the reservation. This changes the status to "cancelled" and immediately opens the capacity and door slots for other B2B or carrier bookings.

DELETE /api/appointments/:id

Path Parameters

Example Request

DELETE /api/appointments/b90c1322-a9b0-4ce0-8e15-fa12ebde41cc

Example Response (200 OK)

{
  "status": "success",
  "message": "Appointment cancelled successfully."
}