Curl Ruby

My Flying Box Web Service Reference documentation

The My Flying Box (MFB) Web Service provides an interface to request shipment offers from multiple carriers in an homogenous way and place bookings for these offers.

By implementing this web service you will have access to a wide range of competitive rates without needing to implement other APIs, saving you time and money.

This documentation is meant for technical people implementing the MFB Web Service on their systems. It provides an exhaustive description of all exposed resources and the way to manipulate them, with corresponding code examples in several languages.

Please note that you can contact us at tech@myflyingbox.com if you need any help. We can also provide you with integration services if needed.

For direct use in your application and for example purposes, we also provide some client libraries for PHP, Prestashop and WooCommerce.

How to use the code examples?

This column contains code examples for most features of the MFB Web Service.

Supported languages are listed on top of the column. You can dynamically switch depending on your needs.

We tried to make 'copy/paste'-friendly examples (for instance curl commands) to ease your development and testing process. Feel free to contact us at tech@myflyingbox.com with feedback or improvement suggestions.

Getting started

Workflow

Before diving into technical details, here is a summary of the general workflow of the web service. Items corresponding to a request to the webservice are linked to the corresponding section of the documentation; other items are actions to be performed on your side only.

Prepare your shipment information: shipper, recipient, pack-list.
Request a quote (passing shipment information).
Select an offer.
If necessary request a list of available delivery locations.
Place a booking on your selected offer (passing complementary shipment details: shipper and recipient details, extra pack-list details).
Download labels
Track your parcels

Test server

When your account is registered on the web service, you will receive an ID and password for a test server only. You must use the test server to fully implement the web service. When your implementation is ready, contact us to obtain ID and password for the production server.

TEST server base URL: https://test.myflyingbox.com/v2
PRODUCTION server base URL: https://api.myflyingbox.com/v2

REST services

The MFB Web Service uses REST resources in a standardized way throughout the API. All request declarations are semantically meaningful:

POST requests to create a new object
GET requests to retrieve an existing object

At the moment we have no use for PUT, PATCH and DELETE requests.

Available routes

The base URL for all your requests is the following : https://api.myflyingbox.com/v2

All the URIs below should be appended to the base URL.

GET: / Access some basic information about the MFB Web Service.
POST: /quotes Request a new quote, returning a set of offers.
GET: /quotes Retrieve a collection of all your past quotes.
GET: /quotes/:id Retrieve a specific quote with its ID.
GET: /offers/:id Returns a particular offer (received within a quote).
GET: /offers/:id/available_delivery_locations Returns a set of relevant delivery locations, for offers that do not propose at-the-door delivery.
POST: /orders Book an offer (returns an order object).
GET: /orders/:id Returns an existing order.
GET: /orders/:id/labels Download the raw PDF of the generated labels for an order.
GET: /orders/:id/tracking Returns the current tracking status of an existing order, for each parcel.

Authentication

You cannot use the MFB Web Service without authentication.

Authentication is stateless (there is no persistence), so you will need to include your credentials on every request.
Authentication is done through the HTTP Basic Access Authentication method.

Example request

curl https://api.myflyingbox.com/v2/ -u login:password

require 'net/http' # Or 'net/https' for ruby version < 2.0.0

uri = URI('https://api.myflyingbox.com/v2/quotes')

Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
  request = Net::HTTP::Get.new uri
  request.request :basic_auth, 'login', 'password'
  response = http.request request # Net::HTTPResponse object
end

Response with failed authentication (HTTP response code 401)

{
  "status":"failure",
  "error":{
    "type":"access_denied",
    "message":"Unauthorized"
  },
  "self":"https://api.myflyingbox.com/v2"
}


  failure
  
    access_denied
    Unauthorized
  
  api.myflyingbox.com/v2/v2

Requests

All requests use the HTTP protocol.

Content must be encoded in UTF-8.

The web service supports two formats for passing request attributes:

JSON: JSON is the preferred format to send request attributes.
Plain form fields: This format is similar to what is sent by a traditional web form.

Whatever format you use, make sure that the proper "content-type" header is used.

Check out the code example for quote requests for an example of curl requests using each format approach.

Responses

Response format

Responses are sent in JSON format.

Most programming languages include well supported JSON libraries, which you can use to manipulate the response data.

All text is encoded in UTF-8 character set. If your system is not using UTF-8, make sure that you use proper conversion methods for all interactions with the web service.

Response attributes

Responses are encapsulated in a basic envelop described below.

All responses contain the 'status' and 'self' attributes.
Responses with errors (status = failure) also contain an 'error' attribute containing an explanation on why the request failed.
Responses for successful requests also contain a 'data' attribute containing the actual data pertaining to your request. If the root data is an array of objects (e.g. if you query the index of a given resource, like a list of past orders), a 'count' attribute will also be present.

self

string (URL) Returns the complete URL which was queried to generate this response.

status

string Possible values: failure, success When 'failure' is returned, the 'error' attribute is populated with the cause of the failure.

data

array or hash Possible values: array of objects, quote, order, etc. This attribute is only present for successful requests (status = success). It is populated with objects (single or in an array), depending on your request. Please go to the resources section for details on all object attributes.

count

integer Possible values: 1, 15, etc. (any integer superior or equal to 1) This attribute is only present when the 'data' attribute contains an array of objects, and contains the total number of objects in the array.

error

hash (hide/show attributes) Only returned when the request 'status' attribute is set to 'failure'.

type: string An string-formatted error code.
message: string Human readable error message. Always returned in English. If you wish to implement translations, you can base them on the 'type' attribute.

Error codes

When sending a query to the MFB Web Service, you have access to three sources of information to interpret the success or failure of your request:

The HTTP response code and description
The 'status' attribute, containing either 'success' or 'failure'
The 'error' node and its 'type' attribute, only if 'status' returns 'failure'

Please note that two other attributes are available for debugging purposes if you get query errors:

error:message contains a string in English with generic details about the error. If your system is implemented only in English language, you may use the error:message directly. Otherwise, we recommend that you ignore this attribute for any automated mechanism, and use it only for debugging or logging purposes.
error:details is returned only with HTTP code 422 (error while creating a resource). It contains a detailed description of while the saving failed. Use it only for debug purposes.

Below are presented the different HTTP response codes with corresponding error types. You can base your implementation on these codes.

200: Request successful. Successful queries do not transmit an 'error' node. Only the 'status' attribute is present, with the value 'success'.
201: Resource created successfully. Successful queries do not transmit an 'error' node. Only the 'status' attribute is present, with the value 'success'.
401: access_denied You do not have access to the queried resource, either because you are not authenticated or because you do not have sufficient access rights.
404: not_found The queried URI does not correspond to any known path in the MFB Web Service.
404: resource_not_found The query corresponds to a known path, but the corresponding resource could not be found (wrong ID, for instance).
404: labels_not_ready The PDF containing labels to be printed is not yet available. You should try again later.
This error code is specific to the route GET /orders/:id/labels.
422: resource_not_created The query attempted to create a resource, but the creation failed. Check the 'details' attribute of the response for detailed error messages.
500: internal Catch-all error code for server malfunction. Encountering such an error does not mean that you are doing anything wrong, but rather that the web service is not working properly.

Response for non-existent quote with ID 3 (HTTP code 404)

{
  "status":"failure",
  "error":{
    "type":"resource_not_found",
    "message":"Quote not found"
  },
  "self":"https://api.myflyingbox.com/v2/quotes/3"
}

Request a quote

