Getting started

Getting started

This walks through the core integration flow: authenticate, find a location, create a reservation, and hand your customer the PIN that opens the locker.

1. Authenticate

Every request carries Authorization: Bearer <api_key>. Create an API key in the dashboard under Settings → API keys, or ask your Bob Box contact to issue one with an API user. It never expires:

curl -G "https://api.bobbox.co.za/v2/account/locations" \
  -H "Authorization: Bearer 4f3c9b1a72e04d5fa9c8e6b0d1a2f3c4"

That is all you need for the rest of this guide.

2. Find a location

Look up the locker locations available to your account, and check which ones have space for your parcel before you try to reserve.

Endpoint: GET /account/locations

curl -G "https://api.bobbox.co.za/v2/account/locations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "lat=-26.107567" \
  --data-urlencode "lng=28.053040" \
  --data-urlencode "max_distance=10" \
  --data-urlencode "order_closest=true" \
  --data-urlencode "parcel_length=30" \
  --data-urlencode "parcel_width=20" \
  --data-urlencode "parcel_height=10" \
  --data-urlencode "include_availability=true"

Send the parcel dimensions together with include_availability=true. That gives you a compartment_availability map per location:

"compartment_availability": { "Small": true, "Medium": true, "Large": false }

A size is true when a compartment of that size is free and your parcel fits it. Without dimensions, include_availability=true still reports which compartment sizes are free, but it does not check whether your parcel fits. Skip any location where every size is false.

That is enough to finish this guide. What the map does and does not promise about step 3, and what to do when it is wrong, is in the Workflows section under "Checking space before you reserve".

See the Get account locations endpoint in the Locations section for the full parameter and response reference.

3. Create a reservation

Reserve a compartment at the chosen location.

Endpoint: POST /bob-box/reservations

curl -X POST "https://api.bobbox.co.za/v2/bob-box/reservations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "location_id": 213,
    "reservation_type": "client-pickup",
    "parcel_length": 30,
    "parcel_width": 20,
    "parcel_height": 10,
    "allow_auto_upgrade": true,
    "contact_name": "Jane Customer",
    "contact_number": "+27833771167",
    "reference": "ORDER-1452"
  }'

Two things to get right here:

  • reservation_type is required. Leave it out and the call fails.
  • allow_auto_upgrade defaults to false, which fails the reservation while bigger compartments stand empty. The sample above sends true. Why, and when not to, is on the Create reservation endpoint page under "How the parcel is sized".

The response gives you the reservation's id, the compartment it claimed, and all three PINs. Store the id and your own reference so you can look the reservation up later.

See the Create reservation endpoint in the Reservations section for the full parameter and response reference.

4. Give your customer the PIN

The PINs come back on the create response above — you do not need a second call:

PIN Opens the compartment for
dropoff_pin Putting the parcel in
pickup_pin Collecting the parcel
return_pin Sending the parcel back to the sender

Send the customer the one that matches what they are doing. Notifying customers is your side of the integration by default — Bob Box does not SMS or email them unless your account is configured for it. Contact the Bob Box team if you want Bob Box to send the collection SMS instead.

If you ever need the PINs again without pulling the whole reservation, there is a dedicated endpoint:

Endpoint: GET /bob-box/locations/reservations/pins

curl -G "https://api.bobbox.co.za/v2/bob-box/locations/reservations/pins" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "id=8931"

5. Track status

Bob Box can push reservation status changes to your own URL via webhooks — see the Webhooks section. You can also poll the reservation directly.

Endpoint: GET /bob-box/reservations

curl -G "https://api.bobbox.co.za/v2/bob-box/reservations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "id=8931"

Reservation statuses

Status Description
waiting-for-dropoff Reservation created; parcel not yet dropped off.
waiting-for-pickup Parcel dropped off; waiting for the recipient to collect it.
complete Parcel was collected.
expired Legacy status, set only by Bob Box operations. Not part of the normal lifecycle — do not build against it.
cancelled The reservation was cancelled.
returned The parcel was returned to the sender.
cleared The reservation was manually cleared.

Every reservation also carries flat_fee_end_time — the moment the flat-fee window closes and overstay charges start. Watch it if overstay cost matters to you.

See the Get reservations endpoint in the Reservations section for the full field reference.

6. Cancel, if needed

If the parcel is no longer being sent, cancel the reservation to free up the compartment.

Endpoint: POST /bob-box/reservations/cancel

curl -X POST "https://api.bobbox.co.za/v2/bob-box/reservations/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "reservation_id": 8931 }'

This only works while the reservation is still waiting-for-dropoff. Once the parcel is in the locker it cannot be cancelled — the parcel has to be collected or returned instead.

See the Cancel reservation endpoint in the Reservations section for details.

Next steps

  • Webhooks section — get reservation status changes pushed to your own URL instead of polling.
View as Markdown