Schedule a dock appointment

You may use the guide and the steps below to implement a dock appointment scheduling flow.

To book a dock appointment using our Dock Scheduling APIs you will need the facility_id and shipment_id that the appointment is related to and then make calls to the following two endpoints.

Get a list of docks and availabilities at a specified facility from /facilities/{facility_id}/availability
Create the appointment at /facilities/{facility_id}/docks/{dock_id}/appointments using the information from the previous step

Note

Shipwell Dock Scheduling is in early access for select customers. If you are an existing Shipwell customer and want early access to Shipwell Dock Scheduling contact your customer service representative. If you want to learn more as a new Shipwell customer contact sales here.

Dock Scheduling API Reference

In order to manage facilities, dock appointments, and other dock scheduling functionality through the API you may also explore and interact with the dock scheduling endpoints with Postman using the API specification below:

Download or explore the Open API specification for the latest version of Shipwell's Dock Scheduling APIs.
- Dock Scheduling Open API Specification

Get a Shipment Id by Purchase Order Number

Freight invoices can be created in several ways:

Example request

curljavascriptpythonjava

Copy

Copied

curl --location --request GET 'https://sandbox-api.shipwell.com/v2/purchase-orders?order_number={orderNumber}' \
    --header 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const orderNumber = "YOUR_orderNumber_PARAMETER";
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";

const query = new URLSearchParams({
  order_number: orderNumber,
}).toString();

const targetUrl = `https://${host}${basePath}/purchase-orders?${query}`;

const resp = await fetch(
  targetUrl,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    },
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

order_number = "YOUR_orderNumber_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/purchase-orders"
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

query_params = {
    "order_number": order_number
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)

Copy

Copied

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String orderNumber = "YOUR_orderNumber_PARAMETER";
String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/purchase-orders" +
  "?orderNumber=" +
  orderNumber;

Request request = new Request.Builder()
  .url(targetUrl)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}

Example response

Note

There is a single result because only one PurchaseOrder matches the order_number .
This is not guaranteed to be unique and will only be unique if external system keeps each PurchaseOrder 's order_number unique
Our single example result has a not-null shipment_id , meaning it has been assigned to a Shipment . If this is null, it means the PurchaseOrder has not yet been assigned as must be assigned before creating a Shipment -related Appointment
Because shipment_id is not-null, there are also non-null values for origin_stop_id and destination_stop_id . Each of these Stop ID s points to a Stop under the Shipment with shipment_id .

Copy

Copied

{
   "total_count":1,
   "total_pages":1,
   "page_size":20,
   "results":[
      {
         "id":"bcf7987a-5958-4b4a-8a4a-8ca2371d7d14",
         "created_by_user":{
            "id":"1f4fec2f-d4fe-4341-9872-a23677497fac",
            "first_name":"Tester",
            "last_name":"McTester",
            "email":"noreply@shipwell.com",
            "phone_number":"+15555555555"
         },
         "origin_address":{
            "id":"59fb33dc-5575-495a-8606-83260ccbcef2",
            "address_1":"1234 Rock Rose Ave",
            "address_2":null,
            "city":"Austin",
            "state_province":"TX",
            "postal_code":"78758",
            "country":"US",
            "phone_number":null,
            "latitude":30.4024521,
            "longitude":-97.7219818,
            "timezone":"America/Chicago",
            "formatted_address":"1234 Rock Rose Ave, Austin, TX 78758, US",
            "created_at":"2023-05-31T22:05:49.715465Z",
            "updated_at":"2023-06-07T15:22:22.866193Z"
         },
         "destination_address":{
            "id":"4cd23a30-c867-4264-b1ba-0a689143a171",
            "address_1":"4401 N Interstate Hwy 35",
            "address_2":null,
            "city":"Round Rock",
            "state_province":"TX",
            "postal_code":"78665",
            "country":"US",
            "phone_number":null,
            "latitude":30.56356559999999,
            "longitude":-97.69021180000001,
            "timezone":"America/Chicago",
            "formatted_address":"4401 N Interstate Hwy 35, Round Rock, TX 78665, US",
            "created_at":"2023-05-31T22:05:49.720251Z",
            "updated_at":"2023-06-07T15:22:22.874778Z"
         },
         "line_items":[
            {
               "id":"50f4f913-86bd-4464-a2b0-4dac8ec2f724",
               "created_at":"2023-05-31T22:05:49.772491Z",
               "updated_at":"2023-06-07T15:23:35.878225Z",
               "piece_type":"BALE",
               "package_type":"BALE",
               "freight_class":null,
               "nmfc_item_code":"2323",
               "nmfc_sub_code":"23",
               "stackable":false,
               "hazmat_hazard_class":null,
               "hazmat_identification_number":null,
               "hazmat_proper_shipping_name":null,
               "hazmat_packing_group":null,
               "height":23.0,
               "length":23.0,
               "width":42.0,
               "length_unit":"IN",
               "value_per_piece":234.0,
               "description":"Digitized Unbranded Rubber Pizza - Soft ivory - oce-zoc",
               "product_ref":"Digitized Unbranded Rubber Pizza",
               "product_category":null,
               "total_packages":111,
               "total_pieces":null,
               "weight_unit":"LB",
               "refrigeration_required":false,
               "refrigeration_min_temp":23.0,
               "refrigeration_max_temp":24.0,
               "temp_unit":"F",
               "provider_specific_packaging":null,
               "custom_data":{
                  "shipwell_custom_data":{
                     
                  }
               },
               "package_weight":23.0,
               "total_line_item_weight":2553.0,
               "country_of_manufacture":null
            }
         ],
         "origin_stop":"3e89c1ea-2fde-41c7-bd65-03182e7d6268",
         "origin_stop_alerts":[
            
         ],
         "destination_stop":"d6264e6c-f997-455e-8073-86fa7d0f9314",
         "destination_stop_alerts":[
            {
               "id":"7f7cbdb8-4724-456c-b0ab-14a6cf551edb",
               "created_at":"2023-06-07T21:25:10.727655Z",
               "updated_at":"2023-06-07T21:25:10.728338Z",
               "stop":"d6264e6c-f997-455e-8073-86fa7d0f9314",
               "alert_type":"NO_MATCHED_LOAD_TYPE",
               "reason_code":"OTHER",
               "occurred_at":null,
               "created_by_user":null,
               "created_by_driver":null,
               "description":"Stop does not match any LoadType",
               "location":null,
               "expiration":null
            }
         ],
         "shipment":{
            "id":"9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
            "name":null,
            "state":"tendered",
            "reference_id":"QLFXXA",
            "customer_reference_number":null
         },
         "overall_status":"ASSIGNED",
         "deleted_at":null,
         "created_at":"2023-05-31T22:05:49.723471Z",
         "updated_at":"2023-06-07T15:22:24.204699Z",
         "custom_data":{
            "shipwell_custom_data":{
               "purchase_order":{
                  "354cc2ca-224d-438f-bdd9-3dee3d94cfbf":"test",
                  "5fbb520c-f3c1-4b0b-98af-4afc00e686b7":null,
                  "762e7dac-8590-49fd-9e58-74f60cd4ae05":null,
                  "770b105b-34e5-4bc3-a27e-3a1461b2f5fb":null,
                  "782e3c85-227b-4a5d-b2f0-749803c0632d":null,
                  "9de51a29-5b69-4bb5-9250-d51070a9424e":null,
                  "b63dbff8-f483-4fc3-9975-67aabf6355ab":null,
                  "b82888c5-6238-4628-b24a-2dc2f58aaa25":null,
                  "bf2d06a3-87b3-40e4-b44a-efc16d16e342":null
               },
               "purchase_order_stop":{
                  "pickup":{
                     "1739879e-b27c-43e9-8496-824d5dfdadb3":null,
                     "4744c26a-b12d-4bb2-8bbb-403178287bb0":null,
                     "71a0b26c-7fd7-4525-8424-fedf956eeb0c":null,
                     "abecc19a-c918-47c9-be7c-e67b00814e9f":"PO-DOMAIN001"
                  },
                  "delivery":{
                     "1739879e-b27c-43e9-8496-824d5dfdadb3":null,
                     "4744c26a-b12d-4bb2-8bbb-403178287bb0":null,
                     "71a0b26c-7fd7-4525-8424-fedf956eeb0c":null,
                     "abecc19a-c918-47c9-be7c-e67b00814e9f":"PO-ROUNDROCK001"
                  }
               }
            }
         },
         "order_number":"000111",
         "name":"Something111",
         "description":null,
         "purchase_order_number":"0001111",
         "source":"SHIPWELL_WEB",
         "source_system_id":null,
         "status":"",
         "transit_status":null,
         "transit_status_reason_code":null,
         "customer_external_id":null,
         "customer_name":"Delivery Company (Round Rock)",
         "supplier_external_id":null,
         "supplier_name":"AB Pickup Company Domain",
         "planned_pickup_start_datetime":null,
         "planned_pickup_end_datetime":null,
         "planned_delivery_start_datetime":null,
         "planned_delivery_end_datetime":null,
         "actual_pickup_datetime":null,
         "actual_delivery_datetime":null,
         "origin_dock_external_id":null,
         "destination_dock_external_id":null,
         "origin_appointment_external_id":null,
         "destination_appointment_external_id":null,
         "subtotal_amount_currency":"USD",
         "subtotal_amount":null,
         "tax_amount_currency":"USD",
         "tax_amount":null,
         "invoice_external_id":null,
         "shipment_id":"9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
         "origin_stop_id":"3e89c1ea-2fde-41c7-bd65-03182e7d6268",
         "destination_stop_id":"d6264e6c-f997-455e-8073-86fa7d0f9314",
         "archived":false,
         "origin_address_book_entry":"12e0c8df-3152-4fc6-ad8e-c51fa3bee073",
         "destination_address_book_entry":"46717ac6-e04d-40e2-aa01-9fae907f7668",
         "company":"a54ef012-77d4-44a0-8ba5-115b09b655be"
      }
   ]
}

