All systems operational

SwiftDash API Reference

Integrate SwiftDash delivery management directly into your platform. Book deliveries, track statuses in real-time, and receive webhook events — all via a simple REST API.

REST API Webhooks HMAC Signatures

Introduction

The SwiftDash API lets you programmatically book deliveries, check status, manage webhooks, and pull vehicle pricing — from any language or platform.

Every request is scoped to your business account. You authenticate using a static x-api-key header. Keys are managed from the API & Webhooks page in your dashboard.

Book a Delivery

POST to /deliveries with pickup & dropoff details.

Get Real-time Status

Poll GET /deliveries/:id or subscribe via webhooks.

Receive Events

Authentication

All requests must include your API key in the x-api-key header. Keys begin with sd_live_.

curl https://swiftdashdms.com/api/v1/vehicles \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE'

⚠️Never expose your API key in client-side code or public repositories. Store it as an environment variable on your server.

Request Headers

Name	Type	Required	Description
`x-api-key`	`string`	Required	Your SwiftDash API key. Must start with sd_live_.
`Content-Type`	`string`	Optional	Required for POST/PATCH requests. Use application/json.

Base URL

All API endpoints are relative to:

Base URLhttps://swiftdashdms.com/api/v1

Requests over plain HTTP will be rejected. All endpoints require HTTPS.

Errors

SwiftDash uses standard HTTP status codes. Error responses always include a JSON body with error and code fields.

// Error response shape
{
  "error": "Missing required fields: pickupAddress, dropoffAddress",
  "code": "MISSING_FIELD"
}

HTTP	Code	Meaning
400	`MISSING_FIELD`	A required parameter is absent from the request body.
400	`INVALID_VEHICLE_TYPE`	The vehicleTypeId does not exist or is inactive.
400	`INVALID_BODY`	Request body could not be parsed as JSON.
400	`INVALID_URL`	Webhook URL is not a valid HTTPS address.
400	`INVALID_EVENT`	An unrecognised webhook event was specified.
401	`INVALID_API_KEY`	The x-api-key header is missing, expired, or revoked.
404	`NOT_FOUND`	The requested resource does not exist in your account.
409	`INVALID_STATUS_TRANSITION`	Cannot cancel a delivery in its current status.
429	`RATE_LIMIT_EXCEEDED`	Too many requests. See Rate Limits section.
500	`—`	Internal server error. Contact support if this persists.

Rate Limits

Requests are rate-limited per API key. When exceeded, the API returns 429 RATE_LIMIT_EXCEEDED. Check the response headers to know your current usage.

Plan	Requests / min	Requests / hour
Starter	60	1,000
Business	300	10,000
Enterprise	Unlimited	Unlimited

Rate Limit Response Headers

Name	Type	Required	Description
`X-RateLimit-Limit`	`integer`	Optional	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	`integer`	Optional	Requests remaining before you are throttled.
`X-RateLimit-Reset`	`unix timestamp`	Optional	Time when the window resets.

List Deliveries

Returns a paginated list of deliveries belonging to your business account.

GET/api/v1/deliveries

Query Parameters

Name	Type	Required	Description
`status`	`string`	Optional	Filter by delivery status (e.g. pending, delivered).
`from`	`ISO 8601`	Optional	Return deliveries created on or after this datetime.
`to`	`ISO 8601`	Optional	Return deliveries created on or before this datetime.
`limit`	`integer`	Optional	Number of results per page. Max 100. Default 20.
`offset`	`integer`	Optional	Number of results to skip for pagination. Default 0.

curl 'https://swiftdashdms.com/api/v1/deliveries?status=pending&limit=10' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE'

Response

{
  "data": [
    {
      "id": "del_abc123",
      "status": "in_transit",
      "pickup_address": "123 Rizal Ave, Manila",
      "delivery_address": "456 Ayala Ave, Makati",
      "total_price": 185.50,
      "payment_method": "cash",
      "payment_status": "pending",
      "created_at": "2026-03-18T08:00:00Z",
      "vehicle_types": { "id": "...", "name": "Motorcycle" }
    }
  ],
  "count": 42,
  "limit": 10,
  "offset": 0
}

Create Delivery

Books a new single-stop delivery. Price is automatically calculated using Mapbox routing + 12% VAT.

