The EDS Appointments API follows a basic Request/Response message flow between two systems. EDS clients send an initial "Request" message (called a Service Order or SO) via the API containing information about their appointment requests. Thereafter, EDS "Responds" with all available appointment updates for those requests via the API (i.e., pending, confirmed, etc.).
EDS clients are responsible for “pushing” their Service Orders and “pulling” the Appointment Update Messages from the Azure Endpoints or Service Bus Endpoint. EDS does not support pushing the data directly to customers.
eModal™ Data Services (EDS), offers clients the ability to request and create Appointments/Reservations against their equipment through their Service Orders. Clients can also update or cancel their appointments via their Service Orders. Clients will be provided with API endpoints and Authorization Keys to send Inbound Service Order Requests and receive Outbound Appointment/Reservation Updates from the Microsoft Service Bus via the Azure Subscription endpoints.
A Service Order is a collection of orders to be processed by EDS
There are two methods to submit a Service Order:
POST https://[[namespace]].emodal.com/eds/ServiceOrder/ServiceOrders
Key | Value | Version |
---|---|---|
Content-Type | application/json | PROD |
X-API-Key | [[apiKey]] | PROD |
A Service Order ID if the Service Order could be partially or completely created. Error message if it fails to be processed.
curl "https://[[namespace]].emodal.com/eds/ServiceOrder/ServiceOrders" \
-X POST \
-H "X-API-Key: [[apiKey]]" \
-H "Content-Type: application/json" \
-d 'Service Order object'
{}
For additional information on how to interact with the Azure Service Bus please refer to the Service Bus Runtime REST documentation
POST https://[[namespaceName]].servicebus.windows.net/[[topic]]/messages
Key | Value | Version |
---|---|---|
Authorization | SharedAccessSignature [[value]]' | PROD |
apiKey | [[apiKey]] | PROD |
BrokerProperties | {"SessionId":"1"} | PROD |
MessageType | serviceorder | PROD |
curl "https://[[namespaceName]].servicebus.windows.net/[[topic]]/messages" \
-X POST \
-H 'Authorization: SharedAccessSignature [[value]]'' \
-H 'apiKey: [[apiKey]]' \
-H 'BrokerProperties: {"SessionId":"1"}' \
-H 'MessageType: serviceorder' \
-d 'Service Order object'
The Service Order object is passed as a JSON object in the body of the HTTP request
Name | Description | Version |
---|---|---|
order. trade_type |
string Mandatory Trade Type. I = Import, X = Export, U = Unknown, | PROD |
order. order_type |
string Conditional Order Type (BKG – For Export, BL – For Import, ERP – For Empties, GCD – Group Code) *Must be defined for order-based service order where unit_nbr is not provided |
PROD |
order. order_nbr |
string Conditional Order Number (Mandatory for Export container and Optional for Imports/Empties and Bare.) *Must be defined for order-based service order where unit_nbr is not provided |
PROD |
order. unit |
object Conditional Unit information |
PROD |
order.unit. unit_nbr |
string Conditional Unit Number (Container# for Import/Export/Empties, Chassis# for Bare Claim). Mandatory for import pickups. |
PROD |
order.unit. unit_category |
string Mandatory Unit Category (CN - Container, CH - Chassis, GN - Genset, TL - Trailer) **Genset, Chassis and Trailer Support will be added in future |
PROD |
order.unit. line_scac |
string Optional Shipping Line SCAC |
PROD |
order.unit. sztypeiso_cd |
string Optional Unit size and ISO type code |
PROD |
order.unit. seal_nbrs |
string Optional Seal Number Array up to 8 entries |
PROD |
order.unit.accessories. unit_nbr |
string Issued by eModal | PROD |
order.unit.accessories. unit_category |
string Issued by eModal | PROD |
order.unit.accessories. sztype_cd |
string Issued by eModal | PROD |
order.locations. loc_type |
string Mandatory. O – Origin, there can be only one Origin location per unit. D – Destination, there can be only one Destination location per unit. If destination is missing, Valet Last Mile and Empty Return services won’t be requested as it would require destination. M – Mid Points, there can be only many mid-point location per unit. | PROD |
order.locations. loc_port |
string Mandatory. Port Code | PROD |
order.locations. location_cd |
string Mandatory. Facility or terminal code. Refer to Location Code section for list of eModal terminals. | PROD |
order.locations. arrcarrier_type |
string Optional. Arriving Carrier Type (V-Vessel, T-Truck and R-Rail) | PROD |
order.locations. arrcarrier_cd |
string Optional. Arriving carrier code (Vessel = ‘Vessel Code – Voyage Number – Sequence Number’, Truck = ‘Truck Plate Number’ or ‘Truck Number’, Rail = ‘Rail Number – Rail Car Number’) | PROD |
order.locations. eta |
string (date time) Optional. Estimated time of arrival | PROD |
order.locations. depcarrier_type |
string Optional. Departing Carrier Type (V - Vessel, T - Truck, R - Rail) | PROD |
order.locations. depcarrier_cd |
string Optional. Departing carrier code (Vessel = ‘Vessel Code – Voyage Number – Sequence Number’, Truck = ‘Truck Plate Number’ or ‘Truck Number’, Rail = ‘Rail Number – Rail Car Number’) | PROD |
order.locations. etd |
string (date/time) Optional. Estimated time of departure | PROD |
order.locations. reservation_req |
object Mandatory. Details about reservation request | PROD |
order.locations.reservation_req. reservation_id |
sting Mandatory. Unique identifier generated by eModal Reservation System to be used for updating or canceling existing reservation. NULL for appointment request creation. | PROD |
order.locations.reservation_req. action_cd |
string Mandatory. A = ADD, U = UPDATE, C = CANCEL | PROD |
order.locations.reservation_req. move_type |
string Mandatory. P = PICK, D = DROP | PROD |
order.locations.reservation_req. unit_full_empty |
string Mandatory. Values: FULL / EMPTY | PROD |
order.locations.reservation_req. pin_nbr |
string Optional | PROD |
order.locations.reservation_req. hazmat_info |
object Optional | PROD |
order.locations.reservation_req.hazmat_info. haz_class |
object Optional - Hazardous Class. | PROD |
order.locations.reservation_req.hazmat_info. haz_uncode |
string Optional - Hazardous UN Code | PROD |
order.locations.reservation_req.hazmat_info. commodity_weight |
string Optional - Hazardous commodity weight - This value to be receive in Lbs | PROD |
order.locations.reservation_req.hazmat_info. quantity |
string Optional - Hazardous quantity | PROD |
order.locations.reservation_req.hazmat_info. package_group |
string Optional - Hazardous package group | PROD |
order.locations.reservation_req.hazmat_info. commodity_name |
string Optional - Hazardous commodity Name | PROD |
order.locations.reservation_req.hazmat_info. emergency_ph |
string Optional - Emergency Phone number for Hazardous | PROD |
order.locations.reservation_req.hazmat_info. limited_qty |
string Optional - Indicates Limited Quantity which designates placard is not needed. Values 'Y'/ 'N' or null | PROD |
order.locations.reservation_req.hazmat_info. comments |
string Optional - comments on Hazardous item | PROD |
order.locations.reservation_req. reservation_preferences |
object Mandatory only for appointment requests. | PROD |
order.locations.reservation_req.reservation_preferences. try_later_dates |
string Conditional. Y = YES (default), N = NO. Try dates later than the indicated dates if one or more date time ranges are provided. | PROD |
order.locations.reservation_req.reservation_preferences. preferences_datetime |
list Conditional. List of time or date time ranges for the appointment. EDS will try to make the appointment during the ranges provided in order of preference. Date Time ranges=[['YYY-MM-DDTHH:MM', 'YYYY-MM-DDTHH:MM'], ] Time ranges=[[HH:MM, HH:MM], ]. Use NULL as start or end to indicate appointments after or before a given time or date time. Examples here. | PROD |
order.locations.reservation_req. bundle_info |
object Optional | PROD |
order.locations.reservation_req.bundle_info. bundled_flag |
string Optional. Y or N | PROD |
order.locations.reservation_req.bundle_info. unit_category |
string Optional. (GN = GENSET, CH = Chassis, RD = Rail-deck) | PROD |
order.locations.reservation_req.bundle_info. unit_nbr |
string Optional. Unit Number | PROD |
order.locations.reservation_req. chassis_req |
object Optional. Chassis information | PROD |
order.locations.reservation_req.chassis_req. chassis_nbr |
string Optional. Chassis number | PROD |
order.locations.reservation_req.chassis_req. owner |
string Optional. OWN = Own Chassis, POOL = Pool Chassis | PROD |
order.locations.reservation_req.chassis_req. iep_scac |
string Optional. IEP SCAC | PROD |
order.locations.reservation_req.chassis_req. sztype_cd |
string Optional. Chassis Size Type Code | PROD |
order.locations.reservation_req.chassis_req. chs_weight |
string Optional. Chassis Weight | PROD |
order.locations.reservation_req.chassis_req. weight_uom |
string Optional. Chassis Weight Unit. LB = Pounds, KG = Kilogram, MT = Metric Ton | PROD |
order.locations.reservation_req. trucker_info |
object Mandatory, trucker information | PROD |
order.locations.reservation_req.trucker_info. trucker_scac |
string Mandatory. Trucker SCAC Code | PROD |
order.locations.reservation_req.trucker_info. trucker_nbr |
string Optional. Trucking Number assigned by the Trucking Company | PROD |
order.locations.reservation_req.trucker_info. lic_plate_nbr |
string Optional. License Plate Number. Required by some terminals prior to arriving at the facility. In that case, appointment can be requested without this information and can be updated later including this value | PROD |
order.locations.reservation_req.trucker_info. lic_plate_state_cd |
string Optional. License Plate State Code. Required by some terminals prior to arriving at the facility. In that case, appointment can be requested without this information and can be updated later including this value | PROD |
order.locations.reservation_req.trucker_info. driver_id |
string Optional. Driver’s License number or ID. Required by some terminals prior to arriving at the facility. In that case, appointment can be requested without this information and can be updated later including this value | PROD |
order.locations.reservation_req.trucker_info. driver_fname |
string Optional. Driver’s First Name. Required by some terminals prior to arriving at the facility. In that case, appointment can be requested without this information and can be updated later including this value | PROD |
order.locations.reservation_req.trucker_info. driver_lname |
string Optional. Driver’s Last Name. Required by some terminals prior to arriving at the facility. In that case, appointment can be requested without this information and can be updated later including this value | PROD |
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU",
"sztypeiso_cd": null,
"seal_nbrs": [],
"accessories": [
{
unit_nbr: null,
unit_category: null,
sztype_cd: null
}
]
},
"locations": [
{
"loc_type": "O",
"loc_port": "OAK",
"location_cd": "B58",
"arrcarrier_type": "",
"arrcarrier_cd": null,
"eta": null,
"depcarrier_type": "",
"depcarrier_cd": null,
"etd": null,
"reservation_req": {
"reservation_id": null,
"action_cd": "A",
"move_type": "P",
"unit_full_empty": FULL,
"pin_nbr": null,
"hazmat_info": [
{
"haz_class": null,
"haz_uncode": null,
"commodity_weight": null,
"quantity": null,
"package_group": null,
"commodity_name": null,
"emergency_ph": null,
"limited_qty": null,
"comments": null
}
],
"reservation_preferences": {
"try_later_dates": "N",
"preference_datetimes": [
["2021-01-01T07:00:00"]
]
},
"bundle_info": [
{
"bundled_flag": null,
"unit_category": null,
"unit_nbr": null
}
],
"chassis_req": [
{
"chassis_nbr": null,
"owner": null,
"iep_scac": null,
"sztype_cd": null,
"chs_weight": null,
"weight_uom": null
}
],
"trucker_info": {
"trucker_scac": null,
"truck_nbr": null,
"lic_plate_nbr": null,
"lic_plate_state_cd": null,
"driver_id": null,
"driver_fname": null,
"driver_lname": null
}
},
}
],
}
]
}
Submit an appointment requests for any day and any time after the current date and time, when the first slot is available.
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req": {
"action_cd": "A",
"move_type": "P",
"unit_full_empty": FULL,
},
}
],
}
]
}
Sample of a Pick Import Appointment request after a specified date:
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req": {
"action_cd": "A",
"move_type": "P",
"unit_full_empty": FULL,
"reservation_preferences": {
"preference_datetimes": [
["2021-01-01T07:00:00", null]
]
}
},
}
],
}
]
}
Sample of a Pick Import Appointment request between dates
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req": {
"action_cd": "A",
"move_type": "P",
"unit_full_empty": FULL,
"reservation_preferences": {
"preference_datetimes": [
["2021-01-01T07:00:00", "2021-01-07T17:00:00"]
]
}
},
}
],
}
]
}
Pick Import Appointment request on specific date only
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req": {
"action_cd": "A",
"move_type": "P",
"unit_full_empty": FULL,
"reservation_preferences": {
"try_later_dates": "N",
"preference_datetimes": [
["2021-01-01T07:00:00"]
]
}
},
}
],
}
]
}
Pick Import Appointment request on specific time range
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req": {
"action_cd": "A",
"move_type": "P",
"unit_full_empty": FULL,
"reservation_preferences": {
"preference_datetimes": [
["06:00:00", "14:00:00"],
["16:30:00", "18:00:00"]
]
}
},
}
],
}
]
}
Request to update the appointment with truck and driver information:
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req": {
"reservation_id": "id returned by the original request",
"action_cd": "U",
"move_type": "P",
"unit_full_empty": FULL,
"trucker_info": {
"truck_nbr": "updated truck number",
"lic_plate_nbr": "updated license plate number",
"lic_plate_state_cd": "updated license place state code",
"driver_fname": "driver’s first name",
"driver_lname": "driver’s last name"
}
},
}
],
}
]
}
Request cancelation
{
"order": [
{
"trade_type": "I",
"order_type": "",
"order_nbr": "",
"unit": {
"unit_nbr": "CSQU305438",
"unit_category": "CN",
"line_scac": "CSQU"
},
"locations": [
{
"loc_port": "LALB",
"location_cd": "ITS",
"reservation_req":{
"reservation_id":"id returned by the original request"
"action_cd":"C",
}
}
],
}
]
}
Appointment updates can be received through the Service Bus only. For additional information on how to interact with the Azure Service Bus please refer to the Service Bus Runtime REST documentation.
DELETE https://[[namespaceName]].servicebus.windows.net/[[topic]]/subscriptions/appointmentupdates/messages/head
Key | Value |
---|---|
Authorization | SharedAccessSignature [[value]] |
None
curl "https://[[namespaceName]].servicebus.windows.net/[[topic]]/subscriptions/appointmentupdates/messages/head" \
-X DELETE \
-H 'Authorization: SharedAccessSignature [[value]]'
{
"msgheader": {
"source_cd": "eModal",
"sender_cd": "EDS",
"receiver_cd": "[[]]",
"company_cd": "[[]]",
"msg_type": "APPTUPD"
},
"msgdata": [
{
"reservation_id": "b0e781a5-c0e3-42eb-9d6c-f030396f8ee5",
"reservation_status": "PENDING",
"units": [
{
"unit_nbr": "TRLU6850740"
}
],
"reservation_msgs": [
{
"msg_cd": null,
"msg_desc": "Reservation Saved: TRLU6850740",
"msg_sev": "0",
"msg_dttm": null
}
]
}
]
}
curl "https://[[namespaceName]].servicebus.windows.net/[[topic]]/subscriptions/appointmentupdates/messages/head" \
-X DELETE \
-H 'Authorization: SharedAccessSignature [[value]]'
{
"msgheader": {
"source_cd": "eModal",
"sender_cd": "EDS",
"receiver_cd": "[[]]",
"company_cd": "[[]]",
"msg_type": "APPTUPD"
},
"msgdata": [
{
"event_nm": "Appointment update",
"facility_cd": "ITS",
"reservation_id": "b0e781a5-c0e3-42eb-9d6c-f030396f8ee5",
"reservation_date": "2020-08-05",
"reservation_slot": "00:00:00-23:59:00",
"reservation_status": "CONFIRMED",
"ticket_nbr": "NCT-0805-00666",
"pin_nbr": "1234",
"transreq_dttm": "2020-08-05T10:59:55.1564286+00:00",
"booked_dttm": "2020-08-05T10:59:55.1564286+00:00",
"booked_by": "baf1d356-c119-48cf-ada1-cac3d1f11040",
"move_id": "b0e781a5-c0e3-42eb-9d6c-f030396f8ee5",
"move_type": "IP",
"duelmove_flag": "N",
"order_type": "",
"order_nbr": "",
"sztype_cd": "40DH",
"speedgate_flag": "N",
"trucker_info": {
"trucker_scac": "TMBL",
"truck_nbr": null,
"lic_plate_nbr": "",
"lic_plate_state_cd": null,
"rfid_tag": "",
"driver_id": null,
"driver_fname": "",
"driver_lname": ""
},
"units": [
{
"unit_nbr": "TRLU6850740",
"unit_category": "CN",
"line_scac": "MAEU",
"sztype_iso": "40A0",
"sztype_cd": "40DH",
"yard_spot": "UNKNOWN",
"seal_nbrs": [],
"spcl_instructions": [
{
"instructions": ""
}
],
"accessories": [
{
"unit_nbr": null,
"unit_category": "CHS",
"sztype_cd": null
}
]
}
],
"chassis_req": {
"chassis_nbr": null,
"owner": "POOL",
"iep_scac": null,
"sztype_cd": null,
"chs_weight": "0.0",
"weight_uom": null
},
"reservation_msgs": [],
"terminal_msgs": null,
"ticket": null
}
]
}
Service Order updates can be received through the Service Bus only. For additional information on how to interact with the Azure Service Bus please refer to the Service Bus Runtime REST documentation.
DELETE https://[[namespaceName]].servicebus.windows.net/[[topic]]/subscriptions/serviceorderupdates/messages/head
Key | Value |
---|---|
Authorization | SharedAccessSignature [[value]] |
None
curl "https://[[namespaceName]].servicebus.windows.net/[[topic]]/subscriptions/serviceorderupdates/messages/head" \
-X DELETE \
-H 'Authorization: SharedAccessSignature [[value]]'
{
"service_order": {
"serviceorderuid": "eca4cac4-8322-4702-92d0-a600ce2069db",
"header": {
"sender_cd": "SOTC",
"receiver_cd": "eds",
"drayexchange_id": null,
"trans_dttm": "2022-05-25T16:09:20.0929209Z",
"requesteddt_tm": null,
"company_uid": "86f2abcd-db29-480a-b6ab-dbdf6739820d",
"company_cd": "SOTC"
},
"order": [
{
"trade_type": "I",
"order_type": null,
"order_nbr": "",
"order_status": "PENDING",
"unit": {
"unit_nbr": "TRLU6850740",
"unit_category": "CN",
"line_scac": "MAEU",
"sztypeiso_cd": "40A0",
"seal_nbrs": [],
"accessories": null
},
"metadata": null,
"locations": [
{
"loc_type": "O",
"loc_port": "OAK",
"location_cd": "B58",
"arrcarrier_type": null,
"arrcarrier_cd": null,
"eta": null,
"depcarrier_type": null,
"depcarrier_cd": null,
"etd": null,
"reservation_req": {
"reservation_id": null,
"action_cd": "A",
"reservation_type": "P",
"move_type": "P",
"pin_nbr": null,
"offdockcarr_type": null,
"hazmat_info": [
{
"haz_class": null,
"haz_uncode": null,
"un_nbr": null,
"class_desc": null,
"commodity_weight": null,
"quantity": null,
"package_group": null,
"commodity_name": null,
"emergency_ph": null,
"limited_qty": null,
"comments": null
}
],
"sztypeiso_cd": null,
"unit_full_empty": "FULL",
"reefer_flg": null,
"od_flg": null,
"reservation_preferences": {
"preference_datetimes": [
[
"2022-05-26T17:00:00.000Z",
"2022-05-26T23:59:59.000Z"
]
],
"business_date": null,
"reservation_time_from": null,
"reservation_time_to": null,
"try_later_dates": null
},
"bundle_info": [
{
"bundled_flag": null,
"unit_category": null,
"unit_nbr": null
}
],
"chassis_req": [
{
"chassis_nbr": null,
"owner": null,
"iep_scac": null,
"sztype_cd": null,
"chs_weight": null,
"weight_uom": null
}
],
"trucker_info": {
"trucker_scac": "SOTC",
"truck_nbr": null,
"lic_plate_nbr": null,
"lic_plate_state_cd": null,
"driver_id": null,
"driver_fname": "John",
"driver_lname": "Doe"
}
},
"services": [
{
"service_cd": "EMAPT",
"billing_cd": null
}
]
}
]
}
]
},
"status_cd": "PENDING",
"error_msg": "",
"error_dttm": "2022-05-25T16:10:06.0802239Z",
"order_info": [
{
"status_cd": "REQUESTED",
"unit_nbr": "TRLU6850740",
"service_cd": "EMAPT",
"service_msg": {
"msg_sev": "I",
"msg_cd": "Preadvice",
"msg_desc": "N/A"
}
}
]
}
Version Number | Description | Last Updated |
---|---|---|
2.5.4 | Moved documentation to new host and added features available in DEMO | 11/18/2020 |
2.6.0 | Added time and date time preferences for reservations. Added reservation examples. | 9/21/2021 |
2.6.1 | Improved description of trucker_info fields | 3/3/2022 |
2.7.0 | Updated Appointments and Service Order Updates messages | 5/27/2022 |
|