Get a Stop Id from a Shipment Id

Starting with the shipment_id from the previous step, to create an Appointment for the origin Stop, you need to:

Get the Shipment by shipment_id , along with all its Stops
Find the Stop 's stop_id
Find the facility_id of the Stop (aka find the facility_id associated with the stop_id )

Example request

curljavascriptpythonjava

Copy

Copied

curl --location --request GET 'https://sandbox-api.shipwell.com/v2/shipments/{shipmentId}' \
    --header 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const shipmentId = "YOUR_shipmentId_PARAMETER";
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";

const targetUrl = `https://${host}${basePath}/shipments/${shipmentId}`;

const resp = await fetch(
  targetUrl,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    },
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

shipment_id = "YOUR_shipment_id_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/shipments"
    + "/"
    + shipment_id
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)

Copy

Copied

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String shipmentId = "YOUR_shipmentId_PARAMETER";
String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/shipments" +
  "/"
  shipmentId;

Request request = new Request.Builder()
  .url(targetUrl)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}

Example response

Note

Since we are targeting the PurchaseOrder 's origin_stop_id=3e89c1ea-2fde-41c7-bd65-03182e7d6268 , we can search the stops array for a Stop with an id that matches that value. This Stop appears as the first item in our stops array.
Once we find that Stop , we can look at its location.facility_id property to see if that Stop is associated with a Facility. If it is null, this means that the Stop did not match to any known Facility .
- Troubleshooting Tip: The main problem is that PurchaseOrder did not have an origin_address_book_entry whose associated AddressBookEntry has the facility_id you were hoping for.
In our example, stops[0]["location"]["facility"] has a not-null value of 01GW3NJJHQEC7VYAXMWFHCTX53 , so we can move on to searching for availability at the Facility .

Copy

Copied