POST/api/v1/deliveries

Request Body

Name	Type	Required	Description
`vehicleTypeId`	`uuid`	Required	ID of the vehicle type. Get available IDs from GET /vehicles.
`pickupAddress`	`string`	Required	Full text address of the pickup location.
`pickupLat`	`number`	Required	Pickup latitude in decimal degrees.
`pickupLng`	`number`	Required	Pickup longitude in decimal degrees.
`pickupContactName`	`string`	Required	Name of the person at pickup.
`pickupContactPhone`	`string`	Required	Phone number in Philippine format (09XXXXXXXXX).
`dropoffAddress`	`string`	Required	Full text address of the delivery location.
`dropoffLat`	`number`	Required	Dropoff latitude in decimal degrees.
`dropoffLng`	`number`	Required	Dropoff longitude in decimal degrees.
`dropoffContactName`	`string`	Required	Name of the recipient at dropoff.
`dropoffContactPhone`	`string`	Required	Phone number of the recipient.
`pickupInstructions`	`string`	Optional	Special instructions for the driver at pickup.
`dropoffInstructions`	`string`	Optional	Special instructions for the driver at dropoff.
`packageDescription`	`string`	Optional	What is being delivered.
`packageWeightKg`	`number`	Optional	Package weight in kilograms.
`packageValue`	`number`	Optional	Declared value of the package in PHP.
`distanceKm`	`number`	Optional	Pre-calculated distance. If omitted, Haversine estimation is used.
`paymentMethod`	`string`	Optional	One of: cash, credit_card, maya_wallet, qr_ph. Defaults to cash.
`paymentBy`	`string`	Optional	Who pays: sender or recipient. Defaults to sender.
`paymentStatus`	`string`	Optional	One of: pending, paid. Defaults to pending.

curl -X POST 'https://swiftdashdms.com/api/v1/deliveries' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "vehicleTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pickupAddress": "123 Rizal Ave, Tondo, Manila",
    "pickupLat": 14.6042,
    "pickupLng": 120.9822,
    "pickupContactName": "Juan Dela Cruz",
    "pickupContactPhone": "09171234567",
    "dropoffAddress": "456 Ayala Ave, Makati City",
    "dropoffLat": 14.5547,
    "dropoffLng": 121.0244,
    "dropoffContactName": "Maria Santos",
    "dropoffContactPhone": "09181234567",
    "packageDescription": "Documents",
    "paymentMethod": "cash",
    "paymentBy": "sender"
  }'

Response — 201 Created

{
  "data": {
    "id": "del_abc123",
    "status": "pending",
    "pickup_address": "123 Rizal Ave, Tondo, Manila",
    "delivery_address": "456 Ayala Ave, Makati City",
    "distance_km": 8.2,
    "total_price": 185.50,
    "payment_method": "cash",
    "payment_status": "pending",
    "created_at": "2026-03-18T08:00:00Z"
  },
  "pricing": {
    "base": 49.00,
    "distance": 116.52,
    "subtotal": 115.62,
    "vat": 19.88,
    "total": 185.50
  }
}

ℹ️Pricing uses a Haversine straight-line distance estimate by default. Pass distanceKm if you have a more accurate road distance from your own routing.

Delivery Status Flow

pending→

driver_assigned→

pickup_arrived→

package_collected→

in_transit→

delivered

cancelledfailed— terminal states

Get Delivery

Retrieve full details for a single delivery, including current status and driver assignment.

GET/api/v1/deliveries/:id

curl 'https://swiftdashdms.com/api/v1/deliveries/del_abc123' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE'

Cancel Delivery

Cancels a delivery. Only deliveries with status pending or driver_assigned can be cancelled.

DELETE/api/v1/deliveries/:id

Request Body (optional)

Name	Type	Required	Description
`reason`	`string`	Optional	Human-readable cancellation reason. Defaults to "Cancelled via API".

curl -X DELETE 'https://swiftdashdms.com/api/v1/deliveries/del_abc123' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{ "reason": "Customer changed order" }'

⚠️Cancellations for deliveries past the driver_assigned stage will return 409 INVALID_STATUS_TRANSITION. Contact support for overrides.

List Vehicles