A quote contains a set of transportation offers. When requesting a new quote, you must send your shipment requirements (packages specifications, dates, shipper and recipient information) in the expected format (see 'Request parameters' below).

After you have received a quote, you can order any offer returned within this quote (see place an order below). Please note that when placing the order you cannot change the country or postal code of the shipper and recipient, and you cannot change the pack-list either. If you need to alter these details, you must request a new quote with the correct information.

Request URL

POST: https://api.myflyingbox.com/v2/quotes

Request parameters

Parameters must be encapsulated within a root element 'quote' (see code example on the right).

parcel_type: string package or document The type of parcel you are shipping. If not present package will be used by default. Must the same value as parcels[0][type]. Document will only work with 1 parcel.

shipper

hash (hide/show attributes) Information regarding the location of departure of the shipment.

country: varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code: string Postal code of the collection location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city: string City name

recipient

hash (hide/show attributes) Information regarding the destination of the shipment.

is_a_company: boolean (true/false) Is the delivery location a company place?
country: varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code: string Postal code of the delivery location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city: string City name

parcels

array (hide/show attributes) A collection of parcels, forming the pack-list of your shipment. When specifying more than one parcel, make sure that you have the capacity to submit the list in the same order when booking an offer (see place an order below).

type: string package or document The type of parcel you are shipping. If not present, package will be used by default. Must the same value as parcel_type in the quote. Only 1 parcel is allowed for documents.
length: integer e.g. 153 Length of the parcel, in centimeters (cm). Only integers are allowed.
width: integer e.g. 82 Width of the parcel, in centimeters (cm). Only integers are allowed.
height: integer e.g. 55 Height of the parcel, in centimeters (cm). Only integers are allowed.
weight: float e.g. 12.5 Weight of the parcel, in kilograms (kg). You can only use '.' (dot) as decimal separator. If there is anything else than numbers and a dot separator (e.g. 1,400.5) an error will be returned.
insured_value: float e.g. 30.25 Value of parcel to insure. If specified, offers will include (separately) the price of the 'ad valorem insurance' option. This value is not used to fill the parcel's customs value when ordering an offer, and works therefore in a totally independent manner.
insured_currency: string e.g. EUR Currency for the value specified in 'insured_value'. Mandatory if the field 'insured_value' is specified.

offers_sort_attributes

hash e.g. {"total_price": "asc"} The attributes and directions used for sorting offers. For now, only the total_price attribute is supported. The directions for sorting are "asc" and "desc" for ascending and descending respectively.

offers_filters

hash (hide/show attributes) Filter offers by carriers or product codes.

with_drop_off: boolean Includes offers for the product with the "drop off" flag set to to true. The available offers will support drop-off to carrier locations (for example in a partnered shop near the shipper).
with_pick_up: boolean Includes offers for the product with the "pick up" flag set to to true. The available offers will support pick up at the shipper location by the carrier.
with_preset_delivery_location: boolean Includes offers for the product with the "preset delivery location" flag set to to true. The available offers will support delivery at carrier locations (for example in a partnered shop near the recipient).
with_carrier_codes: array of strings Limit offers to this list of carrier codes
with_product_codes: array of strings Limit offers to this list of product codes
without_carrier_codes: array of strings Exclude offers matching this list of carrier codes
without_product_codes: array of strings Exclude offers matching this list of product codes

Example request with JSON

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{"quote": {
        "shipper": {
          "country":"GB",
          "postal_code": "SW1A 1AA",
          "city": "London"
        },
        "recipient": {
          "is_a_company": "false",
          "country": "FR",
          "postal_code": "31300",
          "city": "Toulouse"
        },
        "parcels": [
          {
            "weight": 1,
            "length": 60,
            "width": 60,
            "height": 40
          },
          {
            "weight": 2.5,
            "length": 30,
            "width": 30,
            "height": 20
          }
        ]
      }}'

Example request with offers_filters in JSON

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{"quote": {
        "shipper": {
          "country":"GB",
          "postal_code": "SW1A 1AA",
          "city": "London"
        },
        "recipient": {
          "is_a_company": "false",
          "country": "FR",
          "postal_code": "31300",
          "city": "Toulouse"
        },
        "parcels": [
          {
            "weight": 1,
            "length": 60,
            "width": 60,
            "height": 40
          },
          {
            "weight": 2.5,
            "length": 30,
            "width": 30,
            "height": 20
          }
        ],
        "offers_filters": {
          "with_carrier_codes": ["ups"]
          "without_product_codes": ["ups_access_point_standard"]
        }
      }}'

Example request with plain fields

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-d "quote[shipper][country]=GB" \
-d "quote[shipper][postal_code]=SW1A 1AA" \
-d "quote[shipper][city]=London" \
-d "quote[recipient][country]=FR" \
-d "quote[recipient][postal_code]=31300" \
-d "quote[recipient][city]=Toulouse" \
-d "quote[recipient][is_a_company]=false" \
-d "quote[parcels][][weight]=1" \
-d "quote[parcels][][length]=60" \
-d "quote[parcels][][width]=60" \
-d "quote[parcels][][height]=40" \
-d "quote[parcels][][weight]=2.5" \
-d "quote[parcels][][length]=30" \
-d "quote[parcels][][width]=30" \
-d "quote[parcels][][height]=20"

Example request with JSON for document shipment

curl https://test.myflyingbox.com/v2/quotes -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "quote": {
          "parcel_type": "document",
          "parcels": [
              {
                  "type": "document",
                  "weight": 0.5
              }
          ],
          "recipient": {
              "city": "Toulouse",
              "country": "FR",
              "is_a_company": false,
              "postal_code": "31300"
          },
          "shipper": {
              "city": "Nice",
              "country": "FR",
              "postal_code": "06000"
          }
      }
  }'

Retrieve an existing quote

Request URL

GET: https://api.myflyingbox.com/v2/quotes/:id

Quote attributes

id

uuid e.g. 4d6cc11f-8552-4497-bb24-d715b93ccfa9 Internal unique identifier for this quote.

created_at

timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of creation.

shipper

hash (hide/show attributes) All relevant information regarding the collection of the parcels.

postal_code: string e.g. SW1A 0AA, NY 10001, 79450
country: string e.g. FR, UK, NZ Country code of collection address, on two letters (norm ISO 3166-1 alpha-2)

recipient

hash (hide/show attributes) All relevant information regarding the delivery of the parcels.

is_a_company: boolean Tells whether the delivery location is a company location (true) or a residential location (false).
postal_code: string e.g. SW1A 0AA, NY 10001, 79450
country: string e.g. FR, UK, NZ Country code of delivery address, on two letters (norm ISO 3166-1 alpha-2)

parcels

array (hide/show attributes) A collection of parcels, forming the pack-list of your shipment.

length: integer e.g. 153 Length of the parcel, in centimeters (cm).
width: integer e.g. 82 Width of the parcel, in centimeters (cm).
height: integer e.g. 55 Height of the parcel, in centimeters (cm).
weight: float e.g. 12.5 Weight of the parcel, in kilograms (kg).

offers

array A collection of offers from different carriers and levels of service. You can choose any offer by placing an order.
Jump to offer attributes for details on offer formatting and attributes.

Example representation of a quote in JSON