{
  "id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
  "accessorials": [],
  "auction_stats": {
    "negotiations": 0,
    "has_open_auction": false,
    "quotes": 0,
    "declined_quotes": 0,
    "messages": 0,
    "most_recent_quote_created_at": null,
    "visible_companies": 0,
    "lowest_bid": null
  },
  "created_by_user": {
    "id": "1f4fec2f-d4fe-4341-9872-a23677497fac",
    "first_name": "Tester",
    "last_name": "McTester",
    "email": "noreply@shipwell.com",
    "phone_number": "+15555555555"
  },
  "current_carrier": {
    "id": "112569c5-0c13-427b-9f97-fc9e9f7a444a",
    "name": "Anurag_Carrier001",
    "dba_name": null,
    "primary_phone_number": "+15128064080",
    "primary_email": "anurag+c001@shipwell.com",
    "mailing_address": {
      "id": "c40381ee-52d8-4c75-b3fc-d5264ec811d1",
      "address_1": "1234 Monterey Oaks Blvd",
      "address_2": null,
      "city": "Austin",
      "state_province": "TX",
      "postal_code": "78749",
      "country": "US",
      "phone_number": null,
      "latitude": 30.2315803,
      "longitude": -97.8404906,
      "timezone": "America/Chicago",
      "formatted_address": "1234 Monterey Oaks Blvd, Austin, TX 78749, US",
      "created_at": "2021-08-30T17:06:38.089085Z",
      "updated_at": "2023-05-31T19:24:42.651550Z"
    },
    "billing_address": {
      "id": "e3f3e11a-02c2-4125-814e-6afaf6181ce7",
      "address_1": "1234 Spyglass Dr",
      "address_2": null,
      "city": "Austin",
      "state_province": "TX",
      "postal_code": "78746",
      "country": "US",
      "phone_number": null,
      "latitude": 30.25641809999999,
      "longitude": -97.79263549999999,
      "timezone": "America/Chicago",
      "formatted_address": "1234 Spyglass Dr, Austin, TX 78746, US",
      "created_at": "2022-09-23T15:32:40.543965Z",
      "updated_at": "2023-05-31T19:24:42.656600Z"
    },
    "identifying_codes": [
      {
        "id": "4d2dffb0-9b29-44ca-91db-24fa59487a08",
        "type": "USDOT",
        "value": "918273",
        "created_at": "2021-11-03T16:02:54.174706Z",
        "updated_at": "2022-10-11T17:09:36.301101Z"
      },
      {
        "id": "fa98f3b5-4eb1-4ecc-837d-cb75c75405a8",
        "type": "SCAC",
        "value": "AG09874",
        "created_at": "2022-10-11T17:41:11.666626Z",
        "updated_at": "2022-10-11T17:41:11.668067Z"
      },
      {
        "id": "6ae48d25-c713-4dce-b12f-b64afb35ad15",
        "type": "MC_NUMBER",
        "value": "192838",
        "created_at": "2022-10-11T17:42:57.468298Z",
        "updated_at": "2022-10-11T17:42:57.469234Z"
      }
    ],
    "created_at": "2021-08-30T17:06:38.093162Z",
    "updated_at": "2023-03-03T03:00:19.723274Z",
    "brokerage": {
      "id": "29830d11-8c02-41db-b22b-306c70c1d236",
      "dba_name": null,
      "primary_phone_number": null,
      "primary_email": null,
      "mailing_address": null,
      "billing_address": null,
      "created_at": "2021-08-30T17:06:38.169508Z",
      "updated_at": "2022-10-11T17:09:36.288455Z",
      "is_3pl": false
    },
    "shipper": null,
    "carrier": {
      "id": "92d024d8-2d3f-48cd-bcce-0c0224ceb3fe",
      "dba_name": null,
      "approved_at": null,
      "service_center_lookup_url": null,
      "primary_phone_number": null,
      "primary_email": null,
      "mailing_address": null,
      "billing_address": null,
      "pickup_request_email": null,
      "accounts_receivable_email": null,
      "created_at": "2021-08-30T17:06:40.197089Z",
      "updated_at": "2022-10-11T17:09:36.280970Z",
      "display_name": "Anurag_Carrier001",
      "display_primary_email": "anurag+c001@shipwell.com",
      "display_primary_phone_number": "+15555555555",
      "usdot_number": "918273",
      "scac_number": "AG09874",
      "eld_providers": [],
      "last_power_unit_sync": null,
      "custom_data": null
    },
    "feature_flags": {
      "company": "112569c5-0c13-427b-9f97-fc9e9f7a444a",
      "datadocks_enabled": false,
      "can_initiate_mobile_ping_tracking": false,
      "can_override_bill_to_for_automated_ltl": false,
      "purchase_orders_enabled": false,
      "analytics_enabled": false,
      "uses_3pl_quoting_flow": false,
      "invoicing_enabled": false,
      "load_board_enabled": false,
      "show_load_board": true,
      "integrations_enabled": false,
      "fedex_enabled": false,
      "ftl_instant_rates_enabled": false,
      "supplier_invites_enabled": false,
      "triumph_pay_enabled": false,
      "ups_enabled": false,
      "freightwaves_driver_texts_enabled": false,
      "new_dashboard_enabled": false,
      "contracts_enabled": false,
      "usps_enabled": false,
      "historical_pricing_enabled": false,
      "policies_enabled": false,
      "rmis_enabled": false,
      "saferwatch_enabled": false,
      "send_shipwell_network_enabled": true,
      "bid_manager_enabled": false,
      "ch_robinson_enabled": false,
      "edi_invoicing_enabled": false,
      "netsuite_enabled": false,
      "stop_status_enabled": true,
      "rate_tables_enabled": false,
      "automatic_carrier_policy_enabled": false,
      "alerts_dashboard_enabled": false,
      "order_consolidation_workflows_enabled": false,
      "genesis_ltl_enabled": false,
      "mfa_enabled": false,
      "ceva_enabled": false,
      "direct_fedex_ltl_integration_enabled": false
    },
    "billing_emails": [
      "noreply@shipwell.com"
    ],
    "insurance_expires_at": null,
    "insurance_validated_at": null,
    "insurance_policy_number": null,
    "insurance_provider_name": null,
    "insurance_provider_phone": null,
    "is_shipwell": false,
    "custom_data": null,
    "mileage_type": null,
    "mileage_config_last_updated": null
  },
  "customer": {
    "id": "a54ef012-77d4-44a0-8ba5-115b09b655be",
    "name": "Shipwell, Inc.",
    "dba_name": "Shipwell, Inc.",
    "is_shipwell": true,
    "created_at": "2017-12-20T01:18:57.207800Z",
    "updated_at": "2023-05-18T15:00:05.119584Z",
    "brokerage": "ccba1015-467d-4ab0-b3a9-9531fd692d0f",
    "shipper": "3fc58ab5-3ef5-4541-bae9-51ab942a3770",
    "carrier": "c8b30bfe-3322-4172-8575-c44f3d2ed30c",
    "primary_email": "noreply@shipwell.com",
    "billing_emails": [
      "makar24242@shipwell.com",
      "another@example.com"
    ]
  },
  "custom_data": {
    "shipwell_custom_data": {
      "shipment": {
        "354cc2ca-224d-438f-bdd9-3dee3d94cfbf": "test"
      }
    }
  },
  "documents_count": 1,
  "equipment_type": {
    "id": 2,
    "machine_readable": "REEFER",
    "name": "Reefer"
  },
  "external_tracking_link": "https://sandbox-api.shipwell.com/tracking/9623405e-9bc5-4f8b-8b38-37cab1e3bb48/?key=dqDI6P864voFnwm3q2zaQd5T3EqvOCOU",
  "is_watched": false,
  "is_watchable": true,
  "line_items": [
    {
      "id": "f80884d8-ad6a-4062-9cc1-5ecca739cdd6",
      "order_number": "000111",
      "total_line_item_weight": 2553.0,
      "formatted_description": "111 BALEs, 2,553 lb (1,158.02132 kg), 23 x 42 x 23 in (58.42 x 106.68 x 58.42 cm), Digitized Unbranded Rubber Pizza - Soft ivory - oce-zoc",
      "deleted_at": null,
      "created_at": "2023-06-07T15:22:15.915428Z",
      "updated_at": "2023-06-07T15:23:35.858230Z",
      "custom_data": {
        "shipwell_custom_data": {}
      },
      "piece_type": "BALE",
      "product_category": null,
      "package_type": "BALE",
      "freight_class": null,
      "provider_specific_packaging": null,
      "nmfc_item_code": "2323",
      "nmfc_sub_code": "23",
      "stackable": false,
      "hazmat_hazard_class": null,
      "hazmat_identification_number": null,
      "hazmat_proper_shipping_name": null,
      "hazmat_packing_group": null,
      "height": 23.0,
      "length": 23.0,
      "width": 42.0,
      "length_unit": "IN",
      "value_per_piece_currency": "USD",
      "value_per_piece": 234.0,
      "package_weight": 23.0,
      "weight_unit": "LB",
      "refrigeration_required": false,
      "refrigeration_min_temp": 23.0,
      "refrigeration_max_temp": 24.0,
      "temp_unit": "F",
      "country_of_manufacture": null,
      "product_ref": "Digitized Unbranded Rubber Pizza",
      "description": "Digitized Unbranded Rubber Pizza - Soft ivory - oce-zoc",
      "total_packages": 111,
      "total_pieces": null,
      "insured_value_currency": "USD",
      "insured_value": null,
      "purchase_order_line_item_id": "50f4f913-86bd-4464-a2b0-4dac8ec2f724",
      "dry_ice_weight": null,
      "dry_ice_weight_unit": "LB",
      "purchase_order": "bcf7987a-5958-4b4a-8a4a-8ca2371d7d14"
    },
    {
      "id": "2bbcdfe2-abe6-4628-9114-fcb8d9c4e223",
      "order_number": "000222",
      "total_line_item_weight": 2553.0,
      "formatted_description": "111 BALEs, 2,553 lb (1,158.02132 kg), 23 x 42 x 23 in (58.42 x 106.68 x 58.42 cm), Digitized Unbranded Rubber Pizza - Soft ivory - oce-zoc",
      "deleted_at": null,
      "created_at": "2023-06-07T15:22:15.930433Z",
      "updated_at": "2023-06-07T15:23:35.899809Z",
      "custom_data": {
        "shipwell_custom_data": {}
      },
      "piece_type": "BALE",
      "product_category": null,
      "package_type": "BALE",
      "freight_class": null,
      "provider_specific_packaging": null,
      "nmfc_item_code": "2323",
      "nmfc_sub_code": "23",
      "stackable": false,
      "hazmat_hazard_class": null,
      "hazmat_identification_number": null,
      "hazmat_proper_shipping_name": null,
      "hazmat_packing_group": null,
      "height": 23.0,
      "length": 23.0,
      "width": 42.0,
      "length_unit": "IN",
      "value_per_piece_currency": "USD",
      "value_per_piece": 234.0,
      "package_weight": 23.0,
      "weight_unit": "LB",
      "refrigeration_required": true,
      "refrigeration_min_temp": 23.0,
      "refrigeration_max_temp": 24.0,
      "temp_unit": "F",
      "country_of_manufacture": null,
      "product_ref": "Digitized Unbranded Rubber Pizza",
      "description": "Digitized Unbranded Rubber Pizza - Soft ivory - oce-zoc",
      "total_packages": 111,
      "total_pieces": null,
      "insured_value_currency": "USD",
      "insured_value": null,
      "purchase_order_line_item_id": "9fad7c88-98e5-4196-853e-7eaca5a3e6ce",
      "dry_ice_weight": null,
      "dry_ice_weight_unit": "LB",
      "purchase_order": "66a11a12-ee8c-4440-973b-b323533756f0"
    }
  ],
  "markup": null,
  "messages_count": 0,
  "metadata": {
    "open": false,
    "alerts": [
      {
        "id": "a1c48b08-acb8-41d9-ac84-413dad12f437",
        "deleted_at": null,
        "created_at": "2023-06-07T21:25:12.823154Z",
        "updated_at": "2023-06-07T21:25:12.823697Z",
        "message": "One or more stops on this Shipment does not have a matching LoadType at its Facility",
        "level": "MEDIUM",
        "type": "MISMATCHES_LOAD_TYPE",
        "subtype": null,
        "occurred_at": null,
        "clear_alert_job_id": "d7d36b4c-f3e1-4314-a19e-764d8115a227",
        "metadata": "8a721ece-9a40-4608-8f4b-23abb472bfda"
      }
    ],
    "archived": false,
    "tags": [],
    "alert_level": "MEDIUM",
    "alert_message": null,
    "automation_enabled": false,
    "max_buy_amount": null,
    "max_buy_amount_currency": "USD",
    "target_rate_amount": null,
    "target_rate_amount_currency": "USD",
    "bill_to_override": {
      "id": "13249cc2-0f57-4f7c-9aed-c79e00d46423",
      "billing_id": null,
      "created_at": "2023-06-07T15:23:36.184962Z",
      "updated_at": "2023-06-07T15:23:36.186519Z",
      "company_name": "Shipwell, Inc.",
      "company_address": "515 Congress Ave, Austin, TX 78701, US",
      "contact_email": "makar24242@shipwell.com",
      "contact_phone": "+5555555555",
      "direction": "PREPAID"
    },
    "load_board_enabled": false,
    "buy_it_now_amount": null,
    "custom_data": null,
    "buy_it_now_amount_currency": "USD",
    "load_board_id": "LIDB5GXA2",
    "has_open_auction": false,
    "pending_tender_acceptance": false,
    "customer_side_accessorial_charge_table": null,
    "vendor_side_accessorial_charge_table": null,
    "customer_side_fuel_surcharge_table": null,
    "vendor_side_fuel_surcharge_table": null,
    "v3_shipment_reference_id": null
  },
  "mode": {
    "id": 1,
    "code": "FTL",
    "description": "Full Truckload"
  },
  "next_planned_stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
  "notes_count": 0,
  "parcel_pickup_status": null,
  "service_level": {
    "id": 19,
    "code": "STD",
    "description": "Standard Service"
  },
  "state": "tendered",
  "stops": [
    {
      "id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
      "location": {
        "id": "15430042-1fba-459a-98dc-8b8e0125a72d",
        "point_of_contacts": [
          {
            "id": "36724509-0666-46aa-ba37-440b5da84c93",
            "full_name": "domain",
            "preferences": {
              "cancellation": false,
              "delayed": false,
              "delivered": false,
              "eta_changed": false,
              "picked_up": false,
              "receive_bol_on_shipment_booked": false,
              "shipment_booked": false,
              "trailer_assigned": false
            },
            "phone_number": "+15128064080",
            "created_at": "2023-06-07T15:22:15.248934Z",
            "updated_at": "2023-06-07T15:23:34.945003Z",
            "first_name": "domain",
            "last_name": null,
            "job_title": null,
            "email": "northside@testooo.com"
          }
        ],
        "address": {
          "id": "cab819e1-8716-4232-94fb-7e9d3567da95",
          "formatted_address": "1234 Rock Rose Ave, Austin, TX 78758, US",
          "created_at": "2023-06-07T15:22:15.211784Z",
          "updated_at": "2023-06-07T15:23:34.929332Z",
          "address_1": "1234 Rock Rose Ave",
          "address_2": null,
          "city": "Austin",
          "state_province": "TX",
          "postal_code": "78758",
          "country": "US",
          "phone_number": null,
          "timezone": "America/Chicago",
          "latitude": 30.4024521,
          "longitude": -97.7219818
        },
        "location_type": {
          "id": 1,
          "name": "Business (with dock or forklift)"
        },
        "identification_code": null,
        "location_name": "Pickup @Domain",
        "company_name": "AB Pickup Company Domain",
        "created_using_address_book_entry_id": null,
        "facility_id": "01GW3NJJHQEC7VYAXMWFHCTX53",
        "created_at": "2023-06-07T15:22:15.217280Z",
        "updated_at": "2023-06-07T15:23:34.954249Z",
        "custom_data": null,
        "open_sunday": false,
        "sunday_open_time": null,
        "sunday_close_time": null,
        "open_monday": false,
        "monday_open_time": null,
        "monday_close_time": null,
        "open_tuesday": false,
        "tuesday_open_time": null,
        "tuesday_close_time": null,
        "open_wednesday": false,
        "wednesday_open_time": null,
        "wednesday_close_time": null,
        "open_thursday": false,
        "thursday_open_time": null,
        "thursday_close_time": null,
        "open_friday": false,
        "friday_open_time": null,
        "friday_close_time": null,
        "open_saturday": false,
        "saturday_open_time": null,
        "saturday_close_time": null,
        "dock_external_id": null,
        "notes": null
      },
      "accessorials": [],
      "appointment_type": {
        "id": 3,
        "code": "BY_APPT",
        "name": "By appointment"
      },
      "carrier_specified_eta": {
        "created_at": "2023-06-07T15:22:15.257491Z",
        "updated_at": "2023-06-07T15:22:15.259012Z",
        "initial_window_start": null,
        "initial_window_end": null,
        "running_window_start": null,
        "running_window_end": null,
        "overridden_initial_window_start": null,
        "overridden_initial_window_end": null
      },
      "predictive_model_eta": {
        "created_at": "2023-06-07T15:22:15.262111Z",
        "updated_at": "2023-06-07T15:22:15.263581Z",
        "initial_window_start": null,
        "initial_window_end": null,
        "running_window_start": null,
        "running_window_end": null,
        "overridden_initial_window_start": null,
        "overridden_initial_window_end": null
      },
      "display_eta_window": "Wed Jun 7, 08:00-18:00 CDT",
      "display_planned_window": "Wed Jun 7, 08:00-18:00 CDT",
      "display_schedule": "Wed Jun 7 between 08:00-18:00 CDT",
      "alerts": [],
      "trip_management_eta": null,
      "trip_management_eta_last_updated": null,
      "created_at": "2023-06-07T15:22:15.257117Z",
      "updated_at": "2023-06-07T15:23:34.992623Z",
      "custom_data": {
        "shipwell_custom_data": {
          "shipment_stop": {
            "abecc19a-c918-47c9-be7c-e67b00814e9f": "PO-DOMAIN001"
          }
        }
      },
      "appointment_needed": false,
      "planned_date": "2023-06-07",
      "planned_time_window_start": "08:00:00",
      "planned_time_window_end": "18:00:00",
      "confirmed_arrival_at": null,
      "confirmed_departure_at": null,
      "unconfirmed_arrival_at": null,
      "unconfirmed_departure_at": null,
      "ordinal_index": 1,
      "auto_ordinal_index": 1,
      "is_pickup": true,
      "is_dropoff": false,
      "on_time": null,
      "exclude_on_time": true,
      "on_time_exclusion_reason": null,
      "instructions": null,
      "internal_notes": null,
      "driver_pickup_confirmation_initial_job_id": null,
      "driver_pickup_confirmation_no_response_job_id": null,
      "driver_stop_completion_enter_no_exit_geofence_job_id": null,
      "driver_stop_completion_never_enter_geofence_job_id": null,
      "driver_24_hours_reminder_message_job_id": null,
      "start_tracking_job_id": null,
      "status": null,
      "status_reason_code": null,
      "eta_overridden_by": null
    },
    {
      "id": "3ff05a46-e37a-42c4-a733-1cfa863822d0",
      "location": {
        "id": "4b560000-0c91-4d33-82ad-99631cd9714a",
        "point_of_contacts": [
          {
            "id": "a5288f4d-9f05-45d9-ab46-54da68202bf1",
            "full_name": "test",
            "preferences": {
              "cancellation": false,
              "delayed": false,
              "delivered": false,
              "eta_changed": false,
              "picked_up": false,
              "receive_bol_on_shipment_booked": false,
              "shipment_booked": false,
              "trailer_assigned": false
            },
            "phone_number": "+15128064080",
            "created_at": "2023-06-07T15:23:35.286009Z",
            "updated_at": "2023-06-07T15:23:35.288686Z",
            "first_name": "test",
            "last_name": null,
            "job_title": null,
            "email": "test@testo.com"
          }
        ],
        "address": {
          "id": "6467ee2e-80bc-4453-a03d-d3dff704dd79",
          "formatted_address": "1234 Sunny Brook Dr, Leander, TX 78641, US",
          "created_at": "2023-06-07T15:22:15.421429Z",
          "updated_at": "2023-06-07T15:23:35.276833Z",
          "address_1": "712 Sunny Brook Dr",
          "address_2": null,
          "city": "Leander",
          "state_province": "TX",
          "postal_code": "78641",
          "country": "US",
          "phone_number": null,
          "timezone": "America/Chicago",
          "latitude": 30.5771316,
          "longitude": -97.88336389999999
        },
        "location_type": {
          "id": 1,
          "name": "Business (with dock or forklift)"
        },
        "identification_code": null,
        "location_name": "test something - Leander, TX, 78641",
        "company_name": "test something",
        "created_using_address_book_entry_id": null,
        "facility_id": null,
        "created_at": "2023-06-07T15:22:15.426724Z",
        "updated_at": "2023-06-07T15:23:35.297515Z",
        "custom_data": null,
        "open_sunday": false,
        "sunday_open_time": null,
        "sunday_close_time": null,
        "open_monday": false,
        "monday_open_time": null,
        "monday_close_time": null,
        "open_tuesday": false,
        "tuesday_open_time": null,
        "tuesday_close_time": null,
        "open_wednesday": false,
        "wednesday_open_time": null,
        "wednesday_close_time": null,
        "open_thursday": false,
        "thursday_open_time": null,
        "thursday_close_time": null,
        "open_friday": false,
        "friday_open_time": null,
        "friday_close_time": null,
        "open_saturday": false,
        "saturday_open_time": null,
        "saturday_close_time": null,
        "dock_external_id": null,
        "notes": null
      },
      "accessorials": [],
      "appointment_type": null,
      "carrier_specified_eta": {
        "created_at": "2023-06-07T15:22:15.451550Z",
        "updated_at": "2023-06-07T15:22:15.453354Z",
        "initial_window_start": null,
        "initial_window_end": null,
        "running_window_start": null,
        "running_window_end": null,
        "overridden_initial_window_start": null,
        "overridden_initial_window_end": null
      },
      "predictive_model_eta": {
        "created_at": "2023-06-07T15:22:15.456570Z",
        "updated_at": "2023-06-07T15:22:15.458431Z",
        "initial_window_start": null,
        "initial_window_end": null,
        "running_window_start": null,
        "running_window_end": null,
        "overridden_initial_window_start": null,
        "overridden_initial_window_end": null
      },
      "display_eta_window": "Thu Jun 8, 08:00-18:00 CDT",
      "display_planned_window": "Thu Jun 8, 08:00-18:00 CDT",
      "display_schedule": "Thu Jun 8 between 08:00-18:00 CDT",
      "alerts": [],
      "trip_management_eta": null,
      "trip_management_eta_last_updated": null,
      "created_at": "2023-06-07T15:22:15.451184Z",
      "updated_at": "2023-06-07T15:23:35.350693Z",
      "custom_data": {
        "shipwell_custom_data": {
          "shipment_stop": {}
        }
      },
      "appointment_needed": false,
      "planned_date": "2023-06-08",
      "planned_time_window_start": "08:00:00",
      "planned_time_window_end": "18:00:00",
      "confirmed_arrival_at": null,
      "confirmed_departure_at": null,
      "unconfirmed_arrival_at": null,
      "unconfirmed_departure_at": null,
      "ordinal_index": 2,
      "auto_ordinal_index": 2,
      "is_pickup": true,
      "is_dropoff": false,
      "on_time": null,
      "exclude_on_time": true,
      "on_time_exclusion_reason": null,
      "instructions": null,
      "internal_notes": null,
      "driver_pickup_confirmation_initial_job_id": null,
      "driver_pickup_confirmation_no_response_job_id": null,
      "driver_stop_completion_enter_no_exit_geofence_job_id": null,
      "driver_stop_completion_never_enter_geofence_job_id": null,
      "driver_24_hours_reminder_message_job_id": null,
      "start_tracking_job_id": null,
      "status": null,
      "status_reason_code": null,
      "eta_overridden_by": null
    }
  ]
  // ...
}

