curl -X POST https://api.bodha.run/api/v1/orders \
-H "X-API-Key: bk_live_..." \
-H "Content-Type: application/json" \
-d '{
"externalOrderId": "ORD-2026-1043",
"externalOrderNumber": "#1043",
"recipient": {
"fullName": "Jane Smith",
"phone": "+14155551234"
},
"location": {
"address": "456 Oak Ave, San Francisco, CA 94102",
"latitude": 37.7751,
"longitude": -122.4193
},
"promise": {
"type": "by",
"date": "2026-11-01"
},
"timeWindow": {
"startTime": "09:00",
"endTime": "12:00"
},
"items": [
{ "name": "Widget A", "quantity": 2 }
],
"notes": "Leave at side gate"
}'
const res = await fetch('https://api.bodha.run/api/v1/orders', {
method: 'POST',
headers: {
'X-API-Key': 'bk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
externalOrderId: 'ORD-2026-1043',
recipient: { fullName: 'Jane Smith' },
location: {
address: '456 Oak Ave, San Francisco, CA 94102',
latitude: 37.7751,
longitude: -122.4193,
},
}),
});
const { data } = await res.json();
{
"data": {
"id": "665f1a2b3c4d5e6f7a8b9c0f",
"source": "api",
"externalOrderId": "ORD-2026-1043",
"externalOrderNumber": "#1043",
"status": "ready",
"recipient": {
"fullName": "Jane Smith",
"phone": "+14155551234"
},
"location": {
"address": "456 Oak Ave, San Francisco, CA 94102",
"latitude": 37.7751,
"longitude": -122.4193
},
"promise": { "type": "by", "date": "2026-11-01" },
"priority": "normal",
"items": [{ "name": "Widget A", "quantity": 2 }],
"tags": [],
"customProperties": {},
"routeId": null,
"stopId": null,
"createdAt": "2026-10-28T10:30:00.000Z",
"updatedAt": "2026-10-28T10:30:00.000Z"
}
}
Orders
Create Order
Push a new order into the Bodha inbox.
POST
/
orders
curl -X POST https://api.bodha.run/api/v1/orders \
-H "X-API-Key: bk_live_..." \
-H "Content-Type: application/json" \
-d '{
"externalOrderId": "ORD-2026-1043",
"externalOrderNumber": "#1043",
"recipient": {
"fullName": "Jane Smith",
"phone": "+14155551234"
},
"location": {
"address": "456 Oak Ave, San Francisco, CA 94102",
"latitude": 37.7751,
"longitude": -122.4193
},
"promise": {
"type": "by",
"date": "2026-11-01"
},
"timeWindow": {
"startTime": "09:00",
"endTime": "12:00"
},
"items": [
{ "name": "Widget A", "quantity": 2 }
],
"notes": "Leave at side gate"
}'
const res = await fetch('https://api.bodha.run/api/v1/orders', {
method: 'POST',
headers: {
'X-API-Key': 'bk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
externalOrderId: 'ORD-2026-1043',
recipient: { fullName: 'Jane Smith' },
location: {
address: '456 Oak Ave, San Francisco, CA 94102',
latitude: 37.7751,
longitude: -122.4193,
},
}),
});
const { data } = await res.json();
{
"data": {
"id": "665f1a2b3c4d5e6f7a8b9c0f",
"source": "api",
"externalOrderId": "ORD-2026-1043",
"externalOrderNumber": "#1043",
"status": "ready",
"recipient": {
"fullName": "Jane Smith",
"phone": "+14155551234"
},
"location": {
"address": "456 Oak Ave, San Francisco, CA 94102",
"latitude": 37.7751,
"longitude": -122.4193
},
"promise": { "type": "by", "date": "2026-11-01" },
"priority": "normal",
"items": [{ "name": "Widget A", "quantity": 2 }],
"tags": [],
"customProperties": {},
"routeId": null,
"stopId": null,
"createdAt": "2026-10-28T10:30:00.000Z",
"updatedAt": "2026-10-28T10:30:00.000Z"
}
}
Create an order that enters your Bodha orders inbox. If coordinates are
provided, it’s marked
ready for planning. Otherwise it enters needs_review
for manual geocoding in the dashboard.
This endpoint fires the order.created webhook event.
Required fields
object
required
Optional fields
string
Your system’s unique order ID. Used as an idempotency key — sending the same
ID twice returns a
409 Conflict.string
Human-facing order number shown to dispatchers (e.g.
"#1043").object
Delivery promise to the customer.
string
default:"normal"
normal or urgent.number
Monetary value of the order.
string
ISO 4217 currency code (e.g.
USD, GBP).string
string
Shown to the driver at the stop.
string[]
object
Arbitrary key-value pairs passed through to the stop.
curl -X POST https://api.bodha.run/api/v1/orders \
-H "X-API-Key: bk_live_..." \
-H "Content-Type: application/json" \
-d '{
"externalOrderId": "ORD-2026-1043",
"externalOrderNumber": "#1043",
"recipient": {
"fullName": "Jane Smith",
"phone": "+14155551234"
},
"location": {
"address": "456 Oak Ave, San Francisco, CA 94102",
"latitude": 37.7751,
"longitude": -122.4193
},
"promise": {
"type": "by",
"date": "2026-11-01"
},
"timeWindow": {
"startTime": "09:00",
"endTime": "12:00"
},
"items": [
{ "name": "Widget A", "quantity": 2 }
],
"notes": "Leave at side gate"
}'
const res = await fetch('https://api.bodha.run/api/v1/orders', {
method: 'POST',
headers: {
'X-API-Key': 'bk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
externalOrderId: 'ORD-2026-1043',
recipient: { fullName: 'Jane Smith' },
location: {
address: '456 Oak Ave, San Francisco, CA 94102',
latitude: 37.7751,
longitude: -122.4193,
},
}),
});
const { data } = await res.json();
{
"data": {
"id": "665f1a2b3c4d5e6f7a8b9c0f",
"source": "api",
"externalOrderId": "ORD-2026-1043",
"externalOrderNumber": "#1043",
"status": "ready",
"recipient": {
"fullName": "Jane Smith",
"phone": "+14155551234"
},
"location": {
"address": "456 Oak Ave, San Francisco, CA 94102",
"latitude": 37.7751,
"longitude": -122.4193
},
"promise": { "type": "by", "date": "2026-11-01" },
"priority": "normal",
"items": [{ "name": "Widget A", "quantity": 2 }],
"tags": [],
"customProperties": {},
"routeId": null,
"stopId": null,
"createdAt": "2026-10-28T10:30:00.000Z",
"updatedAt": "2026-10-28T10:30:00.000Z"
}
}