{
  "id": "2a4a628c-e541-4571-b817-a57cc3f89a1b",
  "shipper": {
    "postal_code": "AB1 6CC",
    "country": "GB"
  },
  "recipient": {
    "is_a_company": "true",
    "postal_code": "06800",
    "country": "FR"
  },
  "parcels": [
    {
      "weight": 3,
      "length": 40,
      "width": 30,
      "height": 10,
    },
    {
      "weight": 1.75,
      "length": 50,
      "width": 10,
      "height": 10,
    }
  ],
  "offers": [
    {
      "id":"6d37b0ed-833d-4a59-9e57-d6bd7d935c9b",
      "quote_id":"270cf4a5-e99f-45a5-9dca-1bf75cd3ca64",
      "product_id":"732e50b7-ed0e-424a-8631-51c5135d2b23",
      "product":{
        "id":"732e50b7-ed0e-424a-8631-51c5135d2b23",
        "carrier_code":"dhl",
        "code":"dhl_worldwide_express",
        "name":"Worldwide Express",
        "delay":"24",
        "pick_up":true,
        "drop_off":false,
        "preset_delivery_location":false
      },
      "price":{
        "formatted":"€293.68",
        "currency":"EUR",
        "amount":293.68,
        "amount_in_cents":29368
      },
      "price_vat":{
        "formatted":"€57.56",
        "currency":"EUR",
        "amount":57.56,
        "amount_in_cents":5756
      },
      "total_price":{
        "formatted":"€351.24",
        "currency":"EUR",
        "amount":351.24,
        "amount_in_cents":35124
      },
      "collection_dates":[
        {
          "date":"2013-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2013-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2013-11-18",
          "cutoff":"If you book before 1pm on Monday, or book up to a week in advance"
        }
      ]
    },
    {
      "id":"33a60039-ea0c-4855-b9aa-616690288a4a",
      "quote_id":"270cf4a5-e99f-45a5-9dca-1bf75cd3ca64",
      "product_id":"46dc8970-c48a-4420-a85c-6dd31becba00",
      "product":{
        "id":"46dc8970-c48a-4420-a85c-6dd31becba00",
        "carrier_code":"dpd",
        "code":"dpd_air_express",
        "name":"Air Express",
        "delay":"96",
        "pick_up":true,
        "drop_off":false,
        "preset_delivery_location":false
      },
      "price":{
        "formatted":"€240.74",
        "currency":"EUR",
        "amount":240.74,
        "amount_in_cents":24074
      },
      "price_vat":{
        "formatted":"€47.19",
        "currency":"EUR",
        "amount":47.19,
        "amount_in_cents":4719
      },
      "total_price":{
        "formatted":"€287.93",
        "currency":"EUR",
        "amount":287.93,
        "amount_in_cents":28793
      },
      "collection_dates":[
        {
          "date":"2013-11-14",
          "cutoff":"If you book before 1pm on Thursday, or book up to a week in advance"
        },
        {
          "date":"2013-11-15",
          "cutoff":"If you book before 1pm on Friday, or book up to a week in advance"
        },
        {
          "date":"2013-11-18",
          "cutoff":"If you book before 1pm on Monday, or book up to a week in advance"
        }
      ]
    }
  ]
}

Offers

An offer is proposed by a carrier with a price and some conditions. Offers are sold under MFB product names, with corresponding logos and several variants.

Offers returned by the web service cannot be accessed independently from the quote or order they are linked to; they are returned as a collection in quotes or as single objects in orders.

Offer attributes

id

uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for this offer.

quote_id

uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID of the quote to which this offer belongs.

product_id

uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID of the MFB product for this offer (see below for product details). In most cases you should no need to do anything with this ID, and should rather rely on the product code.

vat_scheme_code

string e.g. FR_20, reverse_charge, exempted_exportation, exempted_importation... Internal code expressing the applicable VAT rule for the invoicing of the shipping costs. As the list may change, make sure to implement auto-discover mechanisms if you use this information in any automated process.

product

hash (hide/show attributes) Characteristics of the transport product proposed.

id: uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 ID of the MFB product. In most cases you should no need to do anything with this ID, and should rather rely on the product code.
code: string e.g. dhl_express_worldwide MFB product code. This is the unique identifier for a given service.
carrier_code: string e.g. dhl Code of the carrier for this service. You could use this to determine what logo to use, for instance.
name: string e.g. Worldwide Express Textual denomination of the product as defined by the carrier. If you plan to translate product names, use the product code as key (the name might change).
delay: integer or interval e.g. 24, or 48-72 Estimated delivery delay for this product. This is NOT a guaranteed delay and should only be considered as an estimation. The format is either an integer (hours) or an interval (shortest possible delivery delay in hours, hyphen, theoretical longest delivery delay in hours, eg. 24-48).
pick_up: boolean e.g. true, false Indicates whether this product allows for parcel pick-up at the shipper's address.
drop_off: boolean e.g. true, false Indicates whether this product allows for parcel drop-off at a carrier-defined drop-off location.
preset_delivery_location: boolean e.g. true, false Indicates whether this product allows for parcel delivery at a predifined location.
support_delayed_pickup: boolean e.g. true, false Indicates whether this product allows for delayed pickups.

price

price hash (hide/show attributes) Price without VAT.

formatted: string e.g. 56,50€ Price formatted as a string with currency symbol, for direct display.
currency: string e.g. EUR Currency code, as per ISO 4217.
amount: float e.g. 56.50 Amount returned as a float (with dot separator).
amount_in_cents: integer e.g. 5650 Amount returned as an integer, in cents (the two last digits of the integer are cents). You should favor this attribute if you need to manipulate prices, as it is the most neutral.

price_vat

price hash VAT amount of the offer. This is *only* the VAT part.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

total_price

price hash Total price, including VAT. Does NOT include insurance price (when applicable)!
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

insurable

boolean e.g. true, false Indicates if this offer is insurable by our insurance provider.

insurance_price

price hash Price of the insurance option, when applicable (only present when the quote request parcels include a value to insure [insured_value/insured_currency]). The price is BEFORE VAT. The VAT rate of the shipment will be applied when booking.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

extended_cover_available

boolean e.g. true, false Indicates if this offer can be covered by My Flying Box's Extended Cover.

price_with_extended_cover

price hash Price including extended cover without VAT.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

price_vat_with_extended_cover

price hash VAT amount of the offer with extended. This is *only* the VAT part.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

total_price_with_extended_cover

price hash Total price, including extended cover and VAT.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

extended_cover_max_liability

price hash The maximum liabilty amount covered by the Extended Cover for this offer.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

collection_dates

array (hide/show attributes) List of possible dates for collection of your parcels (for pickup only).

date: date e.g. 2013-10-07 Collection date.
cutoff: string e.g. If you book before 1pm today, or book up to a week in advance Description of conditions for pickup at this date.

support_electronic_customs

boolean e.g. true, false Indicates whether this offer support electronic customs declaration.

mandatory_electronic_customs

boolean e.g. true, false Indicates whether electronic customs declaration is mandatory.

Delivery locations

For offers where parcels are delivered at a predefined delivery location (as opposed to at-the-door delivery), the MFB Web Service gives you access to the list of predefined locations available for this offer.

To know which offers are concerned, you must check the offer's product attribute 'preset_delivery_location'. If set to true, the delivery will be done at a preset location, and not at the recipient's address.

To get the most relevant locations, you must pass a detailed address in your request. A set of available delivery locations will be returned, sorted by relevance (most relevant first).

Request URL

GET: https://api.myflyingbox.com/v2/offers/:id/available_delivery_locations Replace :id with the UUID of the offer.

Request parameters

location

hash (hide/show attributes) Address of the recipient, to determine the nearest delivery location available.

