API v1

Book and track deliveries from another website.

The ARIZONAH API uses HTTPS, JSON request bodies, Bearer API keys, explicit scopes, request IDs, per-application rate limits, and idempotency protection for shipment creation.

Authentication

Generate a test or live key in the Developer Portal. The full key is displayed once. Send it in the Authorization header.

Authorization: Bearer az_test_...

Never expose a live API key in browser JavaScript. Call ARIZONAH from your own secure backend.

Create a quote

POST https://arizonahtm.com/api/v1/quotes

curl -X POST 'https://arizonahtm.com/api/v1/quotes' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "pickupCity": "Lagos",
  "destinationCity": "Abuja",
  "fulfilmentMethod": "DOORSTEP_TO_DOORSTEP",
  "packageCategory": "Electronics",
  "weightKg": 3.5,
  "serviceLevel": "EXPRESS",
  "declaredValue": 120000,
  "insurance": true
}'

Create a shipment

First create a quote, then submit the complete sender, recipient, package, schedule, and payment details. A unique Idempotency-Key header is mandatory.

curl -X POST 'https://arizonahtm.com/api/v1/shipments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: 0c902392-8d8f-4e51-a713-8ff77e62f271' \
  -H 'Content-Type: application/json' \
  -d '{ "quoteReference": "QT-...", "fulfilmentMethod": "DOORSTEP_TO_DOORSTEP", "serviceLevel": "EXPRESS", "sender": { "fullName": "Sender Name", "email": "sender@example.com", "phone": "+2348000000000" }, "recipient": { "fullName": "Recipient Name", "phone": "+2348111111111" }, "pickup": { "address": "Pickup address", "city": "Lagos" }, "destination": { "address": "Delivery address", "city": "Abuja" }, "package": { "category": "Electronics", "description": "Laptop", "quantity": 1, "weightKg": 3.5, "declaredValue": 120000, "fragile": true }, "schedule": { "dispatchTiming": "NOW" }, "paymentMethod": "BANK_TRANSFER", "termsAccepted": true, "prohibitedItemsConfirmed": true }'

Retrieve shipment

GET https://arizonahtm.com/api/v1/shipments/{trackingNumber}

Cancel shipment

POST https://arizonahtm.com/api/v1/shipments/{trackingNumber}/cancel

Tracking

GET https://arizonahtm.com/api/v1/tracking/{trackingNumber}

The response contains customer-safe status, route cities, payment state, estimated delivery, and the public event timeline.

Signed webhooks

x-arizonah-event-id: evt_...
x-arizonah-timestamp: 1784059200
x-arizonah-signature: v1=<hex hmac>

Calculate HMAC over timestamp + "." + rawBody using the signing secret shown when the endpoint is created. Reject stale timestamps and duplicate event IDs.

Supported events

shipment.created, shipment.payment_confirmed, shipment.assigned, shipment.picked_up, shipment.in_transit, shipment.out_for_delivery, shipment.delivered, shipment.failed, shipment.cancelled, shipment.returned, payment.succeeded, payment.failed, refund.completed.

Error format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key is invalid or revoked."
  },
  "requestId": "..."
}

Include the request ID when contacting support.