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_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 Address reference for the consignor
consignee Address reference for the consignee
supplier Address reference for the supplier
supplier_name Name of the supplier
supplier_releasd_at Date good are released by the supplier
notify_1 Address reference for notifications
notify_2 Address reference for notifications
notify_3 Address reference for notifications
notify_4 Address reference for notifications
hauler Address reference for the haulage company
carrier Address reference for the carrier company
foreign_agent Address reference for the foreign agent
load_type Shipping load type
route Shipment route
mode Transport mode
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_date Customs clearance date
customs_ref Customs entry number
customs_declaration Customs declaration unique reference
cdocs_attached Documents necessary for customs clearance are attached
customs_location Address reference for the
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_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_address_town collection address town
collection_address_county collection address county
collection_address_postcode collection address postcode
collection_address collection address country label
collection_address_country collection address UN country code
collection_location Address reference for the collection
collection_location Address reference for the collection pickup
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_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_address_town Delivery address town
delivery_address_county Delivery address county
delivery_address_postcode Delivery address postcode
delivery_address Delivery address country label
delivery_address_country 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_cube Cubic volume of the cargo
cargo_cube_unit Unit for the cubic volume
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_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
co2 Co2 Emissions estimate for the shipment

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.