street: string Street details (name, number, additional details) used by the seartch. If you need multiline addresses, please use line-breaks.
city: string City of the recipient.

Response attributes

The request will return a collection of locations. Each location has the following attributes:

company

string Name of the company.

street

string (multiline) Lines of address, as a string with line-break (\n).

postal_code

string Postal code of the location.

city

string City of the location.

opening_hours

array Information regarding the opening hours of the location. Contains a list of weekdays with corresponding opening times.

day: integer Number of the day, between 1 (Monday) and 7 (Sunday).
hours: string e.g. 09:00-12:00 15:15-19:00 Opening hours, in a format which should be displayable as is.

Drop-off locations

For offers where parcels are dropped off at a predefined drop-off location (as opposed to a pickup), the MFB Web Service gives you access to the list of predefined locations available for this offer.

To know which offers are concerned, you must check the offer's product attribute 'drop_off'. If set to true, the collection can be done at a preset drop-off location, and not at the shipper's address.

To get the most relevant locations, you must pass a detailed address in your request. A set of available drop-off locations will be returned, sorted by relevance (most relevant first).

Request URL

GET: https://api.myflyingbox.com/v2/offers/:id/available_drop_off_locations Replace :id with the UUID of the offer.

Request parameters

location

hash (hide/show attributes) Address of the shipper, to determine the nearest drop-off location available.

street: string Street details (name, number, additional details) used by the seartch. If you need multiline addresses, please use line-breaks.
postal_code: string Postal code of the shipper.
city: string City of the shipper.
country: string ISO 3166-1 alpha-2 code for the country of the shipper.

Response attributes

The request will return a collection of locations. Each location has the following attributes:

company

string Name of the company.

street

string (multiline) Lines of address, as a string with line-break (\n).

postal_code

string Postal code of the location.

city

string City of the location.

country

string country of the location.

latitude

decimal Latitude of the location.

longitude

decimal Longitude of the location.

opening_hours

array Information regarding the opening hours of the location. Contains a list of weekdays with corresponding opening times.

day: integer Number of the day, between 1 (Monday) and 7 (Sunday).
hours: string e.g. 09:00-12:00 15:15-19:00 Opening hours, in a format which should be displayable as is.

Place an order (= book an offer)

Creating an order object means that you are booking a transport on the basis of an offer and its corresponding quote attributes (collection and delivery postal codes and countries, pack-list). A successfully created order is contractually binding: you will be invoiced for all orders you created, on the basis of the final price transmitted by the carrier.

Request URL

POST: https://api.myflyingbox.com/v2/orders

Request parameters

Parameters must be encapsulated within the root element 'order'.

Please note that the following data will be automatically retrieved from the original quote and cannot be changed while placing the order: postal code and country of the shipper and recipient, list of parcels and their characteristics. If you need to change these data, you must first request a new quote, and place a new order for the corresponding offer. You can use the product code of the offer to make sure that you order the same service as initially intended.

offer_id

uuid e.g. a3dd9019-df68-486b-9817-0a2cc6f3747c The ID of the offer for which you place this order.

thermal_labels

boolean e.g. true, false If true, the API will try to return the labels in a thermal printer-friendly format. This is not possible for all services.

insure_shipment

boolean e.g. true, false If true, the shipment will be insured 'ad valorem', based on the value specified during the quote request. Warning: the insured value is NOT the customs value specified during the order booking!

with_extended_cover

boolean e.g. true, false If true, the shipment will be covered by the Extended Cover, based on the value specified during the quote request.

delay_pickup_order

boolean e.g. true, false If true, the pickup will not be requested at the same time as the order. You will neet to call pickup creation request. This can only work on the products with the attribut support_delayed_pickup is 'true'.

ecommerce_order_platform

string e.g. shopify The name of ecommerce platform that you are using. Only shopify is supported for now.

ecommerce_order_identifier

string The identifier of the shipment on the ecommerce platform.

ecommerce_order_reference

string The reference of the shipment on the ecommerce platform.

inform_shipper_about_insurance

boolean e.g. true, false If applicable, this will inform the shipper about insurance. (In the label and/or by email)

inform_recipient_about_insurance

boolean e.g. true, false If applicable, this will inform the recipient about insurance. (In the label and/or by email)

declare_customs_electronically

boolean e.g. true, false If applicable, you can request to declare the customs electronically. support_electronic_customs must be true in the offer.

shipper

hash (hide/show attributes) Details regarding the location of departure of the shipment.

name: string Name of a contact at the collection location.
company: string Optional company name for the collection location.
street: string Street details (name, number, additional details) for the pickup location. If you need multiline addresses, please use line-breaks (cf. code example).
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
phone: string e.g. +33123456789 Phone number of the shipper, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.
collection_date: string (date or datetime) e.g. 2013-10-01 or 2013-10-01T10:41:14+03:00 Requested collection date (norm ISO-8601).
Used only for offers where the product includes pickup at the shipper's address (see offer attributes above).
If the offer for which you place a booking contained a set of proposed collection dates, you must use the exact same string. Otherwise you must manually put a date/datetime. Remember that the exact pickup date and time depends on the time of the booking and the product. Most products have strict deadlines for same-day pickups.
vat_number: string e.g. FR12345678901 Shipper Vat Number (EU/GB). The VAT identifier of the company for electronic customs declaration.
eori_number: string e.g. GB123456123456 Shipper EORI Number (EU/GB). The EORI identifier of the company for electronic customs declaration.
ein: string e.g. 12-3456789 Shipper EIN number for the United States (US). The EIN identifier of the company for electronic customs declaration.
business_number: string e.g. 123456789 Shipper BN number for Canada (CA). The Business Number of the company for electronic customs declaration.
ide: string e.g. CHE-123.456.789 Shipper IDE number for Swiss (CH). The IDE identifier of the company for electronic customs declaration.
ioss: string e.g. IM0123456789 The IOSS identifier used for VAT declaration if the recipient is in EU and is not a company.
hmrc: string e.g. k1234567890123 The HMRC identifier used for VAT declaration if the recipient is in the United Kingdom (GB) and is not a company.
voec: string e.g. 2123456 The IOSS identifier used for VAT declaration if the recipient is in Norway (NO) and is not a company.
business_identification_number: string e.g. 123456789 Local Company identifier of the shipper company - if nothing above applies.
tax_identification_number: string e.g. 123456789 Local Fiscal identifier of the shipper company - if nothing above applies

recipient

hash (hide/show attributes) Information regarding the destination of the shipment.

name: string Name of a contact at the delivery location.
company: string Company name for the delivery location.
Mandatory if the quote request has a recipient attribute 'is_a_company' at true, optional otherwise.
location_code: string Code of pickup location, when delivery occurs at a predetermined pickup point (opposed to home delivery). When a location code is specified, the attributes company, street, city and state are totally ignored by the web service (they will be overridden by the address of the pickup point).
street: string Street details (name, number, additional details) for the delivery location. If you need multiline addresses, please use line-breaks (cf. code example).
Will be ignored if location_code is set!
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
Will be ignored if location_code is set!
phone: string e.g. +33123456789 Phone number of the recipient, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the recipient. Make sure you check the validity of the email address.
vat_number: string e.g. FR12345678901 Recipient Vat Number (EU/GB). The VAT identifier of the company for electronic customs declaration.
eori_number: string e.g. GB123456123456 Recipient EORI Number (EU/GB). The EORI identifier of the company for electronic customs declaration.
ein: string e.g. 12-3456789 Recipient EIN number for the United States (US). The EIN identifier of the company for electronic customs declaration.
business_number: string e.g. 123456789 Recipient BN number for Canada (CA). The Business Number of the company for electronic customs declaration.
ide: string e.g. CHE-123.456.789 Recipient IDE number for Swiss (CH). The IDE identifier of the company for electronic customs declaration.
business_identification_number: string e.g. 123456789 Local Company identifier of the recipient company - if nothing above applies.
tax_identification_number: string e.g. 123456789 Local Fiscal identifier of the recipient company - if nothing above applies

