1. Bookings
  • Introduction
  • Getting Started
  • Authentication
  • Error Handling
  • Contact Support
  • Modaltrans API
    • Get Auth Token
      • Get Bearer Token
    • Accounting
      • Invoices
        • Retrieve an Invoice
        • List all Invoices
    • Customs
      • NCTS Declarations
        • List all NCTS Declarations
        • Retrieve an NCTS Declaration
        • Create an NCTS Declaration with XML Data
        • Create an Ens Declaration from JSON
        • 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
    • Logistics
      • Bookings
        • Retrieve a Booking
          GET
        • List all Bookings
          GET
        • Create a Booking
          POST
        • Update a Booking
          PATCH
      • Locations
        • List all Locations
        • Retrieve a Location
      • Positions
        • Update a Transport
      • Tracking
        • Available Shipping Lines
        • Retrieve a Tracking Data
        • Subscribe to Tracking
      • Shipments
        • Retrieve a Shipment
        • List All Shipments
        • Retrieve Financials of Shipment
        • List Contacts of the Shipment
        • Create a Shipment
        • Update a Shipment
    • 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
    • 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. Bookings

Create a Booking

Developing
Testing Env
https://demo.modaltrans.com
Testing Env
https://demo.modaltrans.com
POST
/api/v1/bookings
Creates a Booking.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json
booking
object 
required
trans_mode
enum<string> 
required
Transportation Mode
Allowed values:
roadairseacourier
load_type
enum<string> 
required
FCL/FTL or LCL/FTL option
Allowed values:
PK
in_container
enum<string> 
required
If the goods will be carried in a container or not
Allowed values:
at_containerout_of_container
total_pack
number 
optional
Total Pack
Example:
10
brut_wg
number 
optional
Total Weight
Example:
8700
volume
number 
optional
Total Volume
Example:
4.5
price_wg
number 
optional
Chargeable Weight
Example:
132.58
operation_code
string 
required
Specific Operation/Team code, you need to discuss with the account admin if you will work with different teams
Example:
fb9a753c22d59af6
company_no
string 
optional
Company account number
Example:
21321432
company_name
string  | null 
required
Company name
Example:
Demo Uk
company_taxno
string 
optional
Company tax no
Example:
UK411981167
company_country_id
string 
required
Company country code (like GB, US, CH..)
Examples:
GBUSCH
sender_name
string 
optional
Consignor company name
Example:
Test Consignor Co
sender_eori
string 
optional
Consignor company EORI or account no
Example:
GB987654312000
load_place_type
enum<string> 
required
Origin location type
Allowed values:
airseaportcompanyother
load_place_code
string 
optional
Origin place code: If the location type is airport or seaport, then you need to send the airport or seaport code.
Examples:
GBSOULHR
load_place
string 
optional
Origin place address if the location type is "other", then you need to send address here
Example:
WINCHESTER ROAD ,CHANDLERS FORD
dep_zipcode
string 
optional
Origin place postcode if the location type is "other", then you need to send postcode here
Example:
SO53 2PZ
load_state_name
string 
optional
Origin place state name if the location type is "other", then you need to send the state code here
Example:
Winchester
load_coun
string 
required
Origin place country code, Origin or departure country code, two digits code.
Examples:
GBUSCN
consignee_name
string 
optional
Consignee company name
Example:
Test Consignee Co
consignee_eori
string 
optional
Consignee company EORI or account no
Example:
GB987654312000
unload_place_type
enum<string> 
required
Destination location type
Allowed values:
airseaportcompanyother
unload_place_code
string 
optional
Destination place code: If the location type is airport or seaport, then you need to send the airport or seaport code.
Examples:
GBSOULHR
unload_place
string 
optional
Destination place address. If the location type is "other", then you need to send address here
Example:
NO 27 XIANXING ROAD, XIANLIN
arv_zipcode
string 
optional
Destination place postcode if the location type is "other", then you need to send postcode here
Example:
710075
unload_state_name
string 
optional
Destination place state code if the location type is "other", then you need to send state code here
Example:
Nanjing
unload_coun
string 
required
Destination country code, Destination or arrival country code, two digits code like GB, US, CN...
Examples:
CNGBUS
incoterm
string 
required
Incoterm
Example:
CPT
packages_attributes
array [object {7}] 
optional
containers_attributes
array [object {8}] 
optional
Example
{
    "booking": {
        "trans_mode": "sea",
        "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/bookings' \
--header 'Content-Type: application/json' \
--data-raw '{
    "booking": {
        "trans_mode": "sea",
        "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

🟢201Created
application/json
Body
array of:
transaction_id
integer 
required
ID of the transaction
uuid
string 
required
UUID of the booking
reference
string 
required
Reference number of the booking
branch_id
integer 
required
ID of the branch
company_uuid
string 
required
UUID of the company
company_name
string 
required
Name of the company
customer_ref
string 
required
Customer Reference
agent_ref
string 
required
Agency Reference
consignee_name
string 
required
Name of the consignee company
sender_name
string 
required
Name of the sender company
load_place_id
integer 
required
Origin place id
load_city
string 
required
Origin City
load_zipcode
string 
required
Zip code of the origin address
load_coun
string 
required
Origin country
load_place
string 
required
Origin address
load_date
string <date-time>
required
ETD
unload_place_id
integer 
required
ID of destination
unload_city
string 
required
Destination City
unload_zipcode
string 
required
Zip code of the destination address
unload_coun
string 
required
Destination Country
unload_place
string 
required
Destination place address
unload_date
string 
required
ETA
brut_wg
number 
required
Gross weight
volume
number 
required
Volume of the shipment
ladameter
number 
required
Ladameter
status
string 
required
Current status of the transaction
commodity
string 
required
Type of commodity being transported
category
string 
required
Category
group_id
integer 
required
ID of the group
price_wg
number 
required
Chargeable weight
teu
integer 
required
Twenty-foot Equivalent Unit
saler_name
string 
required
Name of the salesperson
saler_email
string 
required
Email of the salesperson
saler_office_tel
string 
required
Office telephone number of the salesperson
total_pack
number 
required
Total number of packages
carrier_name
string 
required
Carrier/Liner Name of the booking
waybill_no
string 
required
MBL No / MAWB No / CIM No /Transit Doc. No
container_nos
array [object {2}] 
required
Container Numbers of the booking
size
string 
required
Size of the container
container_no
string 
required
Container No
timelines
array [object {26}] 
required
Timelines related to the transaction
id
integer 
required
ID of the timeline
parent_type
string 
required
Type of parent entity
parent_id
integer 
required
ID of the parent entity
status_date
string <date-time>
required
Date of the status update
status_code
string 
required
Code representing the status
place_id
integer 
required
ID of the place
city_id
integer 
required
ID of the city
country_id
string 
required
ID of the country
notes
string 
required
Additional notes
source
string 
required
Source of the status update
group_id
integer 
required
ID of the group
user_id
integer 
required
ID of the user
patron_id
integer 
required
ID of the patron
customer_inform_type
boolean 
required
Indicates if the customer was informed
customer_inform_status
string 
required
Status of informing the customer
created_at
string <date-time>
required
Timestamp of creation
updated_at
string <date-time>
required
Timestamp of last update
lng
number 
required
Longitude coordinate
lat
number 
required
Latitude coordinate
place_name
string 
required
Name of the place
notify_senders
boolean 
required
Indicates if senders were notified
notify_consignees
boolean 
required
Indicates if consignees were notified
notify_companies
boolean 
required
Indicates if companies were notified
tenant_id
integer 
required
ID of the tenant
icon_code
string 
required
Fontawsome code
system_location
string 
required
System location
Example
[
    {
        "transaction_id": 0,
        "uuid": "string",
        "reference": "string",
        "branch_id": 0,
        "company_uuid": "string",
        "company_name": "string",
        "customer_ref": "string",
        "agent_ref": "string",
        "consignee_name": "string",
        "sender_name": "string",
        "load_place_id": 0,
        "load_city": "string",
        "load_zipcode": "string",
        "load_coun": "string",
        "load_place": "string",
        "load_date": "2019-08-24T14:15:22Z",
        "unload_place_id": 0,
        "unload_city": "string",
        "unload_zipcode": "string",
        "unload_coun": "string",
        "unload_place": "string",
        "unload_date": "string",
        "brut_wg": 0,
        "volume": 0,
        "ladameter": 0,
        "status": "string",
        "commodity": "string",
        "category": "string",
        "group_id": 0,
        "price_wg": 0,
        "teu": 0,
        "saler_name": "string",
        "saler_email": "string",
        "saler_office_tel": "string",
        "total_pack": 0,
        "carrier_name": "string",
        "waybill_no": "string",
        "container_nos": [
            {
                "size": "string",
                "container_no": "string"
            }
        ],
        "timelines": [
            {
                "id": 0,
                "parent_type": "string",
                "parent_id": 0,
                "status_date": "2019-08-24T14:15:22Z",
                "status_code": "string",
                "place_id": 0,
                "city_id": 0,
                "country_id": "string",
                "notes": "string",
                "source": "string",
                "group_id": 0,
                "user_id": 0,
                "patron_id": 0,
                "customer_inform_type": true,
                "customer_inform_status": "string",
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "lng": 0,
                "lat": 0,
                "place_name": "string",
                "notify_senders": true,
                "notify_consignees": true,
                "notify_companies": true,
                "tenant_id": 0,
                "icon_code": "string",
                "system_location": "string"
            }
        ]
    }
]
🟠400Bad Request
🟠403Forbidden
🟠404Record Not Found
🟠422Unprocessable Entity
Modified at 2025-03-04 09:48:50
Previous
List all Bookings
Next
Update a Booking
Built with