Returns all active vehicle types with their pricing. Use the returned id as vehicleTypeId when creating a delivery.

GET/api/v1/vehicles

curl 'https://swiftdashdms.com/api/v1/vehicles' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE'

Response

{
  "data": [
    {
      "id": "uuid-motorcycle",
      "name": "Motorcycle",
      "description": "Up to 20kg, Size 0.5×0.4×0.5m.",
      "max_weight_kg": 20,
      "base_price": 49.00,
      "price_per_km": 6.00,
      "icon_url": null
    },
    {
      "id": "uuid-sedan",
      "name": "Sedan 200kg",
      "description": "Up to 200kg, Size 1×0.6×0.7m.",
      "max_weight_kg": 200,
      "base_price": 100.00,
      "price_per_km": 18.00,
      "icon_url": null
    }
  ]
}

Register Endpoint

POST/api/v1/webhooks

Request Body

Name	Type	Required	Description
`url`	`string`	Required	Your HTTPS endpoint that will receive POST requests.
`events`	`string[]`	Optional	Array of events to subscribe to. Omit to subscribe to all events.
`description`	`string`	Optional	A human-readable label for this endpoint (e.g. "Production").

Available Events

delivery.createddelivery.driver_assigneddelivery.pickup_arriveddelivery.package_collecteddelivery.in_transitdelivery.delivereddelivery.cancelleddelivery.failed

curl -X POST 'https://swiftdashdms.com/api/v1/webhooks' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://yourapp.com/webhooks/swiftdash",
    "events": ["delivery.created", "delivery.delivered", "delivery.cancelled"],
    "description": "Production"
  }'

List Endpoints

Returns all registered webhook endpoints for your account.

GET/api/v1/webhooks

curl 'https://swiftdashdms.com/api/v1/webhooks' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE'

Update Endpoint

Update the URL, subscribed events, active status, or description of a webhook.

PATCH/api/v1/webhooks/:id

Request Body (all optional)

Name	Type	Required	Description
`url`	`string`	Optional	New destination URL (must be HTTPS).
`events`	`string[]`	Optional	Replace the subscribed events list.
`is_active`	`boolean`	Optional	Set to false to pause delivery without deleting.
`description`	`string`	Optional	Update the label.

curl -X PATCH 'https://swiftdashdms.com/api/v1/webhooks/wh_id' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{ "is_active": false }'

Delete Endpoint

Permanently removes a webhook endpoint. Returns 204 No Content on success.

DELETE/api/v1/webhooks/:id

curl -X DELETE 'https://swiftdashdms.com/api/v1/webhooks/wh_id' \
  -H 'x-api-key: sd_live_YOUR_KEY_HERE'

Verify Signature

SwiftDash signs every webhook POST with an HMAC-SHA256 signature using the secret returned when you registered the endpoint. Always verify this before processing events.

Webhook Request Headers

Name	Type	Required	Description
`x-swiftdash-signature`	`string`	Optional	HMAC-SHA256 of the raw request body, prefixed with sha256=.
`x-swiftdash-event`	`string`	Optional	The event name, e.g. delivery.delivered.
`content-type`	`string`	Optional	Always application/json.

Webhook Payload Shape

{
  "event": "delivery.delivered",
  "timestamp": "2026-03-18T14:30:00Z",
  "delivery_id": "del_abc123",
  "data": {
    "id": "del_abc123",
    "status": "delivered",
    "completed_at": "2026-03-18T14:30:00Z",
    "driver_id": "drv_xyz789",
    "total_price": 185.50
  }
}

import { createHmac, timingSafeEqual } from 'crypto';

export function verifySwiftDashSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string
): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Use timing-safe comparison to prevent timing attacks
  return timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Express.js example
app.post('/webhooks/swiftdash', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-swiftdash-signature'];
  const valid = verifySwiftDashSignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET);

  if (!valid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(req.body.toString());
  console.log('Event received:', event.event, event.delivery_id);

  // Process event...
  res.status(200).send('OK');
});

⚠️Always use a constant-time comparison (timingSafeEqual in Node, hmac.compare_digest in Python, hash_equals in PHP) to prevent timing-based attacks.

SwiftDash API Reference · v1.0 · Updated March 2026

Questions? api-support@swiftdashdms.com