parcels

array (hide/show attributes) Complementary information regarding the parcels.
Please note that the API expects to receive exactly the same number of parcels as in the quote request, in the same order.
Do not send again the dimensions or the parcels (the dimensions passed in the quote request are used). Only send the attributes specified below, if necessary.

shipper_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the shipper. In some cases, this reference will be included on the labels.
recipient_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the recipient. In some cases, this reference will be included on the labels.
customer_reference: string e.g. Parcel 3, CS_03758 Optional customer reference used by the recipient. In some cases, this reference will be included on the labels.

The following four attributes are mandatory only if your parcels need to proceed through customs (export or other regulatory obligations):

value: integer e.g. 15 Value of the content of the parcel, rounded to the nearest integer (currency is specified separately). Used for customs.
currency: string e.g. EUR Currency of the value specified above.
description: string e.g. Books, Clothes, Gift, etc. Description of the content of the parcel (used for customs).
country_of_origin: varchar(2) e.g. FR, UK, NZ Country code of the origin country of the parcel's content, on two letters (norm ISO 3166-1 alpha-2). Used for customs.

customs_details

hash (hide/show attributes) Customs fields for commercial invoice used for electronic customs declaration.

invoice_number: string INV-FSD-4389 The commercial invoice number.
reason_for_export: string e.g. commercial The reason for the the export. Must be on of these values : commercial, gift, personal, return_for_repair, return_after_repair, warranty_replacement, sample
ship_price: float e.g. 11.67 The shipping cost as you sold it your customer.
ship_currency: string (ISO 4217) e.g. EUR Currency code for the shipping cost (EUR, USD, CAD, ...)
insurance_price: float e.g. 3.23 The insurance cost as you sold it your customer.
insurance_currency: string (ISO 4217) e.g. EUR Currency code for insurance cost (EUR, USD, CAD, ...)
remarks: string e.g. Additional remarks. Additional information to be displayed on the commercial invoice.
aes_number: string e.g. AES X20080930987654 Export declaration US.
itn_number: string e.g. X20080930987654 Export declaration US.
ftr_number: string e.g. 30.37(a) Export declaration US.
por_number: string e.g. RC1234 20070512345 Export declaration CA.
mrn_number: string e.g. 24DE1234567890ABCD Export declaration DE.
eur1_number: string e.g. B 432 654 Export declaration CH & DE.

customs_items

array (hide/show attributes) Array detailing the items for the commercial invoice used for the electronic customs declaration.

quantity: float e.g. 3 The quantity of this item.
unit_value: float e.g. 12.54 The unit value of this item. It will be multiplied by the quantity to determine the total value of the line.
value_currency: string (ISO 4217) e.g. USD ISO 4217 currency code for the unit value.
country_of_origin: string (ISO 3166-1 alpha-2) e.g. FR The origin country of the item.
customs_code: string e.g. 0304870090 HS code of the item.
description: string e.g. Hexagonal aluminum bicycle nuts The detailed description of this item.
unit_weight: float e.g. 0.243 The unit weight of the item. It will be multiplied by the quantity to determine the total weight of the line.
mass_unit: string (kg or lbs) e.g. kg The mass unit of the item.

exporter

hash (hide/show attributes) Details regarding the exporter of the shipment. Use only if the exporter is different from the shipper.

name: string Contact name of the exporter.
company: string Company name of the exporter.
street: string Street details (name, number, additional details) for the exporter. If you need multiline addresses, please use line-breaks (cf. code example).
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
phone: string e.g. +33123456789 Phone number of the exporter, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the exporter. Make sure you check the validity of the email address.
vat_number: string e.g. FR12345678901 Exporter Vat Number (EU/GB). The VAT identifier of the company for electronic customs declaration.
eori_number: string e.g. GB123456123456 Exporter EORI Number (EU/GB). The EORI identifier of the company for electronic customs declaration.
ein: string e.g. 12-3456789 Exporter EIN number for the United States (US). The EIN identifier of the company for electronic customs declaration.
business_number: string e.g. 123456789 Exporter BN number for Canada (CA). The Business Number of the company for electronic customs declaration.
ide: string e.g. CHE-123.456.789 Exporter IDE number for Swiss (CH). The IDE identifier of the company for electronic customs declaration.
ioss: string e.g. IM0123456789 The IOSS identifier used for VAT declaration if the recipient is in EU and is not a company.
hmrc: string e.g. k1234567890123 The HMRC identifier used for VAT declaration if the recipient is in the United Kingdom (GB) and is not a company.
voec: string e.g. 2123456 The IOSS identifier used for VAT declaration if the recipient is in Norway (NO) and is not a company.
business_identification_number: string e.g. 123456789 Local Company identifier of the exporter company - if nothing above applies.
tax_identification_number: string e.g. 123456789 Local Fiscal identifier of the exporter company - if nothing above applies

importer

hash (hide/show attributes) Information regarding the importer of the shipment. Use only if importer is different from the recipient

name: string Contact name for the importer
company: string Company name for the importer.
street: string Street details (name, number, additional details) for the importer. If you need multiline addresses, please use line-breaks (cf. code example).
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
phone: string e.g. +33123456789 Phone number of the importer, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the importer. Make sure you check the validity of the email address.
vat_number: string e.g. FR12345678901 Importer Vat Number (EU/GB). The VAT identifier of the company for electronic customs declaration.
eori_number: string e.g. GB123456123456 Importer EORI Number (EU/GB). The EORI identifier of the company for electronic customs declaration.
ein: string e.g. 12-3456789 Importer EIN number for the United States (US). The EIN identifier of the company for electronic customs declaration.
business_number: string e.g. 123456789 Importer BN number for Canada (CA). The Business Number of the company for electronic customs declaration.
ide: string e.g. CHE-123.456.789 Importer IDE number for Swiss (CH). The IDE identifier of the company for electronic customs declaration.
business_identification_number: string e.g. 123456789 Local Company identifier of the importer company - if nothing above applies.
tax_identification_number: string e.g. 123456789 Local Fiscal identifier of the importer company - if nothing above applies

Example request with JSON

curl https://test.myflyingbox.com/v2/orders -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "order": {
        "offer_id": "b26115b4-1852-4937-be54-a65c510744bb",
        "shipper": {
          "name": "Lce Test collection",
          "company": "MY FLYING BOX SAS",
          "street": "15 route de France",
          "state": "Alpes-Maritimes",
          "phone": "+33622123613",
          "email": "test@test.com"
        },
        "recipient": {
          "name": "Lce Test delivery",
          "company": "MY FLYING BOX SAS",
          "street": "15 route de France",
          "state": "Alpes-Maritimes",
          "phone": "+33622123613",
          "email": "test@test.com"
        },
        "parcels": [
          {
            "value": "15",
            "currency": "EUR",
            "description": "Books",
            "shipper_reference": "4684-0770",
            "recipient_reference": "AB-3072"
          }
        ]
      }
    }'

Example with electronic customs declaration ( FR -> US )