Determining Dock Availability

Coming into this step, we have three identifiers from prior steps:

shipment_id : 9623405e-9bc5-4f8b-8b38-37cab1e3bb48
stop_id : 3e89c1ea-2fde-41c7-bd65-03182e7d6268
facility_id : 01GW3NJJHQEC7VYAXMWFHCTX53

Now we can calculate the available time slots for docks that can accommodate the (Shipment, Stop) pair at the Facility.

Example request

About This Request Payload

start_datetime and end_datetime are both ISO 8601 date/time timestamp strings. They both must have explicit timezone information (i.e. in this case the Z suffix indicates UTC ). Other fixed offsets may be used instead, as long as the strings meet the ISO 8601 standard and have timezone information.
request_criteria_type is SHIPMENT . This request body is polymorphic meaning that the contents and shape of the request body may differ depending on how you want to search for availability. In our example where you come into this process with a Shipment ID and a Stop ID , the request_criteria_type should be SHIPMENT and this will require the inclusion of shipment_id and stop_id field values.
dock_ids is null , meaning we want to see results for all Docks that match the LoadType criteria of the (Shipment, Stop) pair. We could provide a non-empty list of ID strings, in which case only that subset of Docks will be considered.
rescheduling_for_appointment_id is null in the current case. Availability can vary depending on whether you are scheduling a new appointment vs. rescheduling an existing appointment. For example, 10:00 - 11:00 may be fully booked because Appointment1234 occurs during that window. If you want to create a new appointment from 10:30 - 11:00 , that not bookable. If instead you want to reschedule Appointment1234 , then 10:30 - 11:00 is an available option because you would be moving the appointment that is blocking that time window. To reschedule an appointment, the request body would contain "rescheduling_for_appointment_id": "1234" to indicate that.

