Create a delivery

curl -X POST 'https://business.kiloapp.org/api/v1/deliveries' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_live_...'

curl -X POST 'https://business.kiloapp.org/api/v1/deliveries' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_live_...'

const response = await fetch("https://business.kiloapp.org/api/v1/deliveries", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk_live_..."
  },
});

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

const response = await fetch("https://business.kiloapp.org/api/v1/deliveries", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk_live_..."
  },
});

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

import requests

url = "https://business.kiloapp.org/api/v1/deliveries"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk_live_..."
}

response = requests.request("POST", url, headers=headers)
print(response.json())

import requests

url = "https://business.kiloapp.org/api/v1/deliveries"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk_live_..."
}

response = requests.request("POST", url, headers=headers)
print(response.json())

<?php
$ch = curl_init("https://business.kiloapp.org/api/v1/deliveries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json",
  "Authorization: Bearer sk_live_...",
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

<?php
$ch = curl_init("https://business.kiloapp.org/api/v1/deliveries");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json",
  "Authorization: Bearer sk_live_...",
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Before you call

Call Capabilities & locations so you know which services, warehouses, payments, and service locations this org actually offers.
For chat / AI bookings: ensure service locations (and warehouses) exist in the dashboard so the bot can peep coordinates instead of guessing — see Capabilities & locations.
Delivery services must be enabled in dashboard settings (API create rejects disabled serviceKind).
Add allowed image hosts under API & Webhooks.
Package photos must be https:// URLs on those hosts. Kilo downloads them and stores them. Private IPs are blocked.

Minimal pickup_delivery example

JSON

{
  "serviceKind": "pickup_delivery",
  "deliveryMode": "pickup",
  "senderName": "Ada Lovelace",
  "senderPhone": "+2348012345678",
  "senderEmail": "ada@example.com",
  "pickupContactSameAsSender": true,
  "receiverName": "Grace Hopper",
  "receiverPhone": "+2348098765432",
  "pickupAddress": "12 Admiralty Way, Lekki",
  "pickupCoords": { "lng": 3.4721, "lat": 6.4474 },
  "deliveryAddress": "Victoria Island Office",
  "deliveryCoords": { "lng": 3.4219, "lat": 6.4281 },
  "packageDescription": "Documents envelope",
  "packageSize": "small",
  "packageImages": [
    "https://cdn.yourbot.com/jobs/abc/package-1.jpg"
  ],
  "customerCollectionMethod": "cash_on_delivery"
}

{
  "serviceKind": "pickup_delivery",
  "deliveryMode": "pickup",
  "senderName": "Ada Lovelace",
  "senderPhone": "+2348012345678",
  "senderEmail": "ada@example.com",
  "pickupContactSameAsSender": true,
  "receiverName": "Grace Hopper",
  "receiverPhone": "+2348098765432",
  "pickupAddress": "12 Admiralty Way, Lekki",
  "pickupCoords": { "lng": 3.4721, "lat": 6.4474 },
  "deliveryAddress": "Victoria Island Office",
  "deliveryCoords": { "lng": 3.4219, "lat": 6.4281 },
  "packageDescription": "Documents envelope",
  "packageSize": "small",
  "packageImages": [
    "https://cdn.yourbot.com/jobs/abc/package-1.jpg"
  ],
  "customerCollectionMethod": "cash_on_delivery"
}

Important fields (plain English)

Field	Meaning
`serviceKind`	`pickup_delivery` or `errand`
`deliveryMode`	`pickup` (rider goes to an address) or `warehouse` (needs `warehouseId`)
`pickupCoords` / `deliveryCoords`	Map coordinates — required for routing. Prefer copying from a service location’s `coords` or a warehouse’s lat/lng (bots rarely know pins)
`packageImages`	0–6 HTTPS image URLs from allowlisted hosts. Required (min 1) for `pickup_delivery` and for `errand` when `errandMode` is `photo` (reference photos). Optional for `at_place` / `link` errands
`customerCollectionMethod`	`cash_on_delivery` or `online_checkout` (must be allowed in your settings)
`isPODEnabled` + `podAmount`	Cash to collect from the receiver (only if enabled for your fleet)

What you get back

JSON

{
  "ok": true,
  "delivery": {
    "id": "uuid",
    "status": "pending",
    "access_code": "ABC123",
    "request_source": "api",
    "tracking": {
      "url": "https://track.kiloapp.org/track/uuid/ABC123",
      "path": "/track/uuid/ABC123",
      "access_code": "ABC123"
    },
    "rider_assigned": false
  }
}

{
  "ok": true,
  "delivery": {
    "id": "uuid",
    "status": "pending",
    "access_code": "ABC123",
    "request_source": "api",
    "tracking": {
      "url": "https://track.kiloapp.org/track/uuid/ABC123",
      "path": "/track/uuid/ABC123",
      "access_code": "ABC123"
    },
    "rider_assigned": false
  }
}

Field	Plain English
`id`	Save this. Use it for get / cancel / matching webhooks.
`access_code`	Secret code baked into the tracking link.
`tracking.url`	Full link to share with the customer (live map + OTP page).
`tracking.path`	Same page as a path only (if you build your own host).
`rider_assigned`	`true` if Auto-dispatch already matched a rider (status will often be `matched`).

If Customer delivery messages are on, Kilo may also text the tracking link. If they are off, you should paste tracking.url into your WhatsApp/SMS reply.

Need the exact payload now?

Request fields: API reference → POST /deliveries
Success response: API reference → POST /deliveries → Success 201
Shared delivery object: API reference → Delivery object
Error shape: API reference → Error envelope

Common errors

code / message	Fix
Image host not allowlisted	Add the CDN hostname in Settings → API & Webhooks
Service kind disabled	Enable the service in Delivery settings
Coverage / location blocked	Job is outside your configured coverage
Validation failed	Read `fieldErrors` — a required field is missing
`rate_limited` (429)	Wait `Retry-After` seconds; see Rate limits

Typed responses: API reference
Listen for delivery.created on your webhook.
Assign a rider yourself: Assign riders.

Before you call

Minimal pickup_delivery example

Important fields (plain English)

What you get back

Common errors

Next