curl https://test.myflyingbox.com/v2/orders -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "order": {
        "declare_customs_electronically": true,
        "offer_id": "625d4079-f0dd-470f-bc37-31582ad14fd8",
        "shipper": {
          "company": "test",
          "name": "test",
          "street": "test",
          "phone": "0123456789",
          "email": "email@test.com",
          "eori_number": "FR35819137589",
          "vat_number": "FR35819137589",
          "collection_date": "2024-09-05"
        },
        "recipient": {
          "name": "test",
          "street": "test",
          "state": "NY",
          "phone": "0123456789",
          "email": "email@test.com",
          "ein": "EIN123456"
        },
        "parcels": [
          {
            "description": "test",
            "country_of_origin": "FR",
            "value": "150.0",
            "currency": "EUR"
          }
        ],
        "customs_details": {
          "invoice_number": "INV312312",
          "reason_for_export": "commercial",
          "ship_price": 49.78,
          "ship_currency": "EUR"
        },
        "customs_items": [
          {
            "description": "description article",
            "customs_code": "4201003000",
            "quantity": 1,
            "currency_code": "EUR",
            "mass_unit": "kg",
            "country_of_origin": "FR",
            "unit_value": 150.0,
            "unit_weight": 3.0,
            "value_currency": "EUR"
          }
        ]
      }
    }'

Get an existing order

Request URL

GET: https://api.myflyingbox.com/v2/orders/:id

Order attributes

id

uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for this order.

created_at

timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of creation.

vat_scheme_code

shipper

hash (hide/show attributes) All relevant information regarding the collection of the parcels.

name: string Name of the person responsible at the collection point
company: string Optional company name for collection point
street: string (multiline) Lines of address, as a string with linebreaks (\n).
city: string City name
postal_code: string e.g. SW1A 0AA, NY 10001, 79450
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
country: string e.g. FR, UK, NZ Country code of collection address, on two letters (norm ISO 3166-1 alpha-2)
phone: string e.g. +33123456789 Phone number of contact at collection address, with international prefix.

recipient

hash (hide/show attributes) All relevant information regarding the delivery of the parcels.

name: string Name of the person responsible at the delivery point
is_a_company: boolean Tells whether the delivery location is a company location (true) or a residential location (false).
company: string Company name for delivery address. Always set if 'is_a_company' is true.
street: string (multiline) Lines of address, as a string with linebreaks (\n).
city: string City name
postal_code: string e.g. SW1A 0AA, NY 10001, 79450
country: string e.g. FR, UK, NZ Country code of delivery address, on two letters (norm ISO 3166-1 alpha-2)
phone: string e.g. +33123456789 Phone number of contact at delivery address, with international prefix.

parcels

array (hide/show attributes) A collection of parcels, forming the pack-list of your shipment.

length: integer e.g. 153 Length of the parcel, in centimeters (cm).
width: integer e.g. 82 Width of the parcel, in centimeters (cm).
height: integer e.g. 55 Height of the parcel, in centimeters (cm).
weight: float e.g. 12.5 Weight of the parcel, in kilograms (kg) with '.' (dot) as decimal separator.
value: float e.g. 15.35 Value of the content of the parcel (currency is specified separately). Used for customs. Note: this value must be identical to the value specified on the customs invoice attached to the shipment.
currency: string e.g. EUR Currency of the value specified above.
description: string e.g. Parcel 3 Brief description of content of the parcel (will be used for customs).
shipper_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the shipper. In some cases, this reference will be included on the labels.
recipient_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the recipient. In some cases, this reference will be included on the labels.
customer_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the customer. In some cases, this reference will be included on the labels.

offer

hash The offer booked in this order.
Go to offer attributes for details on offer formatting and attributes.

Example representation of an order

{
  "uuid": "1471b700-1c14-4076-ade5-861798844129",
  "shipper": {
    "name": "Lce Test collection",
    "company": "MY FLYING BOX SAS",
    "street": ["15 route de France"],
    "city": "Cagnes-sur-Mer",
    "state": "Alpes-Maritimes",
    "postal_code": "AB1 6CC",
    "phone": "+33622123613",
    "country": "UK"
  },
  "recipient": {
    "name": "Lce Test delivery",
    "is_a_company": "true",
    "company": "MY FLYING BOX SAS",
    "street": ["15 route de France"],
    "city": "Cagnes-sur-Mer",
    "state": "Alpes-Maritimes",
    "postal_code": "06800",
    "phone": "+33622123613",
    "country": "FR"
  },
  "parcels": [
    {
      "weight": '3',
      "length": '40',
      "width": '30',
      "height": '10',
      "value": "15",
      "currency": "EUR",
      "description": "Books",
      "shipper_reference": "4684-0770",
      "recipient_reference": "AB-3072"
    },
    {
      "weight": '1.75',
      "length": '50',
      "width": '10',
      "height": '10',
      "value": "15",
      "currency": "EUR",
      "description": "Books",
      "shipper_reference": "4684-0773",
      "recipient_reference": "AB-3073"
    }
  ]
}

Download parcel labels

After creating an order, in most cases, labels will need to be printed by the shipper and affixed on the parcels.

Labels are available almost immediately after placing the order, by sending a request to the URL specified below. The labels are returned in the form of a unique PDF file. When the order includes several parcels, or when more than one label needs to be printed, all relevant documents are included in the one PDF returned.

Request URL

GET: https://api.myflyingbox.com/v2/orders/:id/labels Replace :id with the UUID of the order.

Request parameters and response

No parameters are expected in this request. Only the UUID of the order must be passed in the request URL.

A raw PDF file is returned in response to the request if the labels are available.

If for some reasons the labels are not yet available, you will receive a 404 status code and a generic error response, with error code labels_not_ready.

Tracking parcels

After an order is placed, you have immediate access to tracking information for all parcels.

Request URL

GET: https://api.myflyingbox.com/v2/orders/:id/tracking Replace :id with the UUID of the order.

Request parameters and response

No parameters are expected in this request. Only the UUID of the order must be passed in the request URL.

The response returns all event information for each parcel of this order, sorted in the same order as they were submitted when requesting the initial quote.

Please note that tracking information may vary from carrier to carrier. We forward it through our API in an homogenous way but with a lot of flexibility: many attributes are optional and when we get some non-standard information we try to forward it nevertheless. Make sure that your implementation fits this flexibility.

Response attributes

The root level ('data' node) contains an array of tracking information for each parcel. The attributes below correspond to one entry of the array. Check the example on the right for a complete response example.

parcel_index

integer (starts at 0) Index of the parcel (starts at zero). The API is expected to return tracking info for all packages, but to be on the safe side please use the parcel_index attribute to associate the tracking data to the correct package on your side, so that your code will work even if some packages are missing in the response.

events

array Array of tracking events for this parcel.

code

string Code of the event.
You can rely on these codes for your implementation. However, please take into account that new codes may be added later.
If you want to implement the 'unknown' code, you can use the 'label' node for a direct display of the message (see below).
shipment_created : the order was confirmed
picked_up : parcel has been picked up at collection point
departed_from_facility : parcel has left the hub (cf. location)
arrived_at_facility : parcel arrived at the hub (cf. location)
at_departure_hub : parcel has arrived at the departure hub
in_transit : parcel is in transit between two hubs
at_arrival_hub : parcel is at the arrival hub
delivery_in_progress : parcel is being delivered
delivery_exception : delivery was attempted but failed
delivered : parcel has been delivered successfully
unknown : special code to handle non-standard carrier event codes corresponding to none of the above.