curljavascriptpythonjava

Copy

Copied

curl -i -X POST \
  'https://sandbox-api.shipwell.com/facilities/{facility_id}/availability' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
   "start_datetime": "2023-06-11T19:00:00.0Z",
    "end_datetime": "2023-06-12T19:00:00.0Z",
    "request_criteria_type": "SHIPMENT",
    "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
    "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
    "dock_ids": null,
    "rescheduling_for_appointment_id": null
}'

Copy

Copied

const payload = {
    "start_datetime": "2023-06-11T19:00:00.0Z",
    "end_datetime": "2023-06-12T19:00:00.0Z",
    "request_criteria_type": "SHIPMENT",
    "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
    "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
    "dock_ids": null,
    "rescheduling_for_appointment_id": null
};

const facilityId = "YOUR_facilityId_PARAMETER";
const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/facilities/${facilityId}/availability`,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

facility_id = "YOUR_facilityId_PARAMETER"
base_path = ""
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/facilities/"
    + facility_id
    + "/availability"
)

headers = {"Content-Type": "application/json", "Authorization": "YOUR_AUTHORIZATION_HEADER"}

payload = {
  "start_datetime": "2023-06-11T19:00:00.0Z",
  "end_datetime": "2023-06-12T19:00:00.0Z",
  "request_criteria_type": "SHIPMENT",
  "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
  "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
  "dock_ids": None,
  "rescheduling_for_appointment_id": None
}

response = requests.post(target_url, headers=headers, json=payload)
data = response.json()
print(data)

Copy

Copied

import java.io.IOException;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String facilityId = "YOUR_facilityId_PARAMETER";
String basePath = "";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/facilities/" +
  facilityId +
  "/availability";

String requestBody = "{\"start_datetime\": \"2023-06-11T19:00:00.0Z\"," + 
                      "\"end_datetime\": \"2023-06-12T19:00:00.0Z\"," + 
                      "\"request_criteria_type\": \"SHIPMENT\"," + 
                      "\"shipment_id\": \"9623405e-9bc5-4f8b-8b38-37cab1e3bb48\"," +
                      "\"stop_id\": \"3e89c1ea-2fde-41c7-bd65-03182e7d6268\"," + 
                      "\"dock_ids\": null," + 
                      "\"rescheduling_for_appointment_id\": null}";

Request request = new Request.Builder()
    .url(targetUrl)
    .post(requestBody)
    .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
    .header("Content-Type", "application/json")
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
    response.body().string();
}

Example response

About This Response Payload

The available_windows list is the heart of the availability response data. This indicates which docks and timespans are available within the requested start_datetime to end_datetime window. The response will return the largest possible continuous windows.
In our example, Dock 01H0N9XX0FS1SPN6TP1WF2HTRF is available from 2023-06-12T05:00:00-05:00 - 2023-06-12T10:00:00-05:00 , meaning that you can schedule an Appointment at that Dock ID for any (start, end) timespan that falls within those two bounds.
These (start, end) timestamps (or timespans) are not guaranteed to snap to any clean hour/minute intervals. The above examples happen to fall cleanly on hour boundaries, but you could in theory have timestamps that look more like 2023-06-12T18:23:07.034-05:00 .
The load_type_dock_rule_match_results property provides information about which Docks/LoadTypes are matched given the provided criteria, in this case a (Shipment, Stop) pair. The presence of a LoadType ID or DockRule ID does not necessarily mean that Dock is available during the requested timeframe; only available_windows can tell you that. It means that, those LoadTypes/DockRules have the characteristics to handle your requested Shipment .
The availability_restrictions list is a troubleshooting tool that explains why certain slots of time between the request body 's (start_datetime - end_datetime) window are unavailable. These may be overlapping; e.g. Facility closes at 23:00 but also Dock is at max capacity . If you find yourself with an empty list of available_windows and do not understand why then inspect the availability_restrictions .

Copy

Copied

{
    "available_windows": [
        {
            "start": {
                "timestamp": "2023-06-12T05:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T10:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "dock_id": "01H0N9XX0FS1SPN6TP1WF2HTRF"
        }
    ],
    "load_type_dock_rule_match_results": {
        "facility_id": "01GW3NJJHQEC7VYAXMWFHCTX53",
        "matched_load_type_ids": [
            "01GX320ZVFZNHWQ8H9ZPKEKV7G"
        ],
        "matched_docks": [
            {
                "dock_id": "01H0N9XX0FS1SPN6TP1WF2HTRF",
                "dock_rule_ids": [
                    "01H0N9XXGPTHVWY0HW089DKK57"
                ]
            }
        ],
        "potential_appointment_types": [
            "BY_APPOINTMENT_ONLY"
        ],
        "all_matched_dock_rules": null
    },
    "availability_restrictions": [
        {
            "dock_id": "01GW3NJQ85ZBEQMTXT8X4K984B",
            "start": {
                "timestamp": "2023-06-11T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Dock 'Pickup Dock FTL-DryVan 1am-5am (Appt Only-loadID)' does not match the requested criteria"
        },
        {
            "dock_id": "01GW3NJQ85ZBEQMTXT8X4K984B",
            "start": {
                "timestamp": "2023-06-11T23:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T00:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Facility closes at 23:00:00"
        },
        {
            "dock_id": "01H0N9XX0FS1SPN6TP1WF2HTRF",
            "start": {
                "timestamp": "2023-06-11T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T05:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "No rule for Dock 'Pickup Dock FTL-Reefer 5am-10am (Appt Only-loadID)' matched during the time span (Jun 11, 10:00:00 - Jun 12, 05:00:00)"
        },
        {
            "dock_id": "01H0N9XX0FS1SPN6TP1WF2HTRF",
            "start": {
                "timestamp": "2023-06-11T23:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T00:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Facility closes at 23:00:00"
        },
        {
            "dock_id": "01H0N9XX0FS1SPN6TP1WF2HTRF",
            "start": {
                "timestamp": "2023-06-12T10:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "No rule for Dock 'Pickup Dock FTL-Reefer 5am-10am (Appt Only-loadID)' matched during the time span (Jun 12, 10:00:00 - Jun 12, 14:00:00)"
        },
        {
            "dock_id": "01H0N9XX0ZR9STWVRA2WCD5E36",
            "start": {
                "timestamp": "2023-06-11T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Dock 'Pickup Dock FTL-DryVan 10am-3pm (Appt Only-NOloadID)' does not match the requested criteria"
        },
        {
            "dock_id": "01H0N9XX0ZR9STWVRA2WCD5E36",
            "start": {
                "timestamp": "2023-06-11T23:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T00:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Facility closes at 23:00:00"
        },
        {
            "dock_id": "01H1YQZN09W5F97SBWAMP0EEYR",
            "start": {
                "timestamp": "2023-06-11T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Dock 'Pickup Dock FTL-DryVan 3pm-10pm (Appt Only-loadID)' does not match the requested criteria"
        },
        {
            "dock_id": "01H1YQZN09W5F97SBWAMP0EEYR",
            "start": {
                "timestamp": "2023-06-11T23:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T00:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Facility closes at 23:00:00"
        },
        {
            "dock_id": "01H1YS9A1KVS89PC3G4834HAWV",
            "start": {
                "timestamp": "2023-06-11T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T14:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Dock 'Pickup Dock LTL-Reefer 10pm-11pm (Appt Only-loadID)' does not match the requested criteria"
        },
        {
            "dock_id": "01H1YS9A1KVS89PC3G4834HAWV",
            "start": {
                "timestamp": "2023-06-11T23:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "end": {
                "timestamp": "2023-06-12T00:00:00-05:00",
                "timezone": "America/Chicago"
            },
            "reason": "Facility closes at 23:00:00"
        }
    ]
}

Creating a Dock Appointment

After calculating availability, we now have a few pieces of data that will be used to create an Appointment:

shipment_id : 9623405e-9bc5-4f8b-8b38-37cab1e3bb48
stop_id : 3e89c1ea-2fde-41c7-bd65-03182e7d6268
facility_id : 01GW3NJJHQEC7VYAXMWFHCTX53
matched_load_type_id : 01GX320ZVFZNHWQ8H9ZPKEKV7G

Available Window:

dock_id : 01H0N9XX0FS1SPN6TP1WF2HTRF
start : 2023-06-12T05:00:00-05:00
end : 2023-06-12T10:00:00-05:00

Now that we have this information, the Appointment may be created.

Example request

About This Request Payload

The request body 's start and end both fall within the (start, end) bounds determined by our availability API results and the dock_id from that availability result is in the URL path
stop_id matches the Stop we want to schedule
scheduled_resource_type is the enum member SHIPMENT , meaning this Appointment is being scheduled in order to accommodate a Shipment object
scheduled_resource_id is the value of the SHIPMENT 's ID
scheduled_resource_metadata contains information about the SHIPMENT resource being scheduled, primarily its shipment_id
matched_load_type_id comes from one of the load_type_dock_rule_match_results[].matched_load_type_ids above

curljavascriptpythonjava

Copy

Copied

curl -i -X POST \
  'https://sandbox-api.shipwell.com/facilities/{facility_id}/docks/{dock_id}/appointments' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER' \
  -H 'Content-Type: application/json' \
  -d '{
  "start": {
    "timestamp": "2023-06-12T06:30:00-05:00",
    "timezone": "America/Chicago"
  },
  "end": {
    "timestamp": "2023-06-12T07:00:00-05:00",
    "timezone": "America/Chicago"
  },
  "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
  "carrier_name": null,
  "carrier_contact": null,
  "carrier_tenant_id": null,
  "driver_id": null,
  "is_all_day": false,
  "appointment_type": "BY_APPOINTMENT_ONLY",
  "delivery_type": "SHIPPING",
  "scheduled_resource_type": "SHIPMENT",
  "scheduled_resource_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
  "scheduled_resource_metadata": {
      "resource_type": "SHIPMENT",
      "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48"
  },
  "matched_load_type_id": "01GX320ZVFZNHWQ8H9ZPKEKV7G"
}'

Copy

Copied

const form = new FormData();
const payload = {
  "start": {
    "timestamp": "2023-06-12T06:30:00-05:00",
    "timezone": "America/Chicago"
  },
  "end": {
    "timestamp": "2023-06-12T07:00:00-05:00",
    "timezone": "America/Chicago"
  },
  "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
  "carrier_name": null,
  "carrier_contact": null,
  "carrier_tenant_id": null,
  "driver_id": null,
  "is_all_day": false,
  "appointment_type": "BY_APPOINTMENT_ONLY",
  "delivery_type": "SHIPPING",
  "scheduled_resource_type": "SHIPMENT",
  "scheduled_resource_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
  "scheduled_resource_metadata": {
      "resource_type": "SHIPMENT",
      "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48"
  },
  "matched_load_type_id": "01GX320ZVFZNHWQ8H9ZPKEKV7G"
};

const facilityId = "YOUR_facilityId_PARAMETER";
const dockId = "YOUR_dockId_PARAMETER";
const basePath = "";
const host = "sandbox-api.shipwell.com";
const resp = await fetch(
  `https://${host}${basePath}/facilities/${facilityId}/docks/${dockId}/appointments`,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

