Getting Started

The CocoonFMS API allows you to directly interact with the data set that is used to power the CocoonFMS portal.

This documentation details how you use the API endpoints.

We assume that you/your developers have an understanding using JSON. To obtain a Key please do contact us on [email protected]

Authentication #back to top

The CocoonFMS API is stateless so you must pass your API key with each request.

Your API key must be passed in the request header as the Bearer value

        $response = $client->request('GET', '/api/shipments', [
            'headers' => [
                'Bearer' => $apiKey,
                'Accept' => 'application/json',

The API authentication layer provides the following HTTP status codes:

Status Message
200 Successful request
401 Invalid API Key
403 API access not enabled

Both the staus code and the message are provides as an array in the JSON response body.

List Shipments#back to top


Verb: GET

This will return an JSON array of objects with the following summary attributes for each shipment:

Attribute Description
_id FMS UUID for the shipment
created_at timestamp the shipment was created on the FMS
updated_at timestamp the shipment information was updated on the FMS
mode Transport mode
Transport mode Individual customer reference
ref_job Job display reference

Shipment Details #back to top


Verb: GET

This endpoint will return a single JSON object that represents the shipment with all available attributes attached.

The shipment_id attributes is available on the /api/shipments response.

A HTTP 404 is returned if the shipment id is not valid.

Available Attributes

The following table details the shipment attributes that are available:

Attribute Description
_id FMS UUID for the shipment
created_at timestamp the shipment was created on the FMS
updated_at timestamp the shipment information was updated on the FMS
job_date Client reference date for the job this shipment is attached to
job_status Client reference status for the job this shipment is attached to
job_route Client reference for the routing for the job that this shipment is attached to
job_office Client reference for the office that generated the job this shipment is attached to
jod_id Client reference for the job this shipment is attached to
job_sum_containers Summary of all job containers
job_sum_marks Summary of all job marks
ref_booking Booking reference
ref_display The consolidated and searchable reference attribute
ref_cust_1 Individual customer reference
ref_cust_2 Individual customer reference
ref_cust_3 Individual customer reference
ref_po PO display refernce
ref_job Job display reference
customer Address reference for the customer
consingor Reference for the consignor
consingor_name name of the shipper
consignee Address reference for the consignee
consignee_name Name of the consignee
supplier Address reference for the supplier
supplier_name Name of the supplier
notify_1 Reference for notifications
notify_2 Reference for notifications
notify_3 Reference for notifications
notify_4 Reference for notifications
haulier Reference for the haulage company
haulier_name Nam of the haulage company
carrier Address reference for the carrier company
carrier_name Name of the carrier
foreign_agent Address reference for the foreign agent
foreign_agent_name Name of the foreign agent
load_type Shipping load type (FCL)
route Shipment route (E=Export, I=Import, D=Domestic)
mode Transport mode (A=Air, S=Sea, R=Road, T=Rail)
pol Port code for port of loading / origin port
pol_label Port name for port of loading
pol_depart Searchable date/time of departure
pol_depart_p Planned date/time of departure
pol_depart_e Estimated date/time of departure
pol_depart_a Actual date/time or departure
pod Port code for port of discharge / final port
pod_label Port name for port of discharge
pod_arrive Searchable date/time of arrival
pod_arrive_p Planned date/time of arrival
pod_arrive_e Estimated date/time of arrival
pod_arrive_a Actual date/time of arrival
legs Embed collection of legs (see Legs table)
milestones Collection of milestone events
documents Collection of documents related to the job
addresses Embedded collection of addresses
customs_ori_loc Address reference for clearance at the port of origin
customs_ori_date Customs clearance date at port of origin
customs_ori_en Customs entry number at port of origin
customs_ori_ucr Customs declaration unique reference at port of orign
customs_dst_loc Address reference for clearance at the port of entry
customs_dst_date Customs clearance date at port of entry (destination)
customs_dst_en Customs entry number at port of entry (destination)
customs_dst_ucr Customs declaration unique reference at port of entry (destination)
cdocs_attached Documents necessary for customs clearance are attached
cdocs_complete Customs documentation completed
cdocs_complete_by Email address of the person that marked the cdocs as completed
cdocs_complete_at Timestamp that the cdocs where marked as completed
collection_date Date of the collection
collection_time Time of the collection
collection_r_date Date of the collection required by customer
collection_r_time Time of the collection required by customer
collection_a_date Actual date of collection
collection_ref Haulier's reference
collection_extra Extra details for the collection
collection_name collection addressee's name
collection_address_1 collection address line 1
collection_address_2 collection address line 2
collection_address_3 collection address line 3
collection_town collection address town
collection_county collection address county
collection_postcode collection address postcode
collection_country collection address country label
collection_country collection address UN country code
collection_location Address reference for the collection
delivery_date Date of the delivery
delivery_time Time of the delivery
delivery_r_date Date of the delivery required by customer
delivery_r_time Time of the delivery required by customer
delivery_a_date Actual date of delivery to the customer
delivery_ref Customer reference for the delivery
delivery_extra Extra details for the delivery provided by the customer
delivery_booking_at Timestamp when the delivery booking was arranged
delivery_booked_by Email address of the person that arranged the delivery
delivery_name Delivery addressee's name
delivery_address_1 Delivery address line 1
delivery_address_2 Delivery address line 2
delivery_address_3 Delivery address line 3
delivery_town Delivery address town
delivery_county Delivery address county
delivery_postcode Delivery address postcode
delivery_country Delivery address country label
delivery_country_code Delivery address UN country code
delivery_location Address reference for the delivery
urgent Boolean flag to mark shipment as urgent
urgent_note Note from customer
urgent_at Data the shipment was requested to be urgent
urgent_by The email address of the user that made the urgent request
cargo_desc Description of cargo being shipped
cargo_pieces Number of pieces that make up the shipment
cargo_wgt Weight of the cargo
cargo_wgt_unit Unit for the cargo weight
cargo_linear Linear dimensions of the cargo
cargo_linear_unit Unit for the cargo linear measurements
cargo_cbm Cubic volume of the cargo
cargo_vol_wgt Volumetic Weight of the cargo
cargo_packing The type of packaging eg: cartons
cargo_value Value of the cargo
cargo_value_unit Value currency code
cargo_available_at Cargo release from supplier
hazard_class UN Classification for dangerous substances.
hazard_un_number UN Number for specific material
hazard_mat Material Type (S=Solid, L=Liquid)
hazard_desc Notes in addition to the published document for the specified material
container_equipment Equipment type code
container_number Container number
container_seal Text value of the container seal number
container_utilization Cargo % utilization of container
container_utilization_target Target Cargo % utilization of container
approved Approval status
approved_by Email of the person that made the approval
approved_at Timestamp that the approval was made
approved_note Note for the approval / rejection notice
waybill_master Reference for the master waybill for the shipment
waybill_house Reference for the house waybill for the shipment
inco_terms INCO terms applied to the shipment
flight_ref Flight Number
vessel_name Vessel Name
distance Total distance used in emissions calculation in Km
co2 CO2 emissions estimate for the shipment in Kg
nox NOx emissions estimate for the shipment in g
pm Particulate matter emissions estimate for the shipment in g
co2_offset Equivalent CO2 actually offset in Kgs
trees_planted The number of trees actually planted to offset emissions
ecologi_id ID for the certificate provided by Ecologi for certifying planting of trees to offset emissions
ecologi_date Date of issue for the Egologi certificate

The shipment details endpoint only includes attributes in the shipment object that have had values explicitly on the FMS platform. Attributes that are not relevant, particularly to the transport mode, will be omitted from the model.