Create freight - Trans.eu Api

Creating a new freight without the option of publishing.

After successfully executing the method, you receive in response the freight details with the unique freight identification number id assigned when creating the new freight.
This method can only be used to create a working copy of the freight for subsequent manual publication using any method on the Platform.
The rules for completing data in the request are described in Freight creation.

POST
/ext/freights-api/v1/freights

Request Authorization

Every request MUST include a valid access token obtained during the user authorization process, provided using the Bearer token scheme in the Authorization header.

Request Header

POST /ext/freights-api/v1/freights HTTP/1.1 
Host: api.platform.trans.eu 
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token) 
Api-key: {unique_app_api-key}

Request Parameters

Attribute	Type	Example	Mandatory	Description
callback_url	String	http://example.com/msg	No	The return address provided by the client to receive freight and publication event statuses. See list of available event statuses.
capacity	Float	24	Yes	Total freight capacity in tonnes. This value is being validated in comparison to the sum of all loads weight (range: 0,001 – 100000)
height	Float	3.2	No	Expected/required vehicle height (range: 0.01–10)
length	Float	5	No	Expected/required vehicle length (range: 0.01–100)
loading_meters	Float	13.6	No	Total freight loading meters (range: 0,01 — 417)
loads (see details)	Array of Objects		No	Collection of freight loads. It is possible to send empty array of loads, nevertheless an array has to be set
requirements (see details)	Object		Yes	Main freight requirements
shipment_external_id	String	2023/NWX/1/3	No	External identification number
spots (see details)	Array of Objects		Yes	Collection of freights’ spots – at least one loading and one unloading is required
transit_time	Int	280	No	Time expressed in minutes (positive integer) for transport. Must be less than the difference between the last unloading and the first loading.
volume	Float	21	No	Expected/required vehicle volume (range: 0.01–10000)
width	Float	3.1	No	Expected/required vehicle width (range: 0.01–10)

Example Request Body

{
  "callback_url": "http://example.com/msg",  
  "capacity": 15.1,
  "height":9.1,
  "length":6.1,
  "loading_meters": 7.2,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "dump-truck"
    ],
    "vehicle_size": "lorry"
  },
  "shipment_external_id": "1111",
  "spots": [
    {
      "spot_order": 1,
      "operations": [
        {
          "operation_order": 1,
          "type": "loading",
          "timespans": {
            "begin": "2026-02-23T10:30:58+01:00",
            "end": "2026-02-23T12:30:58+01:00"
          }
        }
      ],
      "place": {
        "address": {
          "country": "PL",
          "postal_code": "54-128",
          "locality": "Wroclaw"
        }
      }
    },
    {
      "spot_order": 2,
      "operations": [
        {
          "operation_order": 1,
          "type": "unloading",
          "timespans": {
            "begin": "2026-02-26T10:30:58+01:00",
            "end": "2026-02-26T12:30:58+01:00"
          }
        }
      ],
      "place": {
        "address": {
          "country": "IT",
          "postal_code": "20097",
          "locality": "Milan"
        }
      }
    }
  ],
  "volume":12.1,
  "width": 6.6
}

Response Fields

Attribute	Type	Example	Description
accepted_price	Object	null	Final price for freight accepted during publication and negotiation process. Always `null` in this request.
capacity	Float	22.1	Total freight capacity in tonnes.
carrier	Object	null	Carrier selected during publication and negotiation process. Always `null` in this request.
contact_employees	Array of Objects		List of employees assigned to freight negotiation. Always publisher in this request.
contact_employees.last_name	String	Nowak	Surname of assigned employee
contact_employees.name	String	Jan	First name of assigned employee
contact_employees.trans_id	String	13443–1	TransId of assigned employee
distance	Int	34	Distance in meters from the point of loading to the point of unloading.
end_reason	String	null	Publication end reason. Always `null` in this request.
height	Float	3.1	Vehicle height (range: 0.01–10)
id	Int	234923	Freight identification number, assigned automatically during creation of a new freight.
is_first_buy	Boolean	False	Defines if price can be negotiated or only accepted by carrier. Always `null` in this request.
length	Float	12	Vehicle length (range: 0.01–100)
loading_meters	Float	23	Total freight loading meters (range: 0,01 — 417)
loads (see details)	Array of Objects		Collection of freight loads.
publication_price	Object		Publication price information. Always `null` in this request.
publication_status	String	new	Status of the publication. Always `null` in this request.
reference_number	String	FR/2025/12/30/2NNQ	Freight reference number — a unique, automatically assigned business identifier of the freight
requirements (see details)	Object		Main freight requirements
shipment_external_id	String	2023/NWX/1/3	External identification number
spots (see details)	Array of Objects		Collection of freights’ spots. At least one loading and one unloading will occur.
status	String	new	Freight status. Always `new` in this request. See other statuses.
surchages	Object	null	Surchages for fixed routes. Always `null` in this request.
transit_time	Int	460	Time expressed in minutes (positive integer) for transport, if specified.
volume	Float	21	Vehicle volume (range 0.01–10000).
width	Float	3.1	Vehicle width (range 0.01–10).

