The Flexport API allows you to automate the creation of booking requests (i.e. load tenders) from an external system. This endpoint replicates the functionality of the user interface available here, which is the starting point for the requesting freight service from Flexport.

The Booking API allows you to create a booking, list all bookings, and retrieve the booking details.

Endpoints

 GET /bookings
POST /bookings
 GET /bookings/id
POST /booking_amendments
 GET /booking_line_items
POST /booking_line_items
 GET /booking_line_items/id

Here’s the general workflow for a booking request:

• A HTTP POST request is made to /bookings endpoint mentioned above
• The Flexport API responds synchronously, either with a positive acknowledgment (HTTP 200) or a negative acknowledgment (HTTP 400). You don’t need to do anything else in the case of a positive acknowledgment. Should you receive a negative acknowledgment, the body of the response will provide a descriptive error message
• The booking will then be submitted for asynchronous processing to Flexport operations
• In case there are any changes in the booking request, an update may be submitted to the /booking_amendments endpoint available https://api.flexport.com/booking_amendments

Note that Flexport operations reviews update requests asynchronously.

In order for a booking to be received successfully, Flexport requires coded references for the following:

• Consignee Party
• Shipper Party
• Origin Address
• Destination Address

The following images show the parties and locations to pre-configure:

These parties and locations must be pre-configured in your network prior to getting started. You may use Flexport-assigned network identifiers when making an API call to point to these entities, or you may configure your own in-app. Responsible parties are identified as Legal Entities in your network. Origin and Destination addresses are identified as Locations.

If you require shipment tags to be provided in your bookings (as metadata that will be copied over to resulting shipments), they must be pre-configured in your account. Please contact Flexport operations to inquire about setting up shipment tags for your bookings.

To get the parameters for creating a booking request, click here.

curl -X "POST" "https://api.flexport.com/bookings" \
     -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
     -H 'Flexport-Version: 3' \
     -H 'Content-Type: application/json' \
     -d $'{
        "delivery_date": "2020-08-15",
        "origin_address_ref": "VN240948",
        "cargo": {
          "volume": {
            "value": 338.95,
            "unit": "cbm"
          },
          "weight": {
            "value": 28755,
            "unit": "kg"
          },
          "shipping_units": [
            {
              "count": 4010,
              "unit_type": "carton",
              "atomic_count": 4010
            }
          ],
          "contains_hazmat": false,
          "contains_li_ion": false,
          "contains_non_li_ion_battery": false,
          "contains_magnets": false,
          "contains_other_dangerous_goods": false
        },
        "destination_address_ref": "MV240984",
        "shipper_entity_ref": "VN245960",
        "cargo_ready_date": "2020-07-10",
        "wants_export_customs_service": false,
        "ocean_booking": {
          "is_lcl": false,
          "product_descriptions": [
            {
              "hs_code": "8508.11",
              "description": "VACUUM CLEANER"
            }
          ],
          "wants_pickup_service": false,
          "container_counts": {
            "_object": "/container_counts",
            "forty_ft_hc": 5
          },
          "incoterm": "FOB",
          "wants_delivery_service": true,
          "origin_port_loc_code": "VNSGN",
          "destination_port_loc_code": "USLAX"
        },
        "metadata": {
          "pr_number": [
            "4500000021"
          ]},
        "name": "1000000001",
        "consignee_entity_ref": "US334132"
      }'

If successful (HTTP 200), you will receive a booking id in the body of the response.

{
  "_object": "/api/response", 
  "flex_id": "FLEX-836453", 
  "id": 317606, 
  ...
}

You may use the id you obtained during the submission of the booking request to show your booking using HTTP GET. For example:

curl -X "GET" "https://api.flexport.com/bookings/317606" \
     -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
     -H 'Flexport-Version: 3' \
     -H "Content-Type: application/json" \

Alternatively, you may query by your assigned metadata (shipment tags). For example:

curl -X "GET" "https://api.flexport.com/bookings?f.metadata.reference=1000000001 " \
     -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
     -H 'Flexport-Version: 3' \
     -H "Content-Type: application/json" \     

You may update a booking using the dedicated /booking_amendments endpoint. This endpoint accepts a limited set of parameters, outlined here.

Prior to updating a booking, you must know the booking id. Let’s take a case in which we want to update the cargo ready date for a booking (and only the cargo ready date). Using booking id 317607, we are able to submit the following:

curl -X "POST" "https://api.flexport.com/booking_amendments" \
     -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
     -H 'Flexport-Version: 2' \
     -H 'Content-Type: application/json' \
     -d $'{
            "booking_id": "317607",
            "new_cargo_ready_date": "2021-08-11"
          }'

Note that booking amendments are only allowed up to departure from origin.

• The booking request API does not enforce uniqueness for external references (name, metadata keys). To prevent duplication of requests to Flexport operations, you should query the /bookings endpoint by your chosen unique reference prior to submitting a HTTP POST request.
• Unless you know all of your package details, only submit one item in cargo.shipping_units along with cargo.weight and cargo.volume.
• When submitting a new booking request, use only one of ocean_booking, trucking_booking, or air_booking (do not mix modes).
• container_counts must be an integer greater than 0. If a container type is not requested, please omit it from the request.

You can filter the response on the parameters mentioned in the reference document.

You can check the error message when an issue occurs by looking at the message field in the API response. Here’s an example of an Error Response:

{
  "_object": "/api/response",
  "self": "https://api.flexport.com/bookings",
  "version": null,
  "data": null,
  "error": {
    "_object": "/api/error",
    "status": 400,
    "code": "invalid_param",
    "message": "shipper_entity_ref does not exist in your network"
  }
}

Use the message fields to handle exceptions. Let’s take a look at possible values in those fields:

• (entity/location_ref) does not exist in your network
• Missing property
• One shipping unit must be specified for undetailed cargo
• Cargo dimensions and shipping unit dimensions must be all metric or all imperial
• Unable to set metadata. Make sure each key exists in the company's schema.