facility_id = "YOUR_facilityId_PARAMETER"
dock_id = "YOUR_dockId_PARAMETER"
base_path = ""
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/facilities/"
    + facility_id
    + "/docks/"
    + dock_id
    + "/appointments"
)

headers = {"Content-Type": "application/json", "Authorization": "YOUR_AUTHORIZATION_HEADER"}

payload = {
  "start": {
    "timestamp": "2023-06-12T06:30:00-05:00",
    "timezone": "America/Chicago"
  },
  "end": {
    "timestamp": "2023-06-12T07:00:00-05:00",
    "timezone": "America/Chicago"
  },
  "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
  "carrier_name": None,
  "carrier_contact": None,
  "carrier_tenant_id": None,
  "driver_id": None,
  "is_all_day": False,
  "appointment_type": "BY_APPOINTMENT_ONLY",
  "delivery_type": "SHIPPING",
  "scheduled_resource_type": "SHIPMENT",
  "scheduled_resource_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
  "scheduled_resource_metadata": {
      "resource_type": "SHIPMENT",
      "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48"
  },
  "matched_load_type_id": "01GX320ZVFZNHWQ8H9ZPKEKV7G"
}
response = requests.post(target_url, headers=headers, json=payload)
data = response.json()
print(data)

Copy

Copied

