# New Booking
## Request delivery
`POST` `{baseUrl}/deliveries`
To create a new delivery booking, provide the following details:
1. **Pick-up Details**\
Include the necessary pick-up information such as address, contact person etc.
2. **Drop-off Details**\
Include drop-off information such as address, contact person etc.
3. **Optional Customer Contact**\
You can specify a customer by including `bookingName` and either:
* **bookingEmail**: The customer's email address.
* **bookingPhone**: The customer's phone number.
> **Note**: If neither field is provided, the delivery will not be associated with a customer.
>
> **`bookingName`** is optional but can be included to specify the customer's name.
4. **Order Type**\
Set the `orderType` to `PROCESSING`. This ensures that the delivery will be handled by your partners.
5. **Optional Partner Assignment**\
You can assign the delivery to a specific partner at the time of booking by using the `assignedPartner` field on the drop object. Provide the partner's ID, which can be obtained from the [**Get Delivery Price Estimate**](/delivery-api/estimates/get-delivery-price.md) request.
6. **Optional custom fields**
You can include any custom fields configured via the dashboard directly within the `pickup` and `drop` objects.
These fields are useful for capturing additional, business-specific information during booking.
For example:\
If you've added custom fields in the dashboard like:
* `pickup_house_number` on the pickup form
* `dropoff_house_number` on the dropoff form
You can include them in your booking via the `pickup` and `drop` objects respectively as shown on the sample payload below.
#### Headers
| Name | Type | Description |
|---|
| app_id* | String | |
| app_secret* | String | |
#### Request Body
| Name | Type | Description |
| ------------------------------------------- | ------ | ---------------------------------- |
| pickup\* | object | Pickup details |
| drops\* | array | Dropoff locations and details |
| orderType\* | string | |
| bookingName | string | specifies the name of the customer |
| bookingPhone | string | specifies phone number of customer |
| bookingEmail | string | specifies email of customer |
**pickup object**
| Field | Description | Data Type | Constraints |
| --------------- | -------------------------------------------------------------------------------------------------------- | --------- | ----------- |
| long | Longitude of specified pickup address | Number | Optional |
| lat | Latitude of specified pickup address | Number | Optional |
| locationCode | Maps to an area, local government, or province connected to the address | String | Optional |
| city | Pickup city | String | Optional |
| state | Pickup state | String | Optional |
| country | Pickup country | String | Optional |
| address2 | Address line 2 | String | Optional |
| address | Pickup address | String | Required |
| pickupName | Pickup name | String | Required |
| pickupEmail | Pickup email | String | Optional |
| pickupNumber | Pickup phone number | String | Required |
| altPickupNumber | Alternative pickup phone number | String | Optional |
| postalCode | Pickup address postal code | String | Optional |
| note | Pickup note | String | Optional |
| pickupDate | The date scheduled for the pickup | String | Optional |
| pickupOtp | Preferred pickup otp to be used. If not specified, a delivery pickup otp will be automatically generated | String | Optional |
#### Drop Object
| Field | Description | Data Type | Constraints |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------- |
| long | Longitude of the drop-off address | Number | Optional |
| lat | Latitude of the drop-off address | Number | Optional |
| locationCode | Maps to a specific area or region connected to the address | String | Optional |
| city | Drop-off city | String | Optional |
| state | Drop-off state | String | Optional |
| country | Drop-off country | String | Default: "NG" |
| address | Drop-off address | String | Required |
| address2 | Address line 2 | String | Optional |
| recipientName | Recipient’s name | String | Required |
| recipientNumber | Recipient’s phone number | String | Required |
| recipientEmail | Recipient’s email address | String | Optional |
| altRecipientNumber | Alternative recipient phone number | String | Optional |
| express | Indicates if express delivery is requested | Boolean | Optional |
| category | Delivery category | String | Optional |
| note | Additional delivery notes | String | Optional |
| value | Value of the item being delivered | Number | Optional |
| description | Description of the item | String | Optional |
| height | Height of the package (cm) | Number | Optional |
| length | Length of the package (cm) | Number | Optional |
| width | Width of the package (cm) | Number | Optional |
| weight | Weight of the package (kg) | Number | Optional |
| assignedPartner | ID of the assigned partner | String | Optional |
| postalCode | Drop-off address postal code | String | Optional |
| categoryId | ID of the delivery category | String | Optional |
| podAmount | Pay on delivery amount | Number | Optional |
| amount | Delivery amount. If provided, it will override the default calculated amount for the delivery | Number | Optional |
| partnerFee | Fee charged by the partner | Number | Optional |
| estimatedPickupWindow | Estimated pickup time window (date and time range).
If provided, it will override the default pickup window for the delivery
| Object | Optional (start, end) |
| estimatedDropoffWindow | Estimated drop-off time window (date and time range). If provided, it will override the default drop-off window for the delivery | Object | Optional (start, end) |
| externalOrderId | External order id | String | Optional |
| dropoffOtp | Preferred dropoff otp to be used. If not specified, a delivery dropoff otp will be automatically generated | String | Optional |
{% tabs %}
{% tab title="200 Request successfully placed" %}
```
{
id: '65fbe637eadabd3da02c3143',
trackingUrl: 'https://app.sendstack.africa/tracking?batchId=R8XB5B',
paymentStatus: 'PAID',
paymentSource: 'self',
batchId: 'R8XB5B',
totalAmount: 1500,
initiator: '65fbe629eadabd3da02c2fab',
pickup: {
address: '1894 Walker Motorway',
pickupName: 'Ramona Rowe',
pickupNumber: '+2349092264624',
pickupDate: '2024-03-22T00:00:00.000Z',
lga: 'Location 1',
state: 'Lagos'
},
drops: [
{
id: '65fbe637eadabd3da02c3141',
fulfillmentPartner: 'Sendstack',
podPaymentStatus: 'PENDING',
status: 'ASSIGNED',
trackingId: 'S1ZZ4U',
trackingUrl: 'https://app.sendstack.africa/tracking?trackingId=S1ZZ4U',
batchId: 'R8XB5B',
address: '2501 Smitham Junctions',
recipientName: 'Melinda King',
recipientNumber: '+2348099793911',
//...truncated for brevity
}
]
}
```
{% endtab %}
{% tab title="400: Bad Request {{field}} is required" %}
```
{
"status": false,
"message": "Invalid app_id or app_secret",
"data": {
"statusCode": 401,
"message": "Invalid app_id or app_secret",
"isOperational": true,
}
}
```
{% endtab %}
{% tab title="422: Unprocessable Entity Low wallet balance" %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
```
// Sample Request information
Url: https://sandbox.sendstack.africa/api/v1/deliveries
method: POST
Headers:
- app_id: "your app_id"
- app_secret: "your app_secret"
```
### Sample Success Data
```json
//Sample Request Body
{
"orderType": "PROCESSING",
"bookingEmail": "test@gmail.com",
"bookingName": "test",
"pickup": {
"address": "928 Lowe Lakes",
"pickupName": "Miss Rudolph Dietrich",
"pickupNumber": "+2348015793998",
"altPickupNumber": "+2348015020200",
"pickupDate": "2024-12-04",
"lat": 6.602928,
"long": 3.345006,
"pickup_house_number": 1 //custom field
},
"drops": [
{
"address": "419 Graham View",
"recipientName": "Robyn Nitzsche DVM",
"recipientNumber": "+2348007384794",
"altRecipientNumber": "+2348002722212",
"lat": 6.602928,
"long": 3.345006,
"estimatedPickupWindow": {
"start": "2024-12-04T06:00:00.00Z",
"end": "2024-12-04T12:00:00.00Z"
},
"estimatedDropoffWindow": {
"start": "2024-12-04T12:00:00.00Z",
"end": "2024-12-04T17:00:00.00Z"
},
"dropoff_house_number": 2 //custom field
}
]
}
```
### Sample Success Data(Pay on Delivery)
```json
//Sample Request Body
{
"orderType": "PROCESSING",
"pickup": {
"address": "928 Lowe Lakes",
"pickupName": "Miss Rudolph Dietrich",
"pickupNumber": "+2348015793998",
"pickupDate": "2024-03-22",
"locationCode": "JJ2M",
},
"drops": [
{
"address": "419 Graham View",
"podAmount": 1000,
"recipientName": "Robyn Nitzsche DVM",
"recipientNumber": "+2348007384794",
"locationCode": "XV4C",
}
]
}
```
### Sample Error Data
```json
// Sample Request Body
{
"orderType": "PROCESSING",
"pickup": {
"pickupName": "Miss Rudolph Dietrich",
"pickupNumber": "+2348015793998",
"pickupDate": "2024-03-22",
"locationCode": "JJ2M",
},
"drops": [
{
"recipientName": "Robyn Nitzsche DVM",
"recipientNumber": "+2348007384794",
"locationCode": "XV4C",
}
]
}
```
```json
// Sample Response Body - 400 Bad Request
{
"status": false,
"message": "\"address\" is required, \"address\" is required"
}
```
A 400 Bad Request is returned for any missing required field.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.sendstackhq.com/delivery-api/bookings/request-delivery.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.