get
https://pluto.cargobase.com/api/1/requests/
The Request Detail end-point can be used to retrieve all specifics of a request.
After a request has been awarded, the details can still be viewed, however: the Shipment Detail end-point should be approached for up to date data.
Request URI
GET https://pluto.cargobase.com/api/1/requests/`SHIPMENT_ID`
Authorization: Token your_token_here
Status codes
| Status | Description | Resolution |
|---|---|---|
| 200 | OK | -- |
| 403 | Forbidden | check Authentication token, or status of the request |
Request Response
Request Response categories
The response is divided into 7 possible categories for shippers and 6 for providers, these are:
| Category | Definition |
|---|---|
| organization | Details related to the organization, such as WBS Codes or Cost Centers |
| service | Details related to the service, such as requested freight modes, incoterms or clearance instructions |
| schedule | Details related to pickup & delivery timing and locations |
| good_items | Details related to the packing list |
| good_customs_information | Customs details per good item |
| special_requirements | Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most. |
| Quotes | Only visible for Shippers - Details regarding the quotes that have been received. |
Request Response: Organization
Details related to the organization, such as WBS Codes or Cost Centers.
| Key | Value | Description |
|---|---|---|
| shipment_id | STRING | The request ID |
| requestor | STRUBG | The name of the person that created this request |
| shipper | STRUBG | The name of the Company that initiated this request |
| request_creation_datetime | TIMESTAMP | Format YYYY-MM-DD HH:MM:SS |
| request_status | STRING | Current status of request, see list for potential status below |
| title | STRING | Title of the Request, as provided by the Shipper |
| cost_center | STRING | Value entered in the cost_center field, the shipper might use a custom label for this field and therefore not recognise the term cost_center |
| custom_field1 | STRING | Value entered in the custom_field1 field, the shipper might use a custom label for this field and therefore not recognise the term custom_field |
| reason_code | STRING | Value entered in the reason_code field, the shipper might use a custom label for this field and therefore not recognise the term reason_code |
| goods_confirmation_type | STRING | Details related to the status of the packing list, only available to some. Status can be Estimated or Finalised |
| good_items | GROUP | Packing list with details |
| special_requirements | GROUP | Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most. |
| additional_comments | STRING | Additional comments added by the shipper to the request |
| dates&timers | SKIPPED | A set of days, hours, minutes and dates related to quoting or confirmation timers. See known issues. |
| quotes | GROUP | Only visible for Shippers - Details regarding the quotes that have been received. |
Request status options
| Status | Definition |
|---|---|
| New | An active request that has not yet received quotes |
| Quoted | An active request that has received 1 or multiple quotes |
| Canceled | A request that was canceled manually or automatically |
| In Progress | Only for Providers - displayed when quoting is ongoing, but the quote has not been submitted |
Request Response: Service
Details related to the service, such as requested freight modes, incoterms or clearance instructions.
| Key | Value | Description |
|---|---|---|
| incoterm | STRING | The requested incoterm |
| delivery_service_level | INTEGER | Number of days associated with Service level, not available for most |
| export_clearance | STRING | Indicator if Export clearance is requested, and what kind |
| export_clearance_instructions | STRING | Instructions related to Export clearance |
| transit_clearance | STRING | Indicator if Transit clearance is requested, and what kind |
| transit_clearance_instructions | STRING | Instructions related to Transit clearance |
| import_clearance | STRING | Indicator if Import clearance is requested, and what kind |
| import_clearance_instructions | STRING | Instructions related to Import clearance |
| insurance | BOOLEAN | Indicator to see if the provider is requested to arrange shipment insurance |
| insurance_instructions | STRING | Instructions related to a positive insurance request |
| service_requirement | STRING | Related to Door-to-Door, Door-to-Port, Port-to-Door or Port-to-Port but abbreviated in a TLA |
| air_charter_invited | BOOLEAN | Boolean to see if this freight mode is invited |
| next_flight_invited | BOOLEAN | Boolean to see if this freight mode is invited |
| ocean_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |
| rail_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |
| regular_air_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |
| road_freight_invited | BOOLEAN | Boolean to see if this freight mode is invited |
| road_freight_type | STRING | Additional detail about road freight if road_freight_invited=TRUE |
| provider_reference | STRING | A list of invited provider teams - Visible for Providers only |
| available_teams | OBJECT | An object with 1 or multiple available teams that the request can be assigned to - Visible for Providers only |
Request Response: Schedule
Details related to pickup & delivery timing and locations.
| Key | Value | Description |
|---|---|---|
| pickup_airport_code | STRING | IATA Airport code, if identified otherwise null |
| pickup_airport | STRING | Airport Name, if identified otherwise null |
| pickup_seaport_code | STRING | Seaport code, if identified otherwise null |
| pickup_seaport | TYPE | Seaport name, if identified otherwise null |
| pickup_street | STRING | Pickup street address |
| pickup_address_name | STRING | Pickup company name |
| pickup_state | STRING | The pickup State in case of US or Mexico |
| pickup_zipcode | STRING | The pickup postal code |
| pickup_city | STRING | The pickup city |
| pickup_country | STRING | The pickup country |
| pickup_date | TIMESTAMP | Requested pickup date, format YYYY-MM-DD |
| pickup_time | TIMESTAMP | Requested pickup time, format HH:MM |
| pickup_time_type | INTEGER | Requested pickup type can be 1=Regularor 2=Between |
| pickup_end_date | TIMESTAMP | Requested pickup end date, in case of pickup_time_type 2 |
| pickup_end_time | TIMESTAMP | Requested pickup end time, in case of pickup_time_type 2 |
| pickup_hours_start | TIMESTAMP | If Shipper indicated pickup location opening hours format: HH:MM |
| pickup_hours_end | TYPE | If Shipper indicated pickup location closing hours format: HH:MM |
| pickup_timezone | STRING | Timezone name |
| pickup_notes | STRING | Additional pickup notes |
| pickup_contact_name | STRING | Name of contact person at pickup location |
| pickup_contact_phone | STRING | Phone number of contact person at pickup location |
| pickup_contact_email | STRING | Email of contact person at pickup location |
| pickup_address_type | STRING | Can be Address, Seaport or Airport |
| stop1_airport | STRING | Airport Name, if identified otherwise null |
| stop1_seaport_code | STRING | Seaport code, if identified otherwise null |
| stop1_seaport | TYPE | Seaport name, if identified otherwise null |
| stop1_street | STRING | Delivery street address |
| stop1_address_name | STRING | Delivery company name |
| stop1_state | STRING | The delivery State in case of US or Mexico |
| stop1_zipcode | STRING | The delivery postal code |
| stop1_city | STRING | The delivery city |
| stop1_country | STRING | The delivery country |
| stop1_date | TIMESTAMP | Requested delivery date, format YYYY-MM-DD |
| stop1_time | TIMESTAMP | Requested delivery time, format HH:MM |
| stop1_time_type | INTEGER | Requested delivery type can be 1=Regularor 2=Between |
| stop1_end_date | TIMESTAMP | Requested delivery end date, in case of stop1_time_type 2 |
| stop1_end_time | TIMESTAMP | Requested delivery end time, in case of stop1_time_type 2 |
| stop1_hours_start | TIMESTAMP | If Shipper indicated delivery location opening hours format: HH:MM |
| stop1_hours_end | TYPE | If Shipper indicated delivery location closing hours format: HH:MM |
| stop1_timezone | STRING | Timezone name |
| stop1_notes | STRING | Additional delivery notes |
| stop1_contact_name | STRING | Name of contact person at delivery location |
| stop1_contact_phone | STRING | Phone number of contact person at delivery location |
| stop1_contact_email | STRING | Email of contact person at delivery location |
| stop1_address_type | STRING | Can be Address, Seaport or Airport |
Request Response: Good items
Details related to the packing list. This category is a child of Organization.
These values are grouped per handling unit, each shipment can have multiple handling units.
Each shipment can also have multiple handling units of the same type, but differences in dimensions, notes or classifications.
| Key | Value | Description |
|---|---|---|
| units | INTEGER | Number of this type of handling unit |
| handling_unit | STRING | Handling unit type |
| length | DOUBLE | Length value |
| height | DOUBLE | Height value |
| width | DOUBLE | Width value |
| m_unit | STRING | LxWxH unit of measurement, can be cm or inch |
| weight | INTEGER | Weight of individual handling unit piece, should be multiple by number of units for total Weight |
| w_unit | STRING | Weight unit of measurement, can be kg or lbs |
| stackable | BOOLEAN | Indicator if individual piece can be stacked |
| hazardous | BOOLEAN | Indicator if goods are considered hazardous |
| crating_required | BOOLEAN | Indicator if the provider is requested to provide crating, will be null for most |
| crating_required_by_date | TIMESTAMP | Date & Time of final possibility to provide crating services, will be null for most |
| is_dangerous_good | BOOLEAN | Indicator if contents are classified as a Dangerous good |
| dangerous_good_value | INTEGER | Indicator of DG Category |
| other_instructions | STRING | Description in case of handling unit other |
| additional_information | STRING | Additional instructions related to these goods |
| container_type | STRING | Description of container type, in case of handling unit container (e.g. 20Ft standard) |
| refrigerated_container | BOOLEAN | Indicator if container should be refridgerated, in case of handling unit container |
| good_customs_information | GROUP | Customs details related to this handling unit |
Request Response: Good customs information
Customs details per good item. This category is a child of a handling unit within category Good items.
| Key | Value | Description |
|---|---|---|
| value | INTEGER | Value of the contents of the handling unit |
| currency_code | STRING | Currency of the value of the handling unit |
| Description | STRING | Description of the contents of the handling unit |
| hs_code | STRING | Harmonised Systems code for this handling unit, as provided by the shipper |
Request Response: Special requirements
Specific requirements of the shipment such as 'air ride trucks' or 'shock tilt' requirements, not available for most.
| Key | Value | Description |
|---|---|---|
| air_truck_required | BOOLEAN | To indicate if shipment will require this feature |
| air_truck_additional_information | STRING | Additional information in case this feature is requested |
| shock_tilt_required | BOOLEAN | To indicate if shipment will require this feature |
| shock_tilt_additional_information | STRING | Additional information in case this feature is requested |
| unique_handling_required | BOOLEAN | To indicate if shipment will require this feature |
| unique_handling_additional_information | STRING | Additional information in case this feature is requested |
| chemical_magnetic_concerns | BOOLEAN | To indicate if shipment will require this feature |
| chemical_magnetic_additional_information | STRING | Additional information in case this feature is requested |
| unique_warehousing_required | BOOLEAN | To indicate if shipment will require this feature |
| unique_warehousing_additional_information | STRING | Additional information in case this feature is requested |
| special_transport_required | BOOLEAN | To indicate if shipment will require this feature |
| special_transport_additional_information | STRING | Additional information in case this feature is requested |
| special_provider_requirements | BOOLEAN | To indicate if shipment will require this feature |
| special_provider_additional_information | STRING | Additional information in case this feature is requested |
| special_lift_fixtures_required | BOOLEAN | To indicate if shipment will require this feature |
| special_lift_fixtures_additional_information | STRING | Additional information in case this feature is requested |
Request Response: Quotes
** Only visible for Shippers** - Details regarding the quotes that have been received.
In case, 1 or multiple quotes has been submitted for this request details will be included in the 'quotes' object, with each quote as an individual object in an array.
Each quote contains 4 categories of information.
| Key | Description |
|---|---|
| basic_information | Information like, provider name, quote reference and total quoted amount |
| schedule | Information related to transit times. |
| cost_details | Individual charge codes and the total quoted amount |
| additional_details | Instructions or additional comments, can also include vessel_information |
Vessel information
***Please Note, vessel_information is part of Quotes in Requests, after booking the vessel_information object is part of the Schedule object in the Shipment details API ***
Vessel information is ocean freight specific, and can contain details provided by the provider about vessel departure, arrival and the vessel number (IMO).
These details are only present in case they are populated. These details will not be sent as null if missing.
In similar fashion to other quotes details, the content of vessel_information is an array of key value pairs.
The potential pairs are:
- Vessel departure : a date in YYYY-MM-DD
- Arrival in port : a date in YYYY-MM-DD
- Vessel / IMO : A string containing the IMO number
Request Response: Available teams
** Only visible for Providers**
An object with 1 or multiple available teams that the request can be assigned to - Visible for Providers only.
Available teams also includes a key to indicate if a team is already assigned - assigned_team
Only 1 provider team can be assigned, assignment can only be undone via the webplatform.
Details on how to assign a team are described in the Assign team end-point.
Each available team is listed as an object in the available_teams section.
The name of each object is the provider_reference needed to assign the team, for instance 'PT12345678'
Each object contains the following details:
| Key | Value | Description |
|---|---|---|
| team_name | STRING | Name of the provider team, assigned by Cargobase |
| supported_freight_modes | ARRAY | Requested freight modes, supported by this team |
| rate_card_available | BOOLEAN | Indicator if a rate-on-file is available to automatically add a quote to the request |