1. Shipments
  • Introduction
  • Getting Started
  • Authentication
  • Error Handling
  • Contact Support
  • Modaltrans API
    • Get Auth Token
      • Get Bearer Token
    • Accounting
      • Invoices
        • Retrieve an Invoice
        • List all Invoices
      • Invoice Items
        • List all Invoice Items
        • Deleted Invoice Items
      • Financials
        • Retrieve Financial Information
    • Customs
      • NCTS Declarations
        • List all NCTS Declarations
        • Retrieve an NCTS Declaration
        • Create an NCTS Declaration with XML Data
        • Update an NCTS Declaration
        • Download an NCTS Declaration
        • List Timelines of NCTS Declaration
        • List Messages of NCTS Decalaration
      • Customs Declarations
        • List all Customs Declarations
        • Retrieve a Custom Declaration
        • Create a Customs Declaration
        • Update a Custom Declaration
        • Delete a Custom Declaration
        • Retrieve a Declaration History
        • Retrieve an MRN Status of Declaration
      • Declaration Requests
        • List all Declaration Orders
        • Retrieve a Declaration Request
        • Create a Declaration Request
        • Update a Declaration Request
        • Delete a Declaration Request
      • Ens Declarations
        • Create an Ens Declaration
        • Download an Ens Declaration
    • Logistics
      • Bookings
        • Retrieve a Booking
        • List all Bookings
        • Create a Booking
        • Update a Booking
      • Locations
        • List all Locations
        • Retrieve a Location
      • Positions
        • Update a Transport
        • Get All Positions
      • Tracking
        • Available Shipping Lines
        • Retrieve a Tracking Data
        • Subscribe to Tracking
      • Shipments
        • Retrieve a Shipment
          GET
        • List All Shipments
          GET
        • Retrieve Financials of Shipment
          GET
        • List Contacts of the Shipment
          GET
        • Create a Shipment
          POST
        • Update a Shipment
          PATCH
    • Depot
      • Orders
        • Retrieve an Order
        • List all Orders
        • Create an Order
        • Update an Order
      • Products
        • Retrieve a Product
        • List all Products
        • Create a Product
        • Update a Product
        • List Product Stocks
      • Inventories
        • List all Inventories
    • Fleet Management
      • Drivers
        • Retrieve a Driver
        • Retrieve a Driver's Vehicle
        • List Driver Positions
        • Update a Driver
      • Vehicles
        • Retrieve a Vehicle
        • Update a Vehicle
      • Gps Service Controller
        • Create Gps Responses
      • Service Logs
        • List all Service Logs
        • Retrieve a Service Log
        • Create a Service Log
        • Delete a Service Log
        • Update a Service Log
      • Periodic Documents
        • Retrieve a Periodic Document
        • Update a Periodic Document
        • Create a Periodic Document
    • CRM
      • Companies
        • List all Companies
        • Retrieve a Company
        • Create a Company
        • Update a Company
        • Delete a Company
        • List Company Credit Limits
    • Timelines
      • Retrieve a Timeline
      • List Timelines
      • Create a Timeline
    • S3 Files
      • List all S3Files
      • Create an S3File
      • Delete an S3File
    • Notifications
      • List all Notifications
      • Update a Notification Status
    • User Details
      • List User Details
      • Update User Details
  1. Shipments

Create a Shipment

Testing Env
https://demo.modaltrans.com
Testing Env
https://demo.modaltrans.com
POST
/api/v1/shipments
Create a Shipment.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json