happened_at

timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of the event.

label

hash Returns a hash of translated strings containing a human-readable description of the event, corresponding to the event code. When the event code is 'unknown', the label will change depending on the message returned by the carrier.
The key of each hash element is the language code (ISO 639-1 alpha-2), and the value is the string.
English language is always present. We currently also return event labels in French language, except for the 'unknown' event, which is English-only. Other languages may be supported later.

location

hash Returns a hash of information regarding the location of the event.
Please note that none of the attributes are mandatory, which means that this node is not always returned.
The API will always try to return as many location details as possible through the available attributes.

name: string Descriptive name of the location (can be abstract, e.g. "Web service").
postal_code: string Postal code of the location.
city: string City of the location.
state: string State of the location.
country: varchar(2) e.g. FR, UK, NZ Country code of the location, on two letters (norm ISO 3166-1 alpha-2).

details

hash For some event codes, more detailed information is sometimes returned in this node.
If no extra information is available, this node will not be returned at all in the response.

code: string Code of the extra information. At the moment, only one code is supported:
not_available_or_closed : returned only along with the event code delivery_exception
label: hash Returns a hash of translated strings containing a human-readable description of the information.
The key of each hash element is the language code (ISO 639-1 alpha-2), and the value is the string.
English language is always present. We currently also return event labels in French language. Other languages may be supported later.

Example of tracking request

curl https://test.myflyingbox.com/v2/orders/eb27ff8e-b353-4a3f-8e7e-69576e64ee1a/tracking \
  -i -u {login}:{password}

Example response of a tracking request

{
  "status":"success",
  "self":"https://test.myflyingbox.com/v2/orders/eb27ff8e-b353-4a3f-8e7e-69576e64ee1a/tracking.json",
  "data":[
    {
      "parcel_index":0,
      "events":[
        {
          "code":"shipment_created",
          "happened_at":"2013-12-10T11:26:23+01:00",
          "label":{
            "fr":"Expédition créée",
            "en":"Shipment created"
          }
        },
        {
          "code":"picked_up",
          "happened_at":"2013-12-11T11:24:00+01:00",
          "label":{
            "fr":"Paquet enlevé",
            "en":"Package picked up"
          },
          "location":{
            "city":"NICE CEDEX 3",
            "postal_code":"06284",
            "country":"FR"
          }
        },
        {
          "code":"in_transit",
          "happened_at":"2013-12-12T03:43:00+01:00",
          "label":{
            "fr":"En transit",
            "en":"In transit"
          },
          "location":{
            "city":"ROISSY CHARLES DE GAULLE CEDEX",
            "postal_code":"95702",
            "country":"FR"
          }
        },
        {
          "code":"arrived_at_facility",
          "happened_at":"2013-12-12T05:11:00+01:00",
          "label":{
            "fr":"Arrivé à la plateforme",
            "en":"Arrived at hub"
          },
          "location":{
            "city":"STANSTED",
            "state":"ES",
            "postal_code":"CM24",
            "country":"GB"
          }
        },
        {
          "code":"delivery_in_progress",
          "happened_at":"2013-12-12T10:39:00+01:00",
          "label":{
            "fr":"Livraison en cours",
            "en":"Delivery in progress"
          },
          "location":{
            "city":"ENFIELD",
            "state":"MI",
            "postal_code":"EN3",
            "country":"GB"
          }
        },
        {
          "code":"delivery_exception",
          "happened_at":"2013-12-12T11:48:00+01:00",
          "label":{
            "fr":"Problème de livraison",
            "en":"Delivery exception"
          },
          "location":{
            "city":"ENFIELD",
            "state":"MI",
            "postal_code":"EN3",
            "country":"GB"
          },
          "details":{
            "code":"not_available_or_closed",
            "label":{
              "fr":"Client non disponible ou entreprise fermée",
              "en":"Customer not available or business closed"
            }
          }
        }
      ]
    }
  ]
}

Cancel an order

If needed, after placing an order, you can cancel it. The order must still have the state "created".

Request URL

PUT: https://api.myflyingbox.com/v2/orders/:id/cancel Replace :id with the UUID of the order.

Request parameters and response

No parameters are expected in this request. Only the UUID of the order must be passed in the request URL.

The response contains the order.

Example of cancel request

curl -X PUT https://test.myflyingbox.com/v2/orders/eb27ff8e-b353-4a3f-8e7e-69576e64ee1a/cancel \
  -i -u {login}:{password}

Schedule a pickup (Only avaialble for orders with delayed pickups).

Scheduling a pickup means that you are requesting the carrier to send a truck to collect your packages. This is only available for orders created with the 'delay_order flag'.

Request URL

POST: https://api.myflyingbox.com/v2/pickups

Request parameters

Parameters must be encapsulated within the root element 'pickup'.

order_id

uuid e.g. a3dd9019-df68-486b-9817-0a2cc6f3747c The ID of the order for which you are scheduling a pickup.

collection_date

string (date or datetime) e.g. 2013-10-01 Requested collection date (norm ISO-8601).

collection_instructions

string Instruction for the driver collecting the shipment.

address

hash (hide/show attributes) Details regarding the location of departure of the shipment. This is only needed if you want to override the shipper from the order.

name: string Name of a contact at the collection location.
company: string Optional company name for the collection location.
street: string Street details (name, number, additional details) for the pickup location. If you need multiline addresses, please use line-breaks (cf. code example).
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
postal_code: string Postal code of the location.
city: string City of the location.
country: string ISO 3166-1 alpha-2 code for the country of the shipper.
phone: string e.g. +33123456789 Phone number of the shipper, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.

Get an existing pickup

Request URL

GET: https://api.myflyingbox.com/v2/pickups/:id

Pickup attributes

id

uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for this pickup.

order_id

uuid e.g. 5ae67ca2-9c7e-477d-ad48-9ccfb468b809 Internal unique identifier for the order.

reference

string e.g. MFB-PU-200420-OQT The pickup reference created by MFB.

supplier_reference

string e.g. 123456789 The pickup reference provided by the carrier.

collection_date

string (date or datetime) e.g. 2013-10-01 Requested collection date (norm ISO-8601).

created_at

timestamp with timezone (ISO 8601) e.g. 2013-10-01T10:41:14+03:00 Date and time of creation.

total_price

price hash Total price, including VAT.
For detailed formatting and sub-attributes, please look at the 'price' attribute above.

address

hash (hide/show attributes) All relevant information regarding the collection of the parcels.

name: string Name of the person responsible at the collection point
company: string Optional company name for collection point
street: string (multiline) Lines of address, as a string with linebreaks (\n).
city: string City name
postal_code: string e.g. SW1A 0AA, NY 10001, 79450
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
country: string e.g. FR, UK, NZ Country code of collection address, on two letters (norm ISO 3166-1 alpha-2)
phone: string e.g. +33123456789 Phone number of contact at collection address, with international prefix.
email: string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.

Automaticaly order the best offer without requesting a quote.

This action combine and replace the quote creation and the order creation actions presented above. For this request, you will need to provide all the data and a way to sort and filter offers in one request. The first service matching your parameters will be selected and ordered.

Request URL

POST: https://api.myflyingbox.com/v2/orders/automatic

Request parameters

Parameters must be encapsulated within the root element 'order'.

thermal_labels

boolean e.g. true, false If true, the API will try to return the labels in a thermal printer-friendly format. This is not possible for all services.

insure_shipment

delay_pickup_order

