Simba Courier — Partner API Documentation

Introduction

#introduction

This API allows external partners to integrate with Simba Courier's logistics platform. When a customer places an order, the partner creates a pickup request via this API. Simba Courier then handles the physical pickup and delivery. The partner can track shipment status in real time using the tracking endpoints.

Responsibility split: The partner handles customer-facing notifications and order management. Simba handles all physical logistics. The partner_reference field is the shared key that links partner orders to Simba shipments across both systems.

Base URL

#base-url

Base URL https://api.simbacourier.co.tz/api/v1/partner

All endpoints are prefixed with /api/v1/partner. All requests and responses use JSON. Always include Accept: application/json in every request header.

Authentication

#authentication

All API requests must include a Bearer token in the Authorization header. This token is issued by Simba and tied to your partner account. Keep it secret — treat it like a password.

Authorization: Bearer <YOUR_API_TOKEN>

Accept: application/json

Content-Type: application/json

Your API token is bound to your partner client account. All requests are automatically scoped to your pickup points and shipments. You cannot access data from other clients.

Integration Flow

#flow

Step 1 Customer places
an order

Step 2 Partner calls
Create Pickup Request

Step 3 Simba assigns driver
and collects parcel

Step 4 Simba updates
shipment status

Step 5 Partner polls
tracking endpoints

Pickup Points

#pickup-points

GET /pickup-points List all active pickup points

Returns all active pickup points linked to your partner account. Use this to retrieve valid pickup_point_id values before creating a pickup request. Pickup points represent seller or collection locations where Simba drivers will collect parcels.

Response Fields

Field	Type	Description
id	integer	Unique ID — use this as `pickup_point_id` when creating a request
name	string	Display name of the pickup location
code	string	Internal short code for the pickup point
city	string	City where the pickup point is located
region	string	Region of the pickup point
latitude	decimal	GPS latitude, nullable
longitude	decimal	GPS longitude, nullable
is_default	boolean	Whether this is the default pickup point for your account

                                JSON Response
                                
                            
{
  "success": true,
  "data": {
    "pickup_points": [
      {
        "id":         20,
        "name":       "MSASANI BRANCH",
        "code":       "MSASANI_001",
        "city":       "Msasani",
        "region":     "Dar es Salaam",
        "latitude":   null,
        "longitude":  null,
        "is_default": true
      }
    ],
    "total": 1
  }
}
{
  "success": false,
  "message": "Invalid or inactive API token."
}

Pickup Requests

#pickup-requests

POST /pickup-requests Create a new pickup request

Creates a pickup request when a customer completes an order. Simba will assign a driver to collect the parcel from the specified pickup point on the requested date. The partner_reference must be your own order ID — this is used to reconcile Simba shipments back to your orders.

Request Body

Field	Type	Required	Description
partner_reference	string	Required	Your own order ID e.g. `ORD-00123`. Used to link Simba shipments to your orders.
pickup_point_id	integer	Required	ID from the List Pickup Points endpoint. Must belong to your account.
contact_name	string	Required	Name of the seller or contact person at the pickup location.
contact_phone	string	Required	Phone number of the contact at the pickup point.
requested_date	date	Required	Requested pickup date. Format: `YYYY-MM-DD`. Must be today or a future date.
receiver_name	string	Required	Full name of the end customer receiving the parcel.
receiver_phone	string	Required	Phone number of the end customer.
receiver_address	string	Required	Full delivery address of the customer.
receiver_region	string	Optional	Delivery region. Helps Simba route the shipment correctly.
time_slot	string	Optional	Preferred pickup time window e.g. `09:00-12:00`.
notes	string	Optional	Special handling instructions for the driver. Max 1000 characters.

Example Request

JSON

{
  "partner_reference": "ORD-00123",
  "pickup_point_id":   20,
  "contact_name":      "John Mwamba",
  "contact_phone":     "0712345678",
  "requested_date":    "2026-06-20",
  "time_slot":         "09:00-12:00",
  "receiver_name":     "Mary Kimani",
  "receiver_phone":    "0756789012",
  "receiver_address":  "123 Uhuru Street, Mwanza",
  "receiver_region":   "Mwanza",
  "notes":             "Fragile items, handle with care"
}

                                JSON Response
                                
                            
{
  "success":  true,
  "message":  "Pickup request created.",
  "data": {
    "id":                2930,
    "status":           "pending",
    "partner_reference": "ORD-00123",
    "requested_date":   "2026-06-20",
    "created_at":       "2026-06-08T14:00:00.000000Z"
  }
}
{
  "message": "The selected pickup point id is invalid.",
  "errors": {
    "pickup_point_id": [
      "The selected pickup point id is invalid."
    ]
  }
}
{
  "success": false,
  "message": "Invalid or inactive API token."
}

GET /pickup-requests List all pickup requests

Returns all pickup requests created by your partner account through this API. Only requests with a partner_reference are returned — requests created manually by Simba staff are excluded.

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	Filter by status: `pending`, `assigned`, `picked`, `handed_over`, `cancelled`
per_page	integer	Optional	Results per page. Default: 20. Max: 100.

JSON — 200 OK

{
  "success": true,
  "data": {
    "pickup_requests": [
      {
        "id":                   2930,
        "partner_reference":    "ORD-00123",
        "status":               "pending",
        "contact_name":         "John Mwamba",
        "contact_phone":        "0712345678",
        "receiver_name":        "Mary Kimani",
        "receiver_phone":       "0756789012",
        "receiver_address":     "123 Uhuru Street, Mwanza",
        "receiver_region":      "Mwanza",
        "pickup_point": {
          "id":     20,
          "name":   "MSASANI BRANCH",
          "city":   "Msasani",
          "region": "Dar es Salaam"
        },
        "requested_date":       "2026-06-20",
        "time_slot":            "09:00-12:00",
        "special_instructions": "Fragile items",
        "items_count":          0,
        "created_at":           "2026-06-08T14:00:00.000000Z"
      }
    ],
    "pagination": {
      "total": 1, "per_page": 20,
      "current_page": 1, "last_page": 1
    }
  }
}

