API Documentation

Submit orders directly from your systems

The Orin API allows you to submit transport orders directly from your warehouse management system, ERP, or other software. Orders appear instantly in your carrier's planning system.

To get started, ask your carrier to provide you with an API key through their Orin dashboard.

Base URL

https://{carrier-domain}/api/external/orders

Your carrier will provide the specific URL for their Orin instance.

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header with every request.

X-API-Key: your-api-key-here

Endpoints

POST /api/external/orders

Create Order

Submit a new transport order to your carrier.

Request Body

{
  "externalReference": "YOUR-ORDER-123",
  "pickupAddress": {
    "name": "Warehouse A",
    "street": "Industrieweg 10",
    "postalCode": "1234 AB",
    "city": "Amsterdam",
    "country": "NL"
  },
  "deliveryAddress": {
    "name": "Customer B",
    "street": "Hoofdstraat 25",
    "postalCode": "5678 CD",
    "city": "Rotterdam",
    "country": "NL"
  },
  "requestedPickupDate": "2024-01-15",
  "requestedDeliveryDate": "2024-01-15",
  "notes": "Handle with care"
}

Response

On success, returns HTTP 201 with the created order details including the assigned order number.

{
  "id": 1234,
  "orderNumber": "ORD-2024-00042",
  "externalReference": "YOUR-ORDER-123",
  "status": "Received",
  "pickupAddress": { ... },
  "deliveryAddress": { ... },
  "createdAt": "2024-01-14T10:30:00Z"
}
GET /api/external/orders/{externalRef}

Get Order

Retrieve an order by your external reference to check its status.

Example

GET /api/external/orders/YOUR-ORDER-123

Response

{
  "id": 1234,
  "orderNumber": "ORD-2024-00042",
  "externalReference": "YOUR-ORDER-123",
  "status": "Delivered",
  "pickupAddress": { ... },
  "deliveryAddress": { ... },
  "createdAt": "2024-01-14T10:30:00Z",
  "deliveredAt": "2024-01-15T14:22:00Z"
}

Field Reference

Field Description
externalReference Your unique order identifier (required)
pickupAddress Pickup location details (required)
deliveryAddress Delivery location details (required)
requestedPickupDate Requested pickup date (optional, format: YYYY-MM-DD)
requestedDeliveryDate Requested delivery date (optional, format: YYYY-MM-DD)
notes Additional instructions or notes (optional)

Address Fields

Field Description
name Company or location name
street Street address
postalCode Postal/ZIP code
city City
country Country code (ISO 3166-1 alpha-2)

Error Responses

401 401 Unauthorized - Invalid or missing API key
400 400 Bad Request - Invalid request body or missing required fields
404 404 Not Found - Order with specified reference not found

Need Help?

Contact your carrier for API access and support. They can provide your API key and answer questions about their specific setup.