Skip to content
/
Managing Transport Orders
Last updated

Managing Transport Orders

Objective

Transport orders are the starting point of every operation in Transportial. This example walks through creating, updating, and managing transport orders from different sources.

Creating a Transport Order via API

The most direct way to create a transport order:

curl -X POST https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "customer": { "id": "customer-business-uuid" },
    "consignments": [
      {
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Electronics",
            "quantity": 120,
            "weight": { "value": 2400, "unit": "kg" }
          }
        ]
      }
    ]
  }'

Response:

{
  "success": true,
  "message": "OK",
  "transportOrder": {
    "id": "to-uuid",
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "consignments": [
      {
        "id": "consignment-uuid",
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Electronics",
            "quantity": 120,
            "weight": { "value": 2400, "unit": "kg" }
          }
        ]
      }
    ],
    "createdAt": "2026-03-22T10:30:00Z"
  }
}

Creating from Email

Transport orders can also be created from incoming emails using the mail receiver endpoint:

curl -X PUT https://api.otms.transportial.com/api/transportOrder/mail/receiver \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "from": "customer@example.com",
    "subject": "Transport request - 50 pallets RTD to BER",
    "body": "Please arrange transport for 50 pallets..."
  }'

Transportial parses the email content and creates a transport order automatically.

Updating a Transport Order

Update fields on an existing transport order:

curl -X PUT https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "to-uuid",
    "name": "Shipment AMS-RTD #1042 (updated)",
    "status": "accepted"
  }'

Listing Transport Orders

Retrieve a paginated list of transport orders:

curl -X GET "https://api.otms.transportial.com/api/transportOrders/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "success": true,
  "message": "OK",
  "totalResults": 142,
  "items": [
    {
      "id": "to-uuid",
      "name": "Shipment AMS-RTD #1042",
      "status": "requested",
      "createdAt": "2026-03-22T10:30:00Z"
    }
  ]
}

Searching with Filters

Use POST to search with advanced filters:

curl -X POST "https://api.otms.transportial.com/api/transportOrders/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested",
    "customer": { "id": "customer-business-uuid" }
  }'

Transport Order Lifecycle

A transport order progresses through these statuses:

StatusDescription
conceptDraft, not yet submitted
requestedSubmitted, awaiting acceptance
acceptedConfirmed by the carrier
calculated_tripRoute has been calculated
partially_plannedSome consignments are planned
plannedAll consignments have trips assigned
actualCurrently in execution
realizedCompleted successfully
cancelledCancelled before completion
declinedRejected by the carrier

Adding Consignments

A single transport order can have multiple consignments. Add additional consignments to group different goods or destinations:

curl -X POST https://api.otms.transportial.com/api/consignment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested",
    "goods": [
      {
        "type": "items",
        "description": "Furniture",
        "quantity": 30,
        "weight": { "value": 900, "unit": "kg" }
      }
    ]
  }'

Attaching Documents

Add documents (CMR, POD, photos) to a transport order:

curl -X PUT "https://api.otms.transportial.com/api/consignment/{id}/documents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "documents": [
      { "id": "document-uuid" }
    ]
  }'

Next Steps

Previous page
Next page