Example
{
    "position": {
        "trans_method": "road",
        "status": "planning",
        "voyage": "SU2143",
        "extref": "test1234",
        "waybill_no": "55501483441",
        "waybill_date": "2025-03-04",
        "truck_type": "trailer",
        "vessel_code": "test123",
        "dep_country_id": "TR",
        "arv_country_id": "PA",
        "estimated_dep_date": "2025-03-04 10:46:00",
        "estimated_arv_date": "2025-03-27 09:00:00",
        "target_volume": 123213213,
        "target_weight": 214321321,
        "dep_place_code": "TEST0555",
        "arv_place_code": "00123"
    },

    "booking": {
        "trans_mode": "road",
        "load_type": "P",
        "in_container": "out_of_container",
        "total_pack": 10,
        "brut_wg": 8700,
        "volume": 6.4,
        "price_wg": 8700,
        "operation_code": "fb9a753c22d59af6",
        "company_no": "21321432",
        "company_name": "Demo Uk",
        "company_taxno": "UK411981167",
        "company_country_id": "UK",
        "sender_name": "Test Consignor Co",
        "sender_eori": "GB987654312000",
        "load_place_type": "other",
        "load_place_code": "2214325324",
        "load_place": "WINCHESTER ROAD ,CHANDLERS FORD",
        "dep_zipcode": "SO53 2PZ",
        "load_state_name": "Winchester",
        "load_coun": "GB",
        "consignee_name": "Test Consignee Co",
        "consignee_eori": "GB987654312000",
        "unload_place_type": "other",
        "unload_place_code": "32412321",
        "unload_place": "NO 27 XIANXING ROAD, XIANLIN",
        "arv_zipcode": "710075",
        "unload_state_name": "Nanjing",
        "unload_coun": "CN",
        "incoterm": "CPT",
        "packages_attributes": [
            {
                "total": 97021,
                "pack_code": "BI",
                "dimension1": 50,
                "dimension2": 50,
                "dimension3": 50,
                "brutwg": 124213,
                "volume": 100,
                "pack_type": "Airpods"
            }

        ]

    }

}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://demo.modaltrans.com/api/v1/shipments' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "position": {
        "trans_method": "road",
        "status": "planning",
        "voyage": "SU2143",
        "extref": "test1234",
        "waybill_no": "55501483441",
        "waybill_date": "2025-03-04",
        "truck_type": "trailer",
        "vessel_code": "test123",
        "dep_country_id": "TR",
        "arv_country_id": "PA",
        "estimated_dep_date": "2025-03-04 10:46:00",
        "estimated_arv_date": "2025-03-27 09:00:00",
        "target_volume": 123213213,
        "target_weight": 214321321,
        "dep_place_code": "TEST0555",
        "arv_place_code": "00123"
    },

    "booking": {
        "trans_mode": "road",
        "load_type": "P",
        "in_container": "out_of_container",
        "total_pack": 10,
        "brut_wg": 8700,
        "volume": 6.4,
        "price_wg": 8700,
        "operation_code": "fb9a753c22d59af6",
        "company_no": "21321432",
        "company_name": "Demo Uk",
        "company_taxno": "UK411981167",
        "company_country_id": "UK",
        "sender_name": "Test Consignor Co",
        "sender_eori": "GB987654312000",
        "load_place_type": "other",
        "load_place_code": "2214325324",
        "load_place": "WINCHESTER ROAD ,CHANDLERS FORD",
        "dep_zipcode": "SO53 2PZ",
        "load_state_name": "Winchester",
        "load_coun": "GB",
        "consignee_name": "Test Consignee Co",
        "consignee_eori": "GB987654312000",
        "unload_place_type": "other",
        "unload_place_code": "32412321",
        "unload_place": "NO 27 XIANXING ROAD, XIANLIN",
        "arv_zipcode": "710075",
        "unload_state_name": "Nanjing",
        "unload_coun": "CN",
        "incoterm": "CPT",
        "packages_attributes": [
            {
                "total": 97021,
                "pack_code": "BI",
                "dimension1": 50,
                "dimension2": 50,
                "dimension3": 50,
                "brutwg": 124213,
                "volume": 100,
                "pack_type": "Airpods"
            }

        ]

    }

}'

Responses

🟢200OK
application/json
Body

