- Introduction
- Getting Started
- Authentication
- Error Handling
- Contact Support
- Modaltrans API
- Get Auth Token
- Accounting
- Customs
- Logistics
- Bookings
- Locations
- Positions
- Tracking
- Shipments
- Depot
- Fleet Management
- CRM
- Timelines
- S3 Files
- Notifications
- User Details
Create a Shipment
Developing
Testing Env
https://demo.modaltrans.com
Testing Env
https://demo.modaltrans.com
POST
/api/v1/shipments
Request
Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.Example:
Authorization: Bearer ********************
Body Params application/json
position
object
required
status
enum<string>
required
Allowed values:
planningactivearrived
trans_method
enum<string>
required
Allowed values:
roadseaairrail
waybill_no
string
required
waybill_date
string <date>
required
truck_type
string
required
Examples:
trailertruckvan
estimated_dep_date
string <date-time>
required
estimated_arv_date
string <date-time>
required
arv_country_id
string
required
Examples:
GBUSTR
dep_country_id
string
required
voyage
string
required
supplier_name
string
optional
truck_code
string
optional
vessel_code
string
optional
driver_name
string
optional
driver_tel
string
optional
driver_email
string <email>
optional
deadline_date
string <date-time>
optional
target_volume
number
required
target_weight
number
required
hub_motion_exit_date
string <date-time>
optional
contract_type
enum<string>
optional
Allowed values:
ownedrented
empty_truck
boolean
optional
freight_price
number
optional
freight_curr
string
optional
Examples:
USDGBP
dep_odemeter
integer
optional
arv_odemeter
integer
optional
total_fuel
number
optional
driver_payment
number
optional
waybill_type
string
optional
commission
number
optional
vagon
string
optional
vehicle_movement_type
string
optional
intermodal
boolean
optional
coagent_hbl_no
string
optional
border_date
string <date>
optional
assigned_date
string <date-time>
optional
free_time
integer
optional
container_no
string
optional
container_type
string
optional
cmr_no
string
optional
cargo_manifest_no
string
optional
cargo_manifest_date
string <date>
optional
transit_code1
string
optional
1.
transit_code2
string
optional
2.
transit_code3
string
optional
3.
departure_date
string <date-time>
optional
arrival_date
string <date-time>
optional
trans_type
string
optional
active_date
string <date-time>
optional
freight_price_rate
number
optional
ppcc
enum<string>
optional
Allowed values:
ppcc
agent_name
string
optional
route_notes
string
optional
transit_date1
string <date>
optional
1.
transit_date2
string <date>
optional
2.
transit_date3
string <date>
optional
3.
report_date
string <date>
optional
arv_place_code
string
required
dep_place_code
string
required
booking
object
required
trans_mode
enum<string>
required
Allowed values:
roadairseacourier
load_type
enum<string>
required
Allowed values:
PK
in_container
enum<string>
required
Allowed values:
at_containerout_of_container
total_pack
number
optional
Example:
10
brut_wg
number
optional
Example:
8700
volume
number
optional
Example:
4.5
price_wg
number
optional
Example:
132.58
operation_code
string
required
Example:
fb9a753c22d59af6
company_no
string
optional
Example:
21321432
company_name
string
required
Example:
Demo Uk
company_taxno
string
optional
Example:
UK411981167
company_country_id
string
required
Examples:
GBUSCH
sender_name
string
optional
Example:
Test Consignor Co
sender_eori
string
optional
Example:
GB987654312000
load_place_type
enum<string>
required
Allowed values:
airseaportcompanyother
load_place_code
string
optional
Examples:
GBSOULHR
load_place
string
optional
Example:
WINCHESTER ROAD ,CHANDLERS FORD
dep_zipcode
string
optional
Example:
SO53 2PZ
load_state_name
string
optional
Example:
Winchester
load_coun
string
required
Examples:
GBUSCN
consignee_name
string
optional
Example:
Test Consignee Co
consignee_eori
string
optional
Example:
GB987654312000
unload_place_type
enum<string>
required
Allowed values:
airseaportcompanyother
unload_place_code
string
optional
Examples:
GBSOULHR
unload_place
string
optional
Example:
NO 27 XIANXING ROAD, XIANLIN
arv_zipcode
string
optional
Example:
710075
unload_state_name
string
optional
Example:
Nanjing
unload_coun
string
required
Examples:
CNGBUS
incoterm
string
required
Example:
CPT
packages_attributes
array [object {7}]
optional
containers_attributes
array [object {8}]
optional
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 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 '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
position
object
required
id
integer
required
reference
string
required
title
string
required
branch_id
integer
required
user_id
integer
required
status
string
required
report_date
string
required
slug
null
required
trashed
boolean
required
notes
null
required
patron_id
integer
required
loadings_count
integer
required
transports_count
integer
required
documents_count
integer
required
created_at
string
required
updated_at
string
required
lead_id
null
required
comments_count
integer
required
trans_method
string
required
trans_type
null
required
vessel_code
string
required
truck_code
null
required
voyage
string
required
vagon
null
required
waybill_no
string
required
waybill_date
string
required
driver_name
null
required
owner_id
null
required
supplier_id
null
required
agent_id
null
required
departure_date
null
required
departure_hour
null
required
dep_place_type
null
required
dep_place_name
null
required
dep_city_name
null
required
dep_country_id
string
required
dep_place_id
integer
required
dep_odemeter
integer
required
arrival_date
null
required
arrival_hour
null
required
arv_place_type
null
required
arv_place_name
null
required
arv_city_name
null
required
arv_country_id
string
required
arv_place_id
integer
required
arv_odemeter
integer
required
freight_price
string
required
freight_curr
null
required
extref
string
required
agent_ref
null
required
color
null
required
contract_type
null
required
driver_id
null
required
driver_tel
null
required
truck_type
string
required
route_notes
null
required
order_date
null
required
loading_date
null
required
unloading_date
null
required
import_id
null
required
agreement_id
null
required
assigned_date
null
required
deadline_date
null
required
border_date
null
required
operation_id
integer
required
route_id
null
required
border_gate
null
required
operator_id
null
required
vessel_id
null
required
truck_id
null
required
customs_type
null
required
waybill_type
null
required
freight_price_rate
string
required
cargo_manifest_no
null
required
cargo_manifest_date
null
required
arrival_vessel_id
null
required
arrival_vessel_code
null
required
empty_truck
boolean
required
ppcc
null
required
transit_point1_id
null
required
transit_point2_id
null
required
transit_point3_id
null
required
transit_point4_id
null
required
transit_point5_id
null
required
transit_point6_id
null
required
transit_date1
null
required
1.
transit_date2
null
required
2.
transit_date3
null
required
3.
transit_date4
null
required
transit_date5
null
required
transit_date6
null
required
transit_code1
null
required
1.
transit_code2
null
required
2.
transit_code3
null
required
3.
transit_code4
null
required
transit_code5
null
required
transit_code6
null
required
estimated_debit
string
required
estimated_credit
string
required
invoiced_debit
string
required
invoiced_credit
string
required
dep_city_id
null
required
arv_city_id
null
required
total_fuel
string
required
driver_payment
string
required
depreciation
string
required
commission
string
required
route_km
string
required
project_id
null
required
untransit_point1_id
null
required
untransit_point2_id
null
required
untransit_point3_id
null
required
untransit_point4_id
null
required
untransit_point5_id
null
required
untransit_point6_id
null
required
auditer_id
null
required
audited_at
null
required
expense_form_id
null
required
cmr_no
string
required
uuid
null
required
financial_status
string
required
active_date
null
required
financial_confirm_date
null
required
file_locked_date
null
required
closed_date
null
required
cancelled_date
null
required
estimated_dep_date
string
required
estimated_arv_date
string
required
feeder_ship_id
null
required
ship_id
null
required
arv_ship_id
null
required
talex
null
required
free_time
null
required
status_options
null
required
total_brut_wg
string
required
total_volume
string
required
total_ladameter
string
required
total_freight_price
string
required
coagent_id
null
required
coagent_hbl_no
null
required
search_key
string
required
supplier_name
null
required
agent_name
null
required
coagent_name
null
required
tenant_id
integer
required
uploaded_files
null
required
driver_email
null
required
tare_wg
null
required
arv_lat
null
required
arv_lng
null
required
dep_lng
null
required
dep_lat
null
required
arv_postcode
null
required
dep_postcode
null
required
trailer_voyage_id
null
required
vehicle_movement_type
null
required
s3files_count
integer
required
picked_up
boolean
required
delivered
boolean
required
last_place_id
null
required
last_timeline_code
string
required
last_timeline_notes
string
required
lat
null
required
lng
null
required
avis_status
boolean
required
edi_status
boolean
required
pod_status
boolean
required
ferry_voyage_id
null
required
pickup_ref
null
required
delivery_ref
null
required
dep_address
null
required
arv_address
null
required
dep_facility_id
null
required
arv_facility_id
null
required
container_no
null
required
container_type
null
required
container_gate_id
null
required
container_gate_date
null
required
tracking_eta
null
required
run_letter
null
required
cass_status
null
required
cass_notes
null
required
dep_state_name
null
required
arv_state_name
null
required
target_weight
integer
required
target_volume
integer
required
intermodal
boolean
required
financial_status_notes
null
required
master_notify_id
null
required
tracking_etd
null
required
waypoint_id
null
required
drive_log
null
required
extra_expense
integer
required
extra_situation
null
required
loading
object
required
transaction_id
integer
required
uuid
null
required
reference
string
required
branch_id
integer
required
company_id
integer
required
company_name
string
required
customer_ref
null
required
agent_ref
null
required
consignee_name
string
required
sender_name
string
required
load_place_id
null
required
load_city
null
required
load_zipcode
string
required
load_coun
string
required
load_place
string
required
unload_place_id
null
required
unload_city
null
required
unload_zipcode
string
required
unload_coun
string
required
unload_place
string
required
brut_wg
integer
required
volume
number
required
ladameter
null
required
status
string
required
commodity
null
required
category
null
required
group_id
integer
required
price_wg
number
required
teu
integer
required
saler_name
string
required
saler_email
string
required
saler_office_tel
string
required
total_pack
integer
required
load_date
null
required
unload_date
null
required
container_nos
null
required
waybill_no
string
required
carrier_name
null
required
total_packs
string
required
points
array[string]
required
timelines
array[string]
required
company_code
null
required
tag_names
array[string]
required
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": []
}
}
🟠422Unprocessable Entity
🟠400Bad Request
🟠403Forbidden
🟠404Record Not Found
Modified at 2025-03-21 23:58:33