Shipments

#shipments

One pickup request can result in multiple shipments if the order contains multiple items. Always use partner_reference to reconcile shipments back to your orders. Shipments only appear after Simba verifies the pickup and processes them through the warehouse.

GET /shipments List all shipments for your account

Returns all shipments that originated from pickup requests created through this API. Shipments created manually by Simba staff are excluded.

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	Filter by shipment status. See Shipment Statuses reference section.
per_page	integer	Optional	Results per page. Default: 20. Max: 100.

JSON — 200 OK

{
  "success": true,
  "data": {
    "shipments": [
      {
        "waybill_number":     "WAYBILL ID 090873",
        "partner_reference":  "ORD-00123",
        "status":             "in_warehouse",
        "status_label":       "At Warehouse",
        "receiver_name":      "Mary Kimani",
        "receiver_phone":     "0756789012",
        "receiver_region":    "Mwanza",
        "origin_branch":      "DAR ES SALAAM",
        "destination_branch": "MWANZA",
        "current_branch":     "DAR ES SALAAM",
        "created_at":         "2026-06-08T14:23:34.000000Z",
        "delivered_at":       null
      }
    ],
    "pagination": {
      "total": 1, "per_page": 20,
      "current_page": 1, "last_page": 1
    }
  }
}

GET /shipments/{waybill} Track shipment by waybill number

Returns full tracking details for a single shipment including the complete status history timeline. Use this when you have the Simba waybill number returned after shipment creation.

Path Parameters

Parameter	Type	Description
waybill	string	Simba waybill number e.g. `WAYBILL ID 090873`

JSON — 200 OK

{
  "success": true,
  "data": {
    "waybill_number":     "WAYBILL ID 090873",
    "partner_reference":  "ORD-00123",
    "status":             "out_for_delivery",
    "status_label":       "Out for Delivery",
    "receiver_name":      "Mary Kimani",
    "receiver_phone":     "0756789012",
    "receiver_region":    "Mwanza",
    "origin_branch":      "DAR ES SALAAM",
    "destination_branch": "MWANZA",
    "current_branch":     "MWANZA",
    "created_at":         "2026-06-08T14:23:34.000000Z",
    "delivered_at":       null,
    "tracking_timeline": [
      {
        "status":    "in_warehouse",
        "label":     "At Warehouse",
        "note":      "Package received and sorted",
        "location":  "Dar es Salaam Hub",
        "timestamp": "2026-06-08T14:23:34.000000Z"
      },
      {
        "status":    "in_transit",
        "label":     "In Transit",
        "note":      "Dispatched to Mwanza",
        "location":  "On route to Mwanza",
        "timestamp": "2026-06-09T08:00:00.000000Z"
      },
      {
        "status":    "out_for_delivery",
        "label":     "Out for Delivery",
        "note":      null,
        "location":  "Mwanza Branch",
        "timestamp": "2026-06-10T09:15:00.000000Z"
      }
    ]
  }
}

GET /orders/{reference}/shipment Track all shipments by your order reference

Returns all shipments linked to your order reference. This is the recommended tracking method — use your own order ID without needing to store Simba waybill numbers. Returns an array since one order can produce multiple shipments.

Path Parameters

Parameter	Type	Description
reference	string	Your order ID used when creating the pickup request e.g. `ORD-00123`

JSON — 200 OK

{
  "success":           true,
  "data": {
    "partner_reference": "ORD-00123",
    "total_shipments":   2,
    "shipments": [
      {
        "waybill_number":    "WAYBILL ID 090873",
        "status":            "delivered",
        "status_label":      "Delivered",
        "receiver_name":     "Mary Kimani",
        "delivered_at":      "2026-06-10T14:30:00.000000Z",
        "tracking_timeline": [/* full history array */]
      },
      {
        "waybill_number":    "WAYBILL ID 090874",
        "status":            "out_for_delivery",
        "status_label":      "Out for Delivery",
        "receiver_name":     "Mary Kimani",
        "delivered_at":      null,
        "tracking_timeline": [/* full history array */]
      }
    ]
  }
}

Shipment Statuses

#statuses

pendingPending Pickup

assignedDriver Assigned

picked_upPicked Up

in_warehouseAt Warehouse

dispatched_to_fleetDispatched to Fleet

in_transitIn Transit

out_for_deliveryOut for Delivery

deliveredDelivered

failedDelivery Failed

returnedReturned to Sender

cancelledCancelled

Pickup Request Statuses

#pickup-statuses

pendingAwaiting driver assignment

assignedDriver assigned

pickedParcel collected

handed_overHanded to warehouse

cancelledRequest cancelled

Error Handling

#errors

HTTP Code	Meaning	Common Cause
200	OK	Request successful
201	Created	Resource created successfully
401	Unauthorized	Missing or invalid Bearer token
403	Forbidden	Accessing a resource that does not belong to your account
404	Not Found	Shipment or pickup request does not exist or is not accessible
422	Validation Error	Required field missing, invalid date, or invalid `pickup_point_id`

Partner APIDocumentation

Introduction

Base URL

Authentication

Integration Flow

Pickup Points

Pickup Requests

Shipments

Shipment Statuses

Pickup Request Statuses

Error Handling

Partner API
Documentation