Response Body

{
    "accepted_price": null,
    "capacity": 15.1,
    "carrier": null,
    "contact_employees": [
        {
            "last_name": "Nowak",
            "name": "Jan",
            "trans_id": "1017374-1"
        }
    ],
    "distance": 1185000,
    "end_reason": null,
    "height": 9.1,
    "id": 3828345,
    "is_first_buy": null,
    "length": 6.1,
    "loading_meters": 7.2,
    "loads": [],
    "publication_price": null,
    "publication_status": null,
    "reference_number": "FR/2026/02/20/2N21",
    "requirements": {
        "exemption_from_adr": false,
        "is_ftl": true,
        "monitoring": "required",
        "other_requirements": [],
        "required_adr_classes": [],
        "required_door_types": [],
        "required_tipper_trailer_additional_equipment": [],
        "required_truck_bodies": [
            "dump-truck"
        ],
        "required_ways_of_loading": [],
        "shipping_remarks": null,
        "temperature": {
            "max": null,
            "min": null
        },
        "transport": {
            "count": null,
            "schedule_type": null,
            "settlement": "route",
            "settlement_basis": null,
            "total_weight": null,
            "type": "ftl"
        },
        "vehicle_size": "lorry"
    },
    "shipment_external_id": "1111",
    "spots": [
        {
            "description": "",
            "name": null,
            "operations": [
                {
                    "loads": [],
                    "operation_order": 1,
                    "operation_time": null,
                    "timespans": {
                        "begin": "2026-02-23T10:30:58+01:00",
                        "begin_local": "2026-02-23T10:30:58+01:00",
                        "end": "2026-02-23T12:30:58+01:00",
                        "end_local": "2026-02-23T12:30:58+01:00",
                        "timezone": "Europe/Warsaw"
                    },
                    "type": "loading"
                }
            ],
            "place": {
                "address": {
                    "country": "pl",
                    "description": null,
                    "locality": "Wroclaw",
                    "number": null,
                    "postal_code": "54-128",
                    "street": null
                },
                "coordinates": {
                    "latitude": 51.142329074,
                    "longitude": 16.937462521
                }
            },
            "spot_order": 1
        },
        {
            "description": "",
            "name": null,
            "operations": [
                {
                    "loads": [],
                    "operation_order": 1,
                    "operation_time": null,
                    "timespans": {
                        "begin": "2026-02-26T10:30:58+01:00",
                        "begin_local": "2026-02-26T10:30:58+01:00",
                        "end": "2026-02-26T12:30:58+01:00",
                        "end_local": "2026-02-26T12:30:58+01:00",
                        "timezone": "Europe/San_Marino"
                    },
                    "type": "unloading"
                }
            ],
            "place": {
                "address": {
                    "country": "it",
                    "description": null,
                    "locality": "Milan",
                    "number": null,
                    "postal_code": "20097",
                    "street": null
                },
                "coordinates": {
                    "latitude": 45.397205283,
                    "longitude": 9.21659417
                }
            },
            "spot_order": 2
        }
    ],
    "status": "new",
    "surcharges": [],
    "transit_time": null,
    "volume": 12.1,
    "width": 6.6
}

Clients errors (code 400)

HTTP 4xx status codes indicate client errors, meaning that the request could not be processed due to an issue on the client side. Below is a list of request-specific errors.

Example error 1

No mandatory value in capacity field

{
    "detail": "Failed Validation",
    "status": 422,
    "title": "Unprocessable Entity",
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "validation_messages": {
        "capacity": {
            "value": {
                "isEmpty": "Value is required and can't be empty"
            }
        }
    }
}

Example error 2

Incorrect date in spot operation

"validation_messages": {
        "spot_operation": {
            "validation_error": "In one of spot.operation begin or end date is lower or equal today (UTC)"
        }
    }

Example error 3

Vehicle type not allowed for vehicle size

"validation_messages": {
            "vehicle_size_id": {
                "invalid": "['7_silos'] is not valid for vehicle size: '1_bus'"
            }
        }
    }

Example error 4

Loading weight does not match capacity

{
    "detail": "Failed Validation",
    "status": 422,
    "title": "Unprocessable Entity",
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "validation_messages": {
        "capacity": {
            "value": {
                "loadingWeightGreaterThanCapacity": "Sum of loading weights is greater than freight capacity '15'"
            }
        }
    }
}