Welcome to the Bob Box API

The Bob Box API is the gateway to South Africa's courier-agnostic smart locker network. It lets couriers, e-commerce platforms, and logistics systems find lockers, reserve compartments, and follow a parcel through dropoff and collection.

By integrating, your platform gains access to a growing nationwide locker network, and your customers get delivery and collection that does not depend on anyone being home.

What you can do

Find lockers. Search the live network by coordinates and radius, by bounding box, or by name. Every location comes back with its address, GPS coordinates, trading hours, photos, and status.
Check space before you commit. Ask for availability by parcel size and get back which compartment sizes are actually free at each location right now.
Reserve a compartment. Send your parcel dimensions and Bob Box matches them to a compartment size. You get the compartment, the PINs, and the billing window back in one call.
Hand over PINs. Every reservation carries a dropoff, pickup, and return PIN. Give your customer the one they need.
Follow the parcel. Subscribe to webhooks for dropoff, collection, return, clearing, and PIN changes — or poll the reservation directly.
Cancel cleanly. Release a compartment you no longer need, as long as the parcel is not already inside.
Attach your own data. Put a JSON object on a reservation and it comes back on every read and every webhook, so you can tie a reservation to your own records without a lookup table.

How to read these docs

Section	What it covers
Workflows	The delivery patterns the network supports, and which reservation type each one uses. Start here to work out what you are building.
Getting started	The shortest path from an API key to a live reservation, in six curl commands.
Authentication	Getting and securely using an API key for your integration.
Locations	Finding lockers available to your account.
Reservations	Creating, reading, and cancelling reservations, and fetching PINs.
Webhooks	Getting status changes pushed to your own URL, and verifying they came from us.

Base URL

Every request goes to the same host.

Base URL: https://api.bobbox.co.za/v2/

Access

Every request carries Authorization: Bearer <api_key>. Your API key is issued once and never expires.

Create your own key. Sign in to the dashboard as the Bob Box account owner and open Settings → API keys. The key is shown in full once, at that moment — copy it then.
Or ask your Bob Box contact. They will set up an API user for your account and give you the key.

Either way, the Authentication section has the full flow and the rules for keeping the key safe.

Conventions

All requests and responses are JSON, over HTTPS only.
Timestamps are ISO 8601.
Dimensions are centimetres. Volumetric weight is kilograms, at a volumetric factor of 4000 — length × width × height ÷ 4000.
List endpoints return { "<name>": [...], "count": N }, where count ignores limit and offset so you can page. When nothing matches, the array may be left out of the body entirely, so read count and treat a missing array as empty.
List filters that accept several values take a JSON array, e.g. status=["waiting-for-dropoff","waiting-for-pickup"].
Limits are imposed while an account is frozen: GET /account/locations and POST /bob-box/reservations return 403 Account is frozen. Reading, cancelling, and fetching PINs for existing reservations are unaffected.
Errors return a non-2xx status and a JSON body shaped { "message": "..." }. The message is capitalised on the way out, so id is required reaches you as { "message": "Id is required" }. Each endpoint page lists its own messages in their uncapitalised source form. Authentication and permission failures are the exception — they are returned before the handler runs, as plain text.

Support

If you need help at any stage of your integration, reach out to your Bob account manager, or contact us at [email protected].