parcel_type

string package or document The type of parcel you are shipping. If not present package will be used by default. Must the same value as parcels[0][type]. Document will only work with 1 parcel.

ecommerce_order_platform

string e.g. shopify The name of ecommerce platform that you are using. Only shopify is supported for now.

ecommerce_order_identifier

string The identifier of the shipment on the ecommerce platform.

ecommerce_order_reference

string The reference of the shipment on the ecommerce platform.

shipper

hash (hide/show attributes) Details regarding the location of departure of the shipment.

name: string Name of a contact at the collection location.
company: string Optional company name for the collection location.
street: string Street details (name, number, additional details) for the pickup location. If you need multiline addresses, please use line-breaks (cf. code example).
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
country: varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code: string Postal code of the collection location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city: string City name
phone: string e.g. +33123456789 Phone number of the shipper, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the shipper. Make sure you check the validity of the email address.
collection_date: string (date or datetime) e.g. 2013-10-01 or 2013-10-01T10:41:14+03:00 Requested collection date (norm ISO-8601).
Used only for offers where the product includes pickup at the shipper's address (see offer attributes above).
If the offer for which you place a booking contained a set of proposed collection dates, you must use the exact same string. Otherwise you must manually put a date/datetime. Remember that the exact pickup date and time depends on the time of the booking and the product. Most products have strict deadlines for same-day pickups.
collection_instructions: string Instruction for the driver collecting the shipment.

recipient

hash (hide/show attributes) Information regarding the destination of the shipment.

name: string Name of a contact at the delivery location.
is_a_company: boolean (true/false) Is the delivery location a company place?
company: string Company name for the delivery location.
Mandatory if the quote request has a recipient attribute 'is_a_company' at true, optional otherwise.
location_code: string Code of pickup location, when delivery occurs at a predetermined pickup point (opposed to home delivery). When a location code is specified, the attributes company, street, city and state are totally ignored by the web service (they will be overridden by the address of the pickup point).
street: string Street details (name, number, additional details) for the delivery location. If you need multiline addresses, please use line-breaks (cf. code example).
Will be ignored if location_code is set!
state: string State/County/Department (regional subdivision relevant to the mail delivery system of the country).
You must specify the official code, not the full name, for instance 'CA' for California, or '31' for Haute-Garonne (France).
Will be ignored if location_code is set!
country: varchar(2) Country of the collection location, alpha-2 iso codes (2 letters).
postal_code: string Postal code of the delivery location. For the rare cases where an address to do contain a postal code, please put an hyphen "-".
city: string City name
phone: string e.g. +33123456789 Phone number of the recipient, with international prefix. No extra characters or spaces allowed.
email: string e.g. example-address@example.com Email address of the recipient. Make sure you check the validity of the email address.

parcels

array (hide/show attributes)

type: string package or document The type of parcel you are shipping. If not present, package will be used by default. Must the same value as parcel_type in the quote. Only 1 parcel is allowed for documents.
length: integer e.g. 153 Length of the parcel, in centimeters (cm). Only integers are allowed.
width: integer e.g. 82 Width of the parcel, in centimeters (cm). Only integers are allowed.
height: integer e.g. 55 Height of the parcel, in centimeters (cm). Only integers are allowed.
weight: float e.g. 12.5 Weight of the parcel, in kilograms (kg). You can only use '.' (dot) as decimal separator. If there is anything else than numbers and a dot separator (e.g. 1,400.5) an error will be returned.
insured_value: float e.g. 30.25 Value of parcel to insure. If specified, offers will include (separately) the price of the 'ad valorem insurance' option. This value is not used to fill the parcel's customs value when ordering an offer, and works therefore in a totally independent manner.
insured_currency: string e.g. EUR Currency for the value specified in 'insured_value'. Mandatory if the field 'insured_value' is specified.
shipper_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the shipper. In some cases, this reference will be included on the labels.
recipient_reference: string e.g. Parcel 3, CS_03758 Optional reference used by the recipient. In some cases, this reference will be included on the labels.
customer_reference: string e.g. Parcel 3, CS_03758 Optional customer reference used by the recipient. In some cases, this reference will be included on the labels.

The following four attributes are mandatory only if your parcels need to proceed through customs (export or other regulatory obligations):

value: integer e.g. 15 Value of the content of the parcel, rounded to the nearest integer (currency is specified separately). Used for customs.
currency: string e.g. EUR Currency of the value specified above.
description: string e.g. Books, Clothes, Gift, etc. Description of the content of the parcel (used for customs).
country_of_origin: varchar(2) e.g. FR, UK, NZ Country code of the origin country of the parcel's content, on two letters (norm ISO 3166-1 alpha-2). Used for customs.

offers_sort_attributes

offers_filters

hash (hide/show attributes) Filter offers by carriers or product codes.

with_drop_off: boolean Includes offers for the product with the "drop off" flag set to to true. The available offers will support drop-off to carrier locations (for example in a partnered shop near the shipper).
with_pick_up: boolean Includes offers for the product with the "pick up" flag set to to true. The available offers will support pick up at the shipper location by the carrier.
with_preset_delivery_location: boolean Includes offers for the product with the "preset delivery location" flag set to to true. The available offers will support delivery at carrier locations (for example in a partnered shop near the recipient).
with_carrier_codes: array of strings Limit offers to this list of carrier codes
with_product_codes: array of strings Limit offers to this list of product codes
without_carrier_codes: array of strings Exclude offers matching this list of carrier codes
without_product_codes: array of strings Exclude offers matching this list of product codes

Example request with JSON

curl https://test.myflyingbox.com/v2/orders/automatic -i -X POST -u {login}:{password} \
-H "Content-Type:application/json" \
-d '{
      "order": {
          "shipper": {
              "company": "test",
              "name": "test",
              "street" :"test",
              "phone": "+33600000000",
              "email": "support@myflyingbox.com",
              "collection_date": "2022-10-20",
              "country": "FR",
              "postal_code": "31300",
              "city": "Toulouse"
          },
          "recipient": {
              "company": "test",
              "name": "test",
              "street": "test",
              "phone": "+33600000000",
              "email": "support@myflyingbox.com",
              "country": "FR",
              "postal_code": "06000",
              "city": "Nice",
              "is_a_company": "false"
          },
          "parcels": [
              {
                  "description": "description",
                  "length": "15",
                  "height": "15",
                  "width": "15",
                  "weight": "1"
              }
          ],
          "offers_sort_attributes": {
              "total_price": "asc"
          },
          "offers_filters": {
              "with_preset_delivery_location": false,
              "with_pick_up": true,
              "with_drop_off": false,
              "with_carrier_codes": ["dhl", "ups", "fedex"]
          }
      }
  }'

Changelog

Below are listed the latest changes made to the documentation, sorted by reverse chronological order (latest on top).

2022-11-02: Adds automatic order action, ecommerce plateform informations, offers filtering/sorting.
2022-09-30: Adds instruction for pickups.
2022-08-03: Adds support for documents.
2020-04-20: Adds delayed pickup creation.
2019-11-29: Adds available_drop_off_locations to offers to look up for drop-off locations.
2018-08-03: Removed obsolete branding and mentions to V1 product logos. Added carrier_code attribute to product, in offers.
2017-01-10: Update to version 2 of the API. Version 2 keeps the same set of features as version 1, but service coding has changed, breaking backward compatibility.
2015-12-04: Added documentation about ad valorem insurance. No compatibility issues.
2014-01-15: Added documentation about tracking.