import java.io.IOException;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String facilityId = "YOUR_facilityId_PARAMETER";
String dockId = "YOUR_dockId_PARAMETER";
String basePath = "";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/facilities/" +
  facilityId +
  "/docks/"
dockId +
  "/appointments";

String requestBody = "{\"start\": {\"timestamp\": \"2023-06-12T06:30:00-05:00\"," +
  "\"timezone\": \"America/Chicago\"}, \"end\": {\"timestamp\": \"2023-06-12T07:00:00-05:00\"," +
  "\"timezone\": \"America/Chicago\"  },  \"stop_id\": \"3e89c1ea-2fde-41c7-bd65-03182e7d6268\"," +
  "\"carrier_name\": null,  \"carrier_contact\": null,  \"carrier_tenant_id\": null,  \"driver_id\": null," +
  "\"is_all_day\": false,  \"appointment_type\": \"BY_APPOINTMENT_ONLY\",  \"delivery_type\": \"SHIPPING\"," +
  "\"scheduled_resource_type\": \"SHIPMENT\"," +
  "\"scheduled_resource_id\": \"9623405e-9bc5-4f8b-8b38-37cab1e3bb48\"," +
  "\"scheduled_resource_metadata\": {\"resource_type\": \"SHIPMENT\"," +
  "\"shipment_id\": \"9623405e-9bc5-4f8b-8b38-37cab1e3bb48\"}," +
  "\"matched_load_type_id\": \"01GX320ZVFZNHWQ8H9ZPKEKV7G\"}";

