Build on DROP-IT delivery

Overview & access

The API follows a predictable flow: list approved pickup addresses, create a priced quote, confirm a shipment from that quote, then poll or listen for status updates. Operations staff can still use the corporate portal while your integration handles day-to-day booking.

• Corporate business account with Partner Shipping API enabled by DROP-IT support.
• HTTPS-only webhook URLs on your side (no redirects).
• JSON request and response bodies with standard HTTP status codes.

New to DROP-IT for business? See business delivery or register a business account.

Sandbox vs live

Sandbox and live keys share the same base URL but are scoped by key prefix. Sandbox bookings create simulated shipments you can advance with the simulate endpoint; live bookings create real parcels subject to credit and service rules.

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

Authentication

Send your API key as a Bearer token on every request. Keys are shown once when created; store them in a secrets manager. Each key carries abilities (for example read quotes vs create shipments) configured when the key is issued.

Authorization: Bearer dk_sandbox_your_key_here

• Keys are header-only. Never put an API key in a query string or URL path (proxies, access logs, and browser history can leak it).
• Grant only the abilities your integration needs. Prefer read abilities first; add shipments.write only when booking from your system.
• Live keys belong in server-side secret storage. Rotate them periodically (and whenever a key may have been exposed).
• In the interactive API reference, use sandbox keys only — never paste a live key into the browser.

Unauthorized or revoked keys return 401; missing abilities return 403. Rate limits apply per account (defaults are documented in the portal).

Pickup locations

Quotes reference saved corporate pickup addresses (warehouses, shops, or offices). Manage addresses in the portal, then pass the returned pickup_location_id when creating quotes.

GET https://api.dropit.co.tz/api/v1/partner/pickup-locations — requires a key with quote read ability.

Quotes

POST a destination, recipient details, and parcel list to receive a quote ID and pricing. Quotes expire; book shipments before the expiry time returned in the response.

curl -X POST "https://api.dropit.co.tz/api/v1/partner/quotes" \
  -H "Authorization: Bearer dk_sandbox_…" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_location_id": "your-saved-address-id",
    "recipient_name": "Jane Doe",
    "recipient_phone": "+255700000001",
    "destination": {
      "latitude": -6.7924,
      "longitude": 39.2083,
      "address_line": "Masaki, Dar es Salaam"
    },
    "parcels": [{ "weight_kg": 1.2, "description": "Sample parcel" }]
  }'

Shipments

Confirm a shipment with the quote ID and your own merchant_reference (order number). Always send an Idempotency-Key header on create so network retries do not double-book.

curl -X POST "https://api.dropit.co.tz/api/v1/partner/shipments" \
  -H "Authorization: Bearer dk_sandbox_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-create" \
  -d '{
    "quote_id": "qt_…",
    "merchant_reference": "order-12345"
  }'

Retrieve status with GET https://api.dropit.co.tz/api/v1/partner/shipments/{tracking_number}, list recent jobs with GET https://api.dropit.co.tz/api/v1/partner/shipments, and cancel when allowed with POST …/cancel. Sandbox shipments support POST …/simulate to advance test statuses.

Webhooks

Register HTTPS endpoints in the corporate portal to receive JSON events (shipment created, picked up, out for delivery, delivered, and others). Each delivery includes headers you must verify before trusting the payload.

• X-DropIt-Event-Id — unique event identifier
• X-DropIt-Delivery-Id — delivery attempt identifier
• X-DropIt-Timestamp — Unix timestamp used in signing
• X-DropIt-Signature — HMAC-SHA256 of {timestamp}.{raw_body}

The signing secret is shown once when you create the endpoint. Respond with 2xx quickly; failures are retried with backoff.

Verify signatures (PHP)

$timestamp = (string) $request->header('X-DropIt-Timestamp');
$signature = (string) $request->header('X-DropIt-Signature');
$body = $request->getContent();

$expected = hash_hmac('sha256', $timestamp.'.'.$body, $webhookSecret);

if ($signature === '' || ! hash_equals($expected, $signature)) {
    abort(401, 'Invalid webhook signature');
}

// Optional: reject replays older than five minutes
if (abs(time() - (int) $timestamp) > 300) {
    abort(401, 'Stale webhook timestamp');
}

Verify signatures (Node.js)

const crypto = require('node:crypto');

const timestamp = req.headers['x-dropit-timestamp'];
const signature = req.headers['x-dropit-signature'];
const body = req.rawBody; // unparsed JSON string

const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(`${timestamp}.${body}`)
  .digest('hex');

if (!signature || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).send('Invalid webhook signature');
}

Recipient SMS

When a delivery or hub pickup requires confirmation, DROP-IT sends an SMS to the recipient phone you provide on the quote or shipment. Partner API parcels use merchant-aware templates (your company display name and tracking number) so recipients know who sent the parcel.

SMS copy for recipients is sent in English. Your integration should collect valid Tanzanian mobile numbers and keep them updated if orders change before pickup.