# Business Delivery ## Create a delivery request > Create a new delivery. If a callback URL was provided, delivery status updates will be sent to that URL.\ > See \[CallbackDeliveryPayload]\(#components-schemas-CallbackDeliveryPayload) for the structure of the data sent.
```json {"openapi":"3.0.0","info":{"title":"Swoove","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://test.swooveapi.com"},{"description":"Production","url":"https://live.swooveapi.com"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"app_key"}},"requestBodies":{"Deliveries":{"required":true,"description":"Delivery Request Body Sample And Schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delivery"}}}}},"schemas":{"Delivery":{"allOf":[{"$ref":"#/components/schemas/Estimate"},{"type":"object","description":"Delivery Request Structure","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"instructions":{"type":"string","default":null,"description":"Any extra notes rider should be mindful of for the delivery."},"reference":{"type":"string","description":"Can be set to the id of some data in your system that needs to know about this delivery."},"estimate_id":{"type":"string","description":"The estimate id of the selected estimate that was returned during the create delivery estimate request"}},"required":["estimate_id","contact","reference"]}]},"Estimate":{"type":"object","description":"Delivery Estimate Request Structure","properties":{"pickup":{"$ref":"#/components/schemas/Location"},"dropoff":{"$ref":"#/components/schemas/Location"},"items":{"description":"Item(s) to be delivered","type":"array","default":[],"items":{"$ref":"#/components/schemas/Item"}},"vehicle_type":{"type":"string","deprecated":true,"description":"Type of vehicle wanted for the delivery\n\n * `MOTORCYCLE` - Normal last-mile bikes\n","default":"MOTORCYCLE"}},"required":["pickup","dropoff","contact","reference"]},"Location":{"description":"Location object for pickup or dropoff in a delivery or estimate request","type":"object","properties":{"type":{"type":"string","description":"Values:\n * `LATLNG` - Longitude and latitude values. Submitted as lat and lng in DeliveryLocation object\n * `GHPOST` - Ghana Post GPS value. Submitted in value key in DeliveryLocation object\n * `WHATTW` - What3Words value, Submitted in value key in DeliveryLocation object"},"value":{"type":"string","description":"Holds the value for either GHPOST or WHATTW"},"contact":{"$ref":"#/components/schemas/Contact"},"country_code":{"type":"string","description":"Iso Alpha-2 code for the delivery location country. Visit [country code ](https://www.iban.com/country-codes) for more reference","default":"GH"},"lat":{"type":"number","description":"Latitude value for delviery location if type is LATLNG","default":null},"lng":{"type":"number","description":"Longitude value for delviery location if type is LATLNG","default":null},"location":{"type":"string","description":"Human readable location of a delivery (address)","default":null}},"required":["type","contact","country_code"]},"Contact":{"description":"Contact person for the delivery location","type":"object","properties":{"name":{"type":"string","description":"Contact Person's Name","default":null},"mobile":{"type":"string","description":"Contact Person's Mobile Number"},"email":{"type":"string","description":"Contact Person's Email","default":null}},"required":["mobile"]},"Item":{"type":"object","description":"Object Structure for item in items array","properties":{"itemName":{"type":"string","description":"Name of item being shipped"},"itemQuantity":{"type":"number","description":"Quantity of the item being shipped"},"itemCost":{"type":"number","description":"Cost of the item being shipped"},"description":{"type":"string","default":null,"description":"A short description of the item"},"itemImages":{"type":"array","items":{"type":"string","description":"valid image url"}},"itemWeight":{"type":"number","description":"Package Weight","default":null},"is_fragile":{"type":"boolean","default":false},"dimensions":{"type":"object","description":"Dimensions of the item. Default to null","default":null,"properties":{"x":{"type":"number","description":"Length of the item"},"y":{"type":"number","description":"Width of the item"},"z":{"type":"number","description":"Height of the item"}},"required":["x","y","z"]}},"required":["itemName","itemCost","itemQuantity","itemWeight"]},"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean","default":true,"description":"status of request true for success and false for failed request"},"code":{"type":"integer","format":"int32","default":200,"description":"code for reason for failure"},"message":{"type":"string","default":"Estimate completed"}}},"Price":{"type":"object","properties":{"discount":{"type":"number","default":0},"value":{"type":"number","default":0},"currency_code":{"type":"string","default":"GHS","description":"Country Currency Code"},"currency_symbol":{"type":"string","default":"₵","description":"Country Currency Symbol"},"currency_name":{"type":"string","default":"Ghanaian cedi","description":"Country Currency Name"}},"required":["discount","value","currency_code","currency_name","currency_symbol"]},"ApiError400":{"type":"object","properties":{"success":{"type":"boolean","default":false,"description":"status of request true for success and false for failed request"},"code":{"type":"integer","format":"int32","default":400,"description":"Data validation error code"},"message":{"type":"string","default":"A certain field was expected but was null or invalid"},"responses":{"type":"string","nullable":true,"default":null}}}}},"paths":{"/delivery/create-delivery":{"post":{"tags":["Business - Delivery"],"summary":"Create a delivery request","description":"Create a new delivery. If a callback URL was provided, delivery status updates will be sent to that URL.\nSee [CallbackDeliveryPayload](#components-schemas-CallbackDeliveryPayload) for the structure of the data sent.\n","parameters":[{"name":"app_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/Deliveries"},"responses":{"200":{"description":"Success Responses On Delivery Creation Request","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"responses":{"allOf":[{"$ref":"#/components/schemas/Delivery"},{"type":"object","properties":{"time":{"type":"number","deprecated":true},"distance":{"type":"number","deprecated":true},"estimate_id":{"type":"string","deprecated":true},"delivery_type":{"type":"string","deprecated":true,"default":"SHARED"},"status":{"type":"string","default":"AGENCY_ASSIGNED","description":"- PENDING - The initial state of a delivery after creation \n- GROUPED - The delivery has been added to a group/trip \n- AGENCY_ASSIGNED - The delivery has been assigned to an agency \n- ASSIGNED - The delivery has been assigned to a rider \n- ONHOLD - The delivery is on hold due to low funds or some other reason \n- PICKUP - The rider is on the way to pick up the items \n- PICKEDUP - The rider has picked up the items \n- DROPOFF - The rider is on the way to drop off the items \n- DROPEDOFF - The rider has dropped off the items \n- ENDED - The delivery is commpleted \n- CANCELLED - The delivery has been cancelled \n- DELIVERY_PAID_FOR - The delivery has been paid for\n","enum":["PENDING","CANCELLED","GROUPED","AGENCY_ASSIGNED","ASSIGNED","ONHOLD","PICKUP","PICKEDUP","DROPOFF","DROPEDOFF","ENDED","DELIVERY_PAID_FOR"]},"delivery_code":{"type":"string"},"secret_code":{"type":"string","description":"The secret code that will allow a delivery to be ended. This must be shared with the drop off content as it will be required to recieve the package from the rirder"},"timestamp":{"type":"number"},"full_price":{"$ref":"#/components/schemas/Price"}},"required":["secret_code","delivery_code","full_price","status"]}]}}}]}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError400"},{"type":"object"}]}}}},"500":{"description":"Requesting Delivery Failed"}}}}}} ``` ## POST /bulk-delivery/create-bulk-delivery > Create Bulk Delivery Request ```json {"openapi":"3.0.0","info":{"title":"Swoove","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://test.swooveapi.com"},{"description":"Production","url":"https://live.swooveapi.com"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"app_key"}},"requestBodies":{"BulkDeliveries":{"required":true,"description":"Bulk Delivery Request Body Sample and Schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDelivery"}}}}},"schemas":{"BulkDelivery":{"description":"Bulk Delivery Request Structure","type":"object","properties":{"delivery_list":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Estimate"},{"type":"object","properties":{"contacts":{"$ref":"#/components/schemas/Contact"},"instructions":{"type":"string","default":null,"description":"Any extra notes rider should be mindful of for the delivery."},"reference":{"type":"string","description":"Can be set to the id of some data in your system that needs to know about this delivery."}}}]}},"estimate_id":{"type":"string","description":"The estimate id of the selected estimate that was returned during the create delivery estimate request"},"individual_pricing_id":{"type":"string","description":"This is an optional paramater to create a delviery for only one individual pricing that is returned in a bulk estimate. Note that creating one will require all others to be created individually"}},"required":["delivery_list","estimate_id"]},"Estimate":{"type":"object","description":"Delivery Estimate Request Structure","properties":{"pickup":{"$ref":"#/components/schemas/Location"},"dropoff":{"$ref":"#/components/schemas/Location"},"items":{"description":"Item(s) to be delivered","type":"array","default":[],"items":{"$ref":"#/components/schemas/Item"}},"vehicle_type":{"type":"string","deprecated":true,"description":"Type of vehicle wanted for the delivery\n\n * `MOTORCYCLE` - Normal last-mile bikes\n","default":"MOTORCYCLE"}},"required":["pickup","dropoff","contact","reference"]},"Location":{"description":"Location object for pickup or dropoff in a delivery or estimate request","type":"object","properties":{"type":{"type":"string","description":"Values:\n * `LATLNG` - Longitude and latitude values. Submitted as lat and lng in DeliveryLocation object\n * `GHPOST` - Ghana Post GPS value. Submitted in value key in DeliveryLocation object\n * `WHATTW` - What3Words value, Submitted in value key in DeliveryLocation object"},"value":{"type":"string","description":"Holds the value for either GHPOST or WHATTW"},"contact":{"$ref":"#/components/schemas/Contact"},"country_code":{"type":"string","description":"Iso Alpha-2 code for the delivery location country. Visit [country code ](https://www.iban.com/country-codes) for more reference","default":"GH"},"lat":{"type":"number","description":"Latitude value for delviery location if type is LATLNG","default":null},"lng":{"type":"number","description":"Longitude value for delviery location if type is LATLNG","default":null},"location":{"type":"string","description":"Human readable location of a delivery (address)","default":null}},"required":["type","contact","country_code"]},"Contact":{"description":"Contact person for the delivery location","type":"object","properties":{"name":{"type":"string","description":"Contact Person's Name","default":null},"mobile":{"type":"string","description":"Contact Person's Mobile Number"},"email":{"type":"string","description":"Contact Person's Email","default":null}},"required":["mobile"]},"Item":{"type":"object","description":"Object Structure for item in items array","properties":{"itemName":{"type":"string","description":"Name of item being shipped"},"itemQuantity":{"type":"number","description":"Quantity of the item being shipped"},"itemCost":{"type":"number","description":"Cost of the item being shipped"},"description":{"type":"string","default":null,"description":"A short description of the item"},"itemImages":{"type":"array","items":{"type":"string","description":"valid image url"}},"itemWeight":{"type":"number","description":"Package Weight","default":null},"is_fragile":{"type":"boolean","default":false},"dimensions":{"type":"object","description":"Dimensions of the item. Default to null","default":null,"properties":{"x":{"type":"number","description":"Length of the item"},"y":{"type":"number","description":"Width of the item"},"z":{"type":"number","description":"Height of the item"}},"required":["x","y","z"]}},"required":["itemName","itemCost","itemQuantity","itemWeight"]},"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean","default":true,"description":"status of request true for success and false for failed request"},"code":{"type":"integer","format":"int32","default":200,"description":"code for reason for failure"},"message":{"type":"string","default":"Estimate completed"}}},"BulkDeliveryResponses":{"type":"array","description":"Bulk Delivery(s) Details","minItems":1,"items":{"allOf":[{"$ref":"#/components/schemas/Estimate"},{"type":"object","properties":{"contacts":{"$ref":"#/components/schemas/Contact"},"time":{"type":"number","deprecated":true},"distance":{"type":"number","deprecated":true},"delivery_type":{"type":"string","deprecated":true,"default":"SHARED"},"status":{"type":"string","description":"- PENDING - The initial state of a delivery after creation \n- GROUPED - The delivery has been added to a group/trip \n- AGENCY_ASSIGNED - The delivery has been assigned to an agency \n- ASSIGNED - The delivery has been assigned to a rider \n- ONHOLD - The delivery is on hold due to low funds or some other reason \n- PICKUP - The rider is on the way to pick up the items \n- PICKEDUP - The rider has picked up the items \n- DROPOFF - The rider is on the way to drop off the items \n- DROPEDOFF - The rider has dropped off the items \n- ENDED - The delivery is completed \n- CANCELLED - The delivery has been cancelled \n- DELIVERY_PAID_FOR - Payment has been successfully made for the delivery (applies only on webhook updates)\n","enum":["PENDING","CANCELLED","GROUPED","AGENCY_ASSIGNED","ASSIGNED","ONHOLD","PICKUP","PICKEDUP","DROPOFF","DROPEDOFF","ENDED","DELIVERY_PAID_FOR"]},"delivery_code":{"type":"string"},"secret_code":{"type":"string","description":"Delivery Secret Code. This is shared with the customer and given to the rider to comfirm dropoff"},"instructions":{"type":"string"},"reference":{"type":"string"},"full_price":{"$ref":"#/components/schemas/Price"},"bulk_id":{"type":"string","description":"Unique id for all deliveries in a bulk delivery request","deprecated":true},"waybill_link":{"type":"string","description":"A waybill url added on the delivery object sent to your callback url"},"tracking_link":{"type":"string","description":"Delivery tracking url added to the delivery object sent to your callback url"},"time_completed":{"type":"number","description":"The time a delivery was completed in milliseconds"}},"required":["contacts","status","delivery_code","secret_code","reference","full_price","bulk_id"]}]}},"Price":{"type":"object","properties":{"discount":{"type":"number","default":0},"value":{"type":"number","default":0},"currency_code":{"type":"string","default":"GHS","description":"Country Currency Code"},"currency_symbol":{"type":"string","default":"₵","description":"Country Currency Symbol"},"currency_name":{"type":"string","default":"Ghanaian cedi","description":"Country Currency Name"}},"required":["discount","value","currency_code","currency_name","currency_symbol"]},"ApiError400":{"type":"object","properties":{"success":{"type":"boolean","default":false,"description":"status of request true for success and false for failed request"},"code":{"type":"integer","format":"int32","default":400,"description":"Data validation error code"},"message":{"type":"string","default":"A certain field was expected but was null or invalid"},"responses":{"type":"string","nullable":true,"default":null}}}}},"paths":{"/bulk-delivery/create-bulk-delivery":{"post":{"tags":["Business - Delivery"],"summary":"Create Bulk Delivery Request","parameters":[{"name":"app_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/BulkDeliveries"},"responses":{"200":{"description":"Bulk Delivery Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"responses":{"$ref":"#/components/schemas/BulkDeliveryResponses"}}}]}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError400"},{"type":"object"}]}}}},"500":{"description":"Getting Estimates Failed"}}}}}} ```