API Integration (Option A)

How It Works

With Option A, you already have a working delivery API. You provide Deliverty Hub with your endpoint URLs and authentication credentials, and the platform calls your API whenever an organization dispatches a task to your courier service.

This is the simplest integration path. You do not need to write any code that runs inside Deliverty Hub. You only need to ensure your API implements the required endpoints described below.

Required API Endpoints

Your API must implement the following endpoints for Deliverty Hub to communicate with your service:

1. Create Task / Dispatch Delivery

Deliverty Hub calls this endpoint when an organization assigns a delivery task to your courier. Your API should accept the task details (pickup location, dropoff location, package info, etc.) and return a tracking identifier.

// Request from Deliverty Hub
{
  "pickup": {
    "address": "123 Main St, Cairo",
    "lat": 30.0444,
    "lng": 31.2357,
    "contactName": "Warehouse A",
    "contactPhone": "+201234567890"
  },
  "dropoff": {
    "address": "456 Nile Ave, Cairo",
    "lat": 30.0131,
    "lng": 31.2089,
    "contactName": "John Doe",
    "contactPhone": "+201098765432"
  },
  "packages": [
    { "description": "Electronics", "weight": 2.5, "quantity": 1 }
  ],
  "notes": "Handle with care"
}

// Expected response
{
  "trackingId": "YOUR-TRACKING-ID-123",
  "status": "accepted",
  "estimatedDelivery": "2026-02-16T14:00:00Z"
}

2. Get Tracking Status

Deliverty Hub periodically polls this endpoint (or relies on your webhooks) to get the current status of a delivery. Return the current status along with any location data if available.

// Expected response
{
  "trackingId": "YOUR-TRACKING-ID-123",
  "status": "in_transit",
  "location": {
    "lat": 30.0300,
    "lng": 31.2200
  },
  "updatedAt": "2026-02-16T13:30:00Z",
  "estimatedDelivery": "2026-02-16T14:00:00Z"
}

3. Cancel Task

Called when an organization cancels a delivery that was previously dispatched to your service. Your API should cancel the delivery on your end and confirm.

// Expected response
{
  "trackingId": "YOUR-TRACKING-ID-123",
  "status": "cancelled",
  "message": "Delivery successfully cancelled"
}

4. Webhook Endpoint (Receiving Updates from Deliverty)

Optionally, you can provide a webhook URL where Deliverty Hub sends updates about tasks (e.g., when an organization modifies task details or when the task is reassigned). This allows you to stay in sync with changes happening on the Deliverty side.

// Payload sent by Deliverty Hub
{
  "event": "task.updated",
  "trackingId": "YOUR-TRACKING-ID-123",
  "data": {
    "dropoff": {
      "address": "789 New Address, Cairo",
      "lat": 30.0500,
      "lng": 31.2400
    },
    "notes": "Updated delivery instructions"
  },
  "timestamp": "2026-02-16T13:45:00Z"
}

Authentication Configuration

When registering your courier with Deliverty Hub, you specify how the platform should authenticate when calling your API.

Choose Your Auth Type

Choose Where to Send Credentials

You also specify where in each HTTP request the credentials should be placed:

Per-Organization Credentials

Deliverty Hub is a multi-tenant platform. Each organization that activates your courier service provides its own credentials. Deliverty stores these credentials securely and uses the correct set for each API call, based on which organization owns the task being dispatched.

This means you can issue different API keys to different organizations, apply different rate limits, or track usage per organization on your end.