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_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 |
| haulier_name | |
| carrier | Address reference for the carrier company |
| carrier_name | |
| foreign_agent | Address reference for the foreign agent |
| foreign_agent_name | |
| 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 |
| waybill_received | |
| waybill_released | |
| 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.