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]
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.
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 |
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.
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 |
| waybill_received | |
| waybill_released | |
| 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.