Kapiten B2B API Reference

Complete guide to integrating Kapiten's delivery fulfillment network into your business systems. Our API supports full lifecycle management from company onboarding to automated dispatch.

Base URL https://api.kapiteni.com

Create Company

POST /api/companies/

Test: Create Company

CURL Request

Response

Parameter	Type	Description
name REQ	String	Legal name of your business.
registration_number REQ	String	Official business registration ID (e.g., RDB number).
address REQ	String	Physical headquarters or main pickup address.
contact_person REQ	String	Primary administrative contact name.
phone_number REQ	String	Primary business contact phone.
email REQ	String	Business email for invoices and notifications.
webhook_url OPT	URL	Your server endpoint for receiving delivery status updates.

EXAMPLE REQUEST

{
  "name": "Best Pilau Ltd",
  "registration_number": "RDB2026-XP",
  "address": "KN 78 St, Kigali",
  "contact_person": "Victor",
  "phone_number": "+250788123456",
  "email": "hello@bestpilau.com"
}

EXAMPLE RESPONSE

{
  "id": "721e54a2-...",
  "name": "Best Pilau Ltd",
  "registration_number": "RDB2026-XP",
  "balance": 0.0,
  "currency": "RWF",
  "pricing_config": { ... }
}

Registration Lookup

Verify if a company is already registered by their registration number.

GET /api/companies/by-registration/{registration_number}/

Test: Registration Lookup

Registration Number

CURL Request

Response

Parameter	Type	Description
registration_number REQ	String	The unique ID assigned by your local regulator.

EXAMPLE RESPONSE

{
  "id": "721e54a2-...",
  "name": "Best Pilau Ltd",
  "registration_number": "RDB2026-XP",
  "is_active": true
}

Add API User

Create a staff user who will be authorized to manage rides for the company.

POST /api/companies/{company_id}/users/create/

Test: Add API User

Company ID (UUID)

CURL Request

Response

Parameter	Type	Description
phone_number REQ	String	Mobile number of the staff member.
first_name REQ	String	Staff member's first name.
last_name REQ	String	Staff member's last name.
email REQ	String	Unique business email for login access.

EXAMPLE REQUEST

{
  "phone_number": "+250788000111",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@bestpilau.com"
}

EXAMPLE RESPONSE

{
  "id": "9944b091-...",
  "phone_number": "+250788000111",
  "first_name": "John",
  "last_name": "Doe",
  "wallet": { "balance": 0.0, "currency": "RWF" }
}

Get API Key

Retrieve the persistent authentication token for a specific company user.

POST /api/companies/{company_id}/users/{user_id}/token/

Test: Get API Key

Company ID (UUID) User ID (UUID)

CURL Request

Response

Parameter	Type	Description
company_id REQ	UUID	The registration ID of your company.
user_id REQ	UUID	The ID of the staff user (from the Create User response).

EXAMPLE RESPONSE

{ "token": "9944b09199c..." }

Use the returned token in the Authorization header for all subsequent calls:

Authorization: Token <your_token>

Estimate Ride Price

Get a dynamic delivery estimate based on your company's specific pricing configuration and overdraft limits.

POST /api/rides/estimate/

Test: Estimate Price

Company ID (UUID) Pickup (Lat, Lng)

Dropoff (Lat, Lng)

Fragile Priority

CURL Request

Response

Parameter	Type	Description
pickup_latitude REQ	Float	Latitude coordinate of the pickup point.
pickup_longitude REQ	Float	Longitude coordinate of the pickup point.
dropoff_latitude REQ	Float	Latitude coordinate of the delivery destination.
dropoff_longitude REQ	Float	Longitude coordinate of the delivery destination.
company_id REQ	UUID	Your unique company ID assigned during onboarding.
weight_range OPT	String	Package weight category. Choices: `0-5`, `5-10`, `10-20`, `20+`.
includes_fragile_items OPT	Bool	Set `true` if the package contains fragile items for special handling.
is_priority OPT	Bool	Set `true` for expedited priority delivery processing.

EXAMPLE RESPONSE

{
  "amount": 1200.0,
  "details": {
    "base_fare": 500,
    "distance_fare": 700
  }
}

Create Delivery

Submit a new delivery request. Kapiten immediately initiates rider matching for company-authorized rides.

POST /api/rides/

Test: Create Delivery

API Token Company ID (UUID)

Sender & Receiver

Package Info

Fragile Priority

CURL Request

Response

