Skip to content
Last updated

Quickstart Guide

Get up and running with the Transportial OTMS API in minutes. This guide walks you through authentication, creating your first transport order, and understanding the response structure.

Prerequisites

Base URLs

EnvironmentURL
Productionhttps://api.otms.transportial.com/api
Testhttps://test.api.otms.transportial.com/api

Step 1: Authenticate

All API requests require a Bearer token. Obtain one by logging in:

curl -X POST https://api.otms.transportial.com/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your@email.com",
    "password": "your-password"
  }'

Response:

{
  "success": true,
  "message": "OK",
  "session": {
    "id": "session-uuid",
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "refresh-token-uuid",
    "expiresAt": "2026-03-23T12:00:00Z",
    "permissions": [
      { "name": "create:transportOrder" },
      { "name": "get:transportOrders" }
    ]
  }
}

Use the access_token in all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Step 2: Create a Business

Before creating transport orders, you need at least one business entity (your company or a customer):

curl -X POST https://api.otms.transportial.com/api/business \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Acme Logistics B.V.",
    "coc": "12345678",
    "vat": "NL123456789B01",
    "contactDetails": [
      {
        "type": "email",
        "value": "info@acme-logistics.com"
      }
    ]
  }'

Step 3: Create a Transport Order

A transport order is the core entity — it represents a request to move goods from A to B.

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",
    "consignments": [
      {
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Electronics",
            "quantity": 120,
            "weight": { "value": 2400, "unit": "kg" }
          }
        ]
      }
    ]
  }'

Response:

{
  "success": true,
  "message": "OK",
  "transportOrder": {
    "id": "transport-order-uuid",
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "consignments": [
      {
        "id": "consignment-uuid",
        "status": "requested",
        "goods": [ ... ]
      }
    ],
    "createdAt": "2026-03-22T10:30:00Z"
  }
}

Step 4: Retrieve the Transport Order

curl -X GET https://api.otms.transportial.com/api/transportOrder/{id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

All API responses follow a consistent structure:

{
  "success": true,
  "message": "OK",
  "entity": { ... }
}

List endpoints include pagination:

{
  "success": true,
  "message": "OK",
  "totalResults": 142,
  "items": [ ... ]
}

Errors return:

{
  "success": false,
  "message": "Description of what went wrong",
  "statusCode": 400
}

Next Steps

 
Next page