Example
{
   "position": {
      "id": 1510817,
      "reference": "TPS250000029",
      "title": null,
      "branch_id": 746,
      "user_id": 8091,
      "status": "planning",
      "report_date": null,
      "slug": null,
      "trashed": false,
      "notes": null,
      "patron_id": 636,
      "loadings_count": 0,
      "transports_count": 0,
      "documents_count": 0,
      "created_at": "2025-03-21T18:52:01.064+03:00",
      "updated_at": "2025-03-21T18:52:01.064+03:00",
      "lead_id": null,
      "comments_count": 0,
      "trans_method": "road",
      "trans_type": null,
      "vessel_code": "test123",
      "truck_code": null,
      "voyage": "SU2143",
      "vagon": null,
      "waybill_no": "55501483441",
      "waybill_date": "2025-03-04",
      "driver_name": null,
      "owner_id": null,
      "supplier_id": null,
      "agent_id": null,
      "departure_date": null,
      "departure_hour": null,
      "dep_place_type": null,
      "dep_place_name": null,
      "dep_city_name": null,
      "dep_country_id": "TR",
      "dep_place_id": 61783,
      "dep_odemeter": 0,
      "arrival_date": null,
      "arrival_hour": null,
      "arv_place_type": null,
      "arv_place_name": null,
      "arv_city_name": null,
      "arv_country_id": "PA",
      "arv_place_id": 67039,
      "arv_odemeter": 0,
      "freight_price": "0.0",
      "freight_curr": null,
      "extref": "test1234",
      "agent_ref": null,
      "color": null,
      "contract_type": null,
      "driver_id": null,
      "driver_tel": null,
      "truck_type": "trailer",
      "route_notes": null,
      "order_date": null,
      "loading_date": null,
      "unloading_date": null,
      "import_id": null,
      "agreement_id": null,
      "assigned_date": null,
      "deadline_date": null,
      "border_date": null,
      "operation_id": 1915,
      "route_id": null,
      "border_gate": null,
      "operator_id": null,
      "vessel_id": null,
      "truck_id": null,
      "customs_type": null,
      "waybill_type": null,
      "freight_price_rate": "0.0",
      "cargo_manifest_no": null,
      "cargo_manifest_date": null,
      "arrival_vessel_id": null,
      "arrival_vessel_code": null,
      "empty_truck": false,
      "ppcc": null,
      "transit_point1_id": null,
      "transit_point2_id": null,
      "transit_point3_id": null,
      "transit_point4_id": null,
      "transit_point5_id": null,
      "transit_point6_id": null,
      "transit_date1": null,
      "transit_date2": null,
      "transit_date3": null,
      "transit_date4": null,
      "transit_date5": null,
      "transit_date6": null,
      "transit_code1": null,
      "transit_code2": null,
      "transit_code3": null,
      "transit_code4": null,
      "transit_code5": null,
      "transit_code6": null,
      "estimated_debit": "0.0",
      "estimated_credit": "0.0",
      "invoiced_debit": "0.0",
      "invoiced_credit": "0.0",
      "dep_city_id": null,
      "arv_city_id": null,
      "total_fuel": "0.0",
      "driver_payment": "0.0",
      "depreciation": "0.0",
      "commission": "0.0",
      "route_km": "0.0",
      "project_id": null,
      "untransit_point1_id": null,
      "untransit_point2_id": null,
      "untransit_point3_id": null,
      "untransit_point4_id": null,
      "untransit_point5_id": null,
      "untransit_point6_id": null,
      "auditer_id": null,
      "audited_at": null,
      "expense_form_id": null,
      "cmr_no": "CMR250000081",
      "uuid": null,
      "financial_status": "active",
      "active_date": null,
      "financial_confirm_date": null,
      "file_locked_date": null,
      "closed_date": null,
      "cancelled_date": null,
      "estimated_dep_date": "2025-03-04T10:46:00.000+03:00",
      "estimated_arv_date": "2025-03-27T09:00:00.000+03:00",
      "feeder_ship_id": null,
      "ship_id": null,
      "arv_ship_id": null,
      "talex": null,
      "free_time": null,
      "status_options": null,
      "total_brut_wg": "0.0",
      "total_volume": "0.0",
      "total_ladameter": "0.0",
      "total_freight_price": "0.0",
      "coagent_id": null,
      "coagent_hbl_no": null,
      "search_key": "tps250000029su2143test123455501483441test123",
      "supplier_name": null,
      "agent_name": null,
      "coagent_name": null,
      "tenant_id": 636,
      "uploaded_files": null,
      "driver_email": null,
      "tare_wg": null,
      "arv_lat": null,
      "arv_lng": null,
      "dep_lng": null,
      "dep_lat": null,
      "arv_postcode": null,
      "dep_postcode": null,
      "trailer_voyage_id": null,
      "vehicle_movement_type": null,
      "s3files_count": 0,
      "picked_up": false,
      "delivered": false,
      "last_place_id": null,
      "last_timeline_code": "transport_planned",
      "last_timeline_notes": "",
      "lat": null,
      "lng": null,
      "avis_status": false,
      "edi_status": false,
      "pod_status": false,
      "ferry_voyage_id": null,
      "pickup_ref": null,
      "delivery_ref": null,
      "dep_address": null,
      "arv_address": null,
      "dep_facility_id": null,
      "arv_facility_id": null,
      "container_no": null,
      "container_type": null,
      "container_gate_id": null,
      "container_gate_date": null,
      "tracking_eta": null,
      "run_letter": null,
      "cass_status": null,
      "cass_notes": null,
      "dep_state_name": null,
      "arv_state_name": null,
      "target_weight": 214321321.0,
      "target_volume": 123213213.0,
      "intermodal": false,
      "financial_status_notes": null,
      "master_notify_id": null,
      "tracking_etd": null,
      "waypoint_id": null,
      "drive_log": null,
      "extra_expense": 0.0,
      "extra_situation": null
   },
   "loading": {
      "transaction_id": 2130792,
      "uuid": null,
      "reference": "DM250056",
      "branch_id": 746,
      "company_id": 641310,
      "company_name": "Demo Uk",
      "customer_ref": null,
      "agent_ref": null,
      "consignee_name": "Test Consignee Co",
      "sender_name": "Test Consignor Co",
      "load_place_id": null,
      "load_city": null,
      "load_zipcode": "SO53 2PZ",
      "load_coun": "GB",
      "load_place": "WINCHESTER ROAD ,CHANDLERS FORD",
      "unload_place_id": null,
      "unload_city": null,
      "unload_zipcode": "710075",
      "unload_coun": "CN",
      "unload_place": "NO 27 XIANXING ROAD, XIANLIN",
      "brut_wg": 124213.0,
      "volume": 12127.625,
      "ladameter": null,
      "status": "pending",
      "commodity": null,
      "category": null,
      "group_id": 16567007,
      "price_wg": 4038499.125,
      "teu": 0,
      "saler_name": "MUHAMMET DEMIRHAN",
      "saler_email": "muhammet.demirhan@nimbo.com.tr",
      "saler_office_tel": "",
      "total_pack": 97021.0,
      "load_date": null,
      "unload_date": null,
      "container_nos": null,
      "waybill_no": "55501483441",
      "carrier_name": null,
      "total_packs": "97021 AIRPODS",
      "points": [],
      "timelines": [],
      "company_code": null,
      "tag_names": []
   }
}
Modified at 2026-01-09 13:57:00
Previous
List Contacts of the Shipment
Next
Update a Shipment
Built with