Parameter	Type	Description
pickup_address REQ	String	Human-readable pickup address (e.g., "KK 12 Ave, Kigali").
pickup_latitude REQ	Float	Latitude of the pickup location.
pickup_longitude REQ	Float	Longitude of the pickup location.
dropoff_address REQ	String	Human-readable destination address.
dropoff_latitude REQ	Float	Latitude of the destination.
dropoff_longitude REQ	Float	Longitude of the destination.
sender REQ	Object	JSON object: `{"name": "...", "phone": "..."}`.
receiver REQ	Object	JSON object: `{"name": "...", "phone": "..."}`.
company_id REQ	UUID	Your company's unique identifier.
external_id REC	String	Your internal order/reference ID for cross-system tracking.
pickup_instructions OPT	String	Helpful notes for the rider at pickup.
package_type OPT	String	Brief description (e.g., "Food", "Electronics").
weight_range OPT	String	Options: `0-5`, `5-10`, `10-20`, `20+`.
includes_fragile_items OPT	Bool	Special handling for fragile goods.
is_priority OPT	Bool	Expedited priority delivery.

EXAMPLE REQUEST

{
  "pickup_address": "Kicukiro, KK 12 Ave",
  "pickup_latitude": -1.9441,
  "pickup_longitude": 30.0619,
  "dropoff_address": "M. Peace Plaza, Nyarugenge",
  "dropoff_latitude": -1.9706,
  "dropoff_longitude": 30.1044,
  "sender": { "name": "Best Pilau", "phone": "0788123456" },
  "receiver": { "name": "Customer", "phone": "0789000111" },
  "company_id": "YOUR_UUID",
  "external_id": "ORDER-99123"
}

EXAMPLE RESPONSE

{
  "id": "uuid",
  "reference_number": "KPT-123456",
  "status": "PENDING",
  "estimated_price": 1200.0,
  "distance_km": 4.5
}

Webhooks & Statuses

Webhook events are sent as POST requests to your configured webhook_url whenever a ride transitions between states.

Status	Meaning
`WAITING_PAYMENT`	Initial state for rides requiring customer payment via MoMo/Airtel.
`PENDING`	Ride is paid (or B2B pre-paid) and waiting to be matched with a rider.
`ACCEPTED`	A rider has accepted the request and is en route to the pickup location.
`WAITING_PICKUP`	Rider has arrived at the pickup location and is waiting for the package.
`PICKED_UP`	Package has been successfully collected by the rider.
`IN_TRANSIT`	Rider is currently moving towards the drop-off destination.
`WAITING_DELIVERY`	Rider has arrived at the destination and is initiating handover.
`COMPLETED`	Delivery successfully completed and package handed over.
`CANCELLED`	Ride was cancelled by the sender or an administrator.
`REJECTED`	System was unable to find a rider within the timeout period.

EXAMPLE WEBHOOK PAYLOAD (POST)

{
  "event": "status_update",
  "ride_id": "721e54a2-...",
  "reference_number": "KPT-112233",
  "external_id": "YOUR_INTERNAL_ORDER_ID",
  "status": "PICKED_UP",
  "metadata": { ... }
}

Wallet Top-up

Initiate a real-time wallet top-up using MoMo or Airtel Money via our integrated payment gateway.

POST /api/companies/{company_id}/topup/

Test: Wallet Top-up

API Token Company ID (UUID) Amount (RWF) Billed Phone Number Description

CURL Request

Response

Parameter	Type	Description
amount REQ	Float	The total amount to deposit into your company wallet.
phone_number REQ	String	The mobile number to be billed (078... or 079...).
description OPT	String	Optional reference for your accounting logs.

EXAMPLE RESPONSE

{
  "id": "uuid",
  "amount": 5000.0,
  "transaction_type": "DEPOSIT",
  "status": "PENDING",
  "description": "Weekly credit top-up",
  "created_at": "2026-04-03T..."
}

List Transactions

Retrieve your company's full financial history, including deposits, ride deductions, and adjustments.

GET /api/companies/{company_id}/transactions/

Test: List Transactions

API Token Company ID (UUID)

CURL Request

Response

EXAMPLE RESPONSE (PAGINATED)

{
  "count": 12,
  "next": null,
  "previous": null,
  "results": [
    { "id": "uuid", "amount": -1200.0, "status": "SUCCESS", "description": "Ride deduction" }
  ]
}

List Company Users

Retrieve a paginated list of all staff members associated with your company.

GET /api/companies/{company_id}/users/

Test: List Users

API Token Company ID (UUID)

CURL Request

Response

EXAMPLE RESPONSE (PAGINATED)

{
  "count": 2,
  "results": [
    { "id": "uuid", "first_name": "John", "last_name": "Doe", "email": "..." }
  ]
}

List Rides

Retrieve your company's full delivery history, ordered by creation date (newest first).

GET /api/companies/{company_id}/rides/

Test: List Rides

API Token Company ID (UUID)

CURL Request

Response

Parameter	Type	Description
company_id REQ	UUID	The company ID to filter by.
page OPT	Int	Index for paginated results (default 1).

EXAMPLE RESPONSE (PAGINATED)

{
  "count": 150,
  "next": "https://api.kapiten.com/api/companies/.../rides/?page=2",
  "results": [
    { "id": "uuid", "reference_number": "KPT-112233", "status": "COMPLETED" }
  ]
}