API Documentation

v1.0.0 — Bizilot Shipment

Overview

A headless delivery platform for businesses to dispatch and track shipments using independent drivers.

Base URL: /api/v1

Endpoints

POST/api/v1/api-clients

Register API Client

Register your external system to receive an API key.

Auth: None

Request Payload

{
  "name": "string (required)",
  "contactMobile": "string (required)",
  "webhookUrl": "string (optional)"
}

Response

{
  "success": "boolean",
  "data": {
    "clientId": "string",
    "apiKey": "string (Plaintext - shown only once)",
    "accountId": "string"
  }
}
POST/api/v1/shipments

Create Delivery Shipment

Submit a new shipment to the platform. A driver will be assigned automatically.

Auth: Bearer API Key

Request Payload

{
  "pickup": "Pickup object (required)",
  "drops": "Array of Drop objects (required)"
}

Response

{
  "success": "boolean",
  "data": {
    "shipmentId": "string",
    "trackingNumber": "string",
    "status": "string",
    "dropsCount": "number",
    "createdAt": "string (ISO 8601)"
  }
}
GET/api/v1/shipments

List Shipments

Retrieve all shipments created by your API Client.

Auth: Bearer API Key

Response

{
  "success": "boolean",
  "data": {
    "shipments": "Array of Shipment objects",
    "total": "number"
  }
}
GET/api/v1/shipments/:shipmentId/status

Check Shipment Status

Lightweight polling endpoint to get the current status of a specific shipment.

Auth: Bearer API Key

Response

{
  "success": "boolean",
  "data": {
    "shipmentId": "string",
    "trackingNumber": "string",
    "status": "string",
    "driver": {
      "name": "string",
      "vehicleNumber": "string"
    },
    "updatedAt": "string (ISO 8601)"
  }
}
PUT/api/v1/webhooks

Configure Webhooks

Update webhook URL and subscribed events.

Auth: Bearer API Key

Request Payload

{
  "webhookUrl": "string (required)",
  "events": "Array of strings (e.g. [\"shipment.accepted\", \"shipment.completed\"])"
}

Response

{
  "success": "boolean",
  "data": {
    "webhookUrl": "string",
    "events": "Array of strings"
  }
}

Webhook Events

shipment.createdFired when a new shipment is successfully created in the system.
{
  "shipmentId": "string",
  "trackingNumber": "string",
  "createdAt": "string (ISO)"
}
shipment.acceptedFired when a driver accepts the shipment assignment.
{
  "shipmentId": "string",
  "trackingNumber": "string",
  "driver": {
    "name": "string",
    "vehicleNumber": "string"
  }
}
shipment.picked_upFired when the driver confirms pickup of the goods.
{
  "shipmentId": "string",
  "trackingNumber": "string"
}
shipment.out_for_deliveryFired when the driver is en route to the first drop location.
{
  "shipmentId": "string",
  "trackingNumber": "string"
}
shipment.completedFired when all drops have been successfully completed.
{
  "shipmentId": "string",
  "trackingNumber": "string",
  "completedAt": "string (ISO)"
}

Ready to integrate?

Try it out in the API Playground — no setup required.

Open PlaygroundAI Context