---
title: Reserve Slots
slug: fourkites-api-reference/reserve-slots
icon: {"apiMethod":"POST"}
createdAt: 2024-05-10T09:05:50.000Z
---
The Reserve Slots API will allow you to make a reservation for your load at a facility by passing on the necessary information about the load.
:::hint{type="info"}
You can either pass `loadNumber` & `shippingType` (or) `facilityId` & `calendarId`
:::
:::hint{type="success"}
Note that the expiry duration is not mandatory; the default expiry duration is 30 mins.
:::
:::hint{type="info"}
`reservedSlotName` need not be unique
:::
### Reserve slot using `loadNumber` & `shippingType`
:::ApiMethodV2
```json
{
"name": "Production",
"method": "POST",
"url": "https://api.fourkites.com/api/v1/reserve_slot",
"description": "",
"tab": "examples",
"examples": {
"languages": [
{
"id": "zWirRi_Z9D37lWDtFKtWl",
"language": "curl",
"code": "curl --location --request POST 'https://api.fourkites.com/api/v1/reserve_slot' \\\n--header 'Content-Type: application/json' \\\n--header 'apikey: REPLACE_KEY_VALUE' \\\n--data-raw '{\n \"loadNumber\" : \"Nb32123\",\n \"shippingType\": \"inbound\",\n \"appointmentStart\" : \"2024-03-13T00:00:00Z\",\n \"appointmentEnd\": \"2024-03-13T01:00:00Z\",\n \"expiryInMins\" : 30,\n \"reservedSlotName\": \"Reservation for Load Nb32123\"\n}'",
"customLabel": ""
}
],
"selectedLanguageId": "zWirRi_Z9D37lWDtFKtWl"
},
"results": {
"languages": [
{
"id": "Dh6grlRjuqGxTjFqtnmu-",
"language": "200",
"customLabel": "",
"code": "{\n \"statusCode\": 200\n \"message\": \"Slots reserved successfully\",\n \"request_id\": \"cnrebhp2kfp1012q5ug0\",\n \"data\": {\n \"reserveSlotId\": 789799,\n \"companyId\": \"shipper-sera\",\n \"facilityId\": \"Rk1fOTAzMTQy\",\n }\n}"
}
],
"selectedLanguageId": "Dh6grlRjuqGxTjFqtnmu-"
},
"request": {
"pathParameters": [],
"queryParameters": [],
"headerParameters": [],
"bodyDataParameters": [
{
"name": "loadNumber",
"kind": "required",
"type": "string",
"description": "It is the unique load identifier from shipper's system. The load number or BOL is an important piece of information used to link the load with truck information received from the Carrier's TMS."
},
{
"name": "shippingType",
"kind": "required",
"type": "string",
"description": "Indicates Inbound or Outbound Shipping Type",
"children": []
},
{
"name": "appointmentStart",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment start time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "appointmentEnd",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment end time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "expiryInMins",
"kind": "optional",
"type": "string",
"description": "It indicates the expiry duration. The default expiry duration is 30 mins.",
"children": []
},
{
"name": "reservedSlotName",
"kind": "required",
"type": "string",
"description": "Name given to the slot. It need not be unique.",
"children": []
}
],
"formDataParameters": []
},
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"hasTryItOut": false,
"autoGeneratedAnchorSlug": "production",
"legacyHash": "rJpWtMNLMQ8zg7hIiNLsI"
}
```
:::
:::ApiMethodV2
```json
{
"name": "Staging",
"method": "POST",
"url": "https://api-staging.fourkites.com/api/v1/reserve_slot",
"description": "",
"tab": "examples",
"examples": {
"languages": [
{
"id": "zWirRi_Z9D37lWDtFKtWl",
"language": "curl",
"code": "curl --location --request POST 'https://api-staging.fourkites.com/api/v1/reserve_slot' \\\n--header 'Content-Type: application/json' \\\n--header 'apikey: REPLACE_KEY_VALUE' \\\n--data-raw '{\n \"loadNumber\" : \"Nb32123\",\n \"shippingType\": \"inbound\",\n \"appointmentStart\" : \"2024-03-13T00:00:00Z\",\n \"appointmentEnd\": \"2024-03-13T01:00:00Z\",\n \"expiryInMins\" : 30,\n \"reservedSlotName\": \"Reservation for Load Nb32123\"\n}'",
"customLabel": ""
}
],
"selectedLanguageId": "zWirRi_Z9D37lWDtFKtWl"
},
"results": {
"languages": [
{
"id": "Dh6grlRjuqGxTjFqtnmu-",
"language": "200",
"customLabel": "",
"code": "{\n \"statusCode\": 200\n \"message\": \"Slots reserved successfully\",\n \"request_id\": \"cnrebhp2kfp1012q5ug0\",\n \"data\": {\n \"reserveSlotId\": 789799,\n \"companyId\": \"shipper-sera\",\n \"facilityId\": \"Rk1fOTAzMTQy\",\n }\n}"
}
],
"selectedLanguageId": "Dh6grlRjuqGxTjFqtnmu-"
},
"request": {
"pathParameters": [],
"queryParameters": [],
"headerParameters": [],
"bodyDataParameters": [
{
"name": "loadNumber",
"kind": "required",
"type": "string",
"description": "It is the unique load identifier from shipper's system. The load number or BOL is an important piece of information used to link the load with truck information received from the Carrier's TMS."
},
{
"name": "shippingType",
"kind": "required",
"type": "string",
"description": "Indicates Inbound or Outbound Shipping Type",
"children": []
},
{
"name": "appointmentStart",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment start time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "appointmentEnd",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment end time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "expiryInMins",
"kind": "optional",
"type": "string",
"description": "It indicates the expiry duration. The default expiry duration is 30 mins.",
"children": []
},
{
"name": "reservedSlotName",
"kind": "required",
"type": "string",
"description": "Name given to the slot. It need not be unique.",
"children": []
}
],
"formDataParameters": []
},
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"hasTryItOut": false,
"autoGeneratedAnchorSlug": "staging",
"legacyHash": "QKroXIerQ2Oljfep4wfQc"
}
```
:::
### Reserve slot using `facilityId` & `calendarId`
:::ApiMethodV2
```json
{
"name": "Production",
"method": "POST",
"url": "https://api.fourkites.com/api/v1/reserve_slot",
"description": "",
"tab": "examples",
"examples": {
"languages": [
{
"id": "srjhXk3yYkBqKRdaSX-KB",
"language": "curl",
"code": "curl --location --request POST 'https://api.fourkites.com/api/v1/reserve_slot' \\\n--header 'Content-Type: application/json' \\\n--header 'apikey: REPLACE_KEY_VALUE' \\\n--data-raw '{ \"facilityId\": \"Rk1fOTAzMTQy\",\n \"calendarId\": 345,\n \"appointmentStart\" : \"2024-03-13T00:00:00Z\",\n \"appointmentEnd\": \"2024-03-13T01:00:00Z\",\n \"expiryInMins\" : 30,\n \"reservedSlotName\": \"Reservation-1\"\n}'",
"customLabel": ""
}
],
"selectedLanguageId": "srjhXk3yYkBqKRdaSX-KB"
},
"results": {
"languages": [
{
"id": "QrqtUROo4IlYifjQs6UDI",
"language": "200",
"customLabel": "",
"code": "{\n \"statusCode\": 200\n \"message\": \"Slots reserved successfully\",\n \"request_id\": \"cnrebhp2kfp1012q5ug0\",\n \"data\": {\n \"reserveSlotId\": 789799,\n \"companyId\": \"shipper-sera\",\n \"facilityId\": \"Rk1fOTAzMTQy\",\n }\n}"
}
],
"selectedLanguageId": "QrqtUROo4IlYifjQs6UDI"
},
"request": {
"pathParameters": [],
"queryParameters": [],
"headerParameters": [],
"bodyDataParameters": [
{
"name": "facilityId",
"kind": "required",
"type": "string",
"description": "Indicates the facility ID."
},
{
"name": "calendarId",
"kind": "required",
"type": "string",
"description": "Indicates the calendar ID.",
"children": []
},
{
"name": "appointmentStart",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment start time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "appointmentEnd",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment end time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "expiryInMins",
"kind": "optional",
"type": "string",
"description": "It indicates the expiry duration. The default expiry duration is 30 mins.",
"children": []
},
{
"name": "reservedSlotName",
"kind": "required",
"type": "string",
"description": "Name given to the slot. It need not be unique.",
"children": []
}
],
"formDataParameters": []
},
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"hasTryItOut": false,
"autoGeneratedAnchorSlug": "production-1",
"legacyHash": "aliIyMfoD_CjD1N7BGE-v"
}
```
:::
:::ApiMethodV2
```json
{
"name": "Staging",
"method": "POST",
"url": "https://api-staging.fourkites.com/api/v1/reserve_slot",
"description": "",
"tab": "examples",
"examples": {
"languages": [
{
"id": "srjhXk3yYkBqKRdaSX-KB",
"language": "curl",
"code": "curl --location --request POST 'https://api-staging.fourkites.com/api/v1/reserve_slot' \\\n--header 'Content-Type: application/json' \\\n--header 'apikey: REPLACE_KEY_VALUE' \\\n--data-raw '{ \"facilityId\": \"Rk1fOTAzMTQy\",\n \"calendarId\": 345,\n \"appointmentStart\" : \"2024-03-13T00:00:00Z\",\n \"appointmentEnd\": \"2024-03-13T01:00:00Z\",\n \"expiryInMins\" : 30,\n \"reservedSlotName\": \"Reservation-1\"\n}'",
"customLabel": ""
}
],
"selectedLanguageId": "srjhXk3yYkBqKRdaSX-KB"
},
"results": {
"languages": [
{
"id": "QrqtUROo4IlYifjQs6UDI",
"language": "200",
"customLabel": "",
"code": "{\n \"statusCode\": 200\n \"message\": \"Slots reserved successfully\",\n \"request_id\": \"cnrebhp2kfp1012q5ug0\",\n \"data\": {\n \"reserveSlotId\": 789799,\n \"companyId\": \"shipper-sera\",\n \"facilityId\": \"Rk1fOTAzMTQy\",\n }\n}"
}
],
"selectedLanguageId": "QrqtUROo4IlYifjQs6UDI"
},
"request": {
"pathParameters": [],
"queryParameters": [],
"headerParameters": [],
"bodyDataParameters": [
{
"name": "facilityId",
"kind": "required",
"type": "string",
"description": "Indicates the facility ID."
},
{
"name": "calendarId",
"kind": "required",
"type": "string",
"description": "Indicates the calendar ID.",
"children": []
},
{
"name": "appointmentStart",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment start time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "appointmentEnd",
"kind": "required",
"type": "string",
"description": "It indicates the scheduled appointment end time at the facility in the stop's local timezone in ISO 8601 format.",
"children": []
},
{
"name": "expiryInMins",
"kind": "optional",
"type": "string",
"description": "It indicates the expiry duration. The default expiry duration is 30 mins.",
"children": []
},
{
"name": "reservedSlotName",
"kind": "required",
"type": "string",
"description": "Name given to the slot. It need not be unique.",
"children": []
}
],
"formDataParameters": []
},
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"hasTryItOut": false,
"autoGeneratedAnchorSlug": "staging-1",
"legacyHash": "Wj6jg1KrRIZO48DlP55JP"
}
```
:::
### Error Response
| | |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| Invalid Auth | \:::BlockQuote |
| \{"message": "Invalid authentication credentials"} | |
| \::: | |
| Load Number & shipping Type or CalendarId & facility Id not passed | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "Load Number and ShippingType or FacilityId and CalendarId either one of the combination is required",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotjjn1628du4065nrqg"
} | |
| \::: | |
| Start Time provided is greater than end Time | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "StartTime should be lesser than EndTime",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotjldh628drfoss63l0"
} | |
| \::: | |
| Load Not Found | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "The shipment does not have an associated appointment",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotjn5d6le7lklkgs4i0"
} | |
| \::: | |
| Load with same shipping type found in more than 1 facility | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "The shipment has multiple appointments associated",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotjntd6le7lklkgs4l0"
} | |
| \::: | |
| Appointment Already booked on reserved slot | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "Appointment already booked on the reserved slot",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotlend6le7hocm48m00"
} | |
| \::: | |
| Same Appointment Start & End | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "Appointment is already Scheduled on the given Time",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotlh0h628drfoss63lg"
} | |
| \::: | |
| Not passing reserved slot name , start time , end time | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "Invalid Request Params",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "Key: 'ReserveSlot.ReserveSlotName' Error\:Field validation for 'ReserveSlotName' failed on the 'required' tag",
"message": "Invalid Request Params"
},
\{
"domain": "oas",
"reason": "Key: 'ReserveSlot.StartTime' Error\:Field validation for 'StartTime' failed on the 'required' tag",
"message": "Invalid Request Params"
},
\{
"domain": "oas",
"reason": "Key: 'ReserveSlot.EndTime' Error\:Field validation for 'EndTime' failed on the 'required' tag",
"message": "Invalid Request Params"
}
]
},
"request\_id": "cotjoml6le7lklkgs4mg"
} | |
| \::: | |
| No slots available | \:::BlockQuote |
| \{
"code": 400,
"error": \{
"message": "This slot is no longer available, please select a different slot",
"code": 400,
"errors": \[
\{
"domain": "oas",
"reason": "",
"message": "This slot is no longer available, please select a different slot"
}
]
},
"request\_id": "cotlc3t6le7hocm48hs0"
} | |
| \::: | |