Request request = new Request.Builder()
  .url(targetUrl)
  .post(requestBody)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .header("Content-Type", "application/json")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}

Example response

Copy

Copied

{
    "start": {
        "timestamp": "2023-06-12T06:30:00-05:00",
        "timezone": "America/Chicago"
    },
    "end": {
        "timestamp": "2023-06-12T07:00:00-05:00",
        "timezone": "America/Chicago"
    },
    "name": null,
    "reason": null,
    "reference_id": null,
    "description": null,
    "stop_id": "3e89c1ea-2fde-41c7-bd65-03182e7d6268",
    "carrier_name": null,
    "carrier_contact": null,
    "carrier_tenant_id": null,
    "driver_id": null,
    "is_all_day": false,
    "appointment_type": "BY_APPOINTMENT_ONLY",
    "delivery_type": "SHIPPING",
    "scheduled_resource_type": "SHIPMENT",
    "scheduled_resource_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48",
    "scheduled_resource_metadata": {
        "resource_type": "SHIPMENT",
        "shipment_id": "9623405e-9bc5-4f8b-8b38-37cab1e3bb48"
    },
    "matched_load_type_id": "01GX320ZVFZNHWQ8H9ZPKEKV7G",
    "references": [
        {
            "qualifier": "SHIPMENT_REFERENCE_ID",
            "value": "QLFXXA"
        },
        {
            "qualifier": "BOL_NUMBER",
            "value": "SW2309052"
        },
        {
            "qualifier": "PRO_NUMBER",
            "value": "QLFXXA"
        },
        {
            "qualifier": "PO_NUMBER",
            "value": "0001111,0002222"
        }
    ],
    "id": "01H2ECDE5W2TENT154VSHCG07X",
    "facility_id": "01GW3NJJHQEC7VYAXMWFHCTX53",
    "dock_id": "01H0N9XX0FS1SPN6TP1WF2HTRF",
    "status": "SCHEDULED",
    "is_closed": false,
    "created_by": "7010b12d-e586-41be-bb04-eea32eecc71d",
    "deleted_by": null,
    "checked_in_at": null,
    "checked_in_by_user_id": null,
    "checked_out_at": null,
    "checked_out_by_user_id": null,
    "rejected_at": null,
    "rejected_reasons": null,
    "scheduled_resource_reference_id": "QLFXXA"
}

Now that an appointment is scheduled, actions on the appointment (i.e. rescheduling, canceling, check-in/start, check-out/end, etc.) may be performed using the related API endpoints under the appointments section of the API reference documentation.