HLD API Documentation

Hyperlocal Delivery - Client Integration Guide

v2.1
AL Services India
delivery.alfast.in
Last Updated: April 2026
Overview Authentication Create Order Realtime Tracking Order List Cancel Order Serviceability Status Codes WebSocket Errors

Overview

HLD (Hyperlocal Delivery) is a hyperlocal, on-demand delivery service by AL Services India. Deliveries are completed within 120 minutes. This document covers all client-facing APIs for order creation, real-time tracking, order management, and cancellation.

Base URL

https://delivery.alfast.in/api/v1

Available Endpoints

POST Create Order

Place a new HLD order with pickup & delivery details

GET Track Order

Real-time order tracking with executive location (Public)

GET Order List

Paginated list of all client orders

POST Cancel Order

Cancel an HLD order before executive assignment

POST Check Serviceability

Verify HLD service availability with pricing & ETA

GET Assignment Status

Check executive assignment status for an order

Authentication

All client APIs (except public tracking) require a Bearer Token in the request header. Contact AL Services team to get your API credentials.

Authorization: Bearer {your_api_token}
Content-Type:  application/json
Accept:        application/json
POST /client/hld/create-order Auth Required

Create a new HLD (Hyperlocal Delivery) order. Delivery guaranteed within 120 minutes. The system will automatically find and assign the nearest available executive.

Full URL: https://delivery.alfast.in/api/v1/client/hld/create-order
Duplicate Check: Orders with same customer_order_no within 5 minutes are rejected.

Request Parameters

FieldTypeRequiredDescription
Order Information
customer_order_nostringRequiredYour unique order reference number (max 100 chars)
product_namestringRequiredName/description of the product (max 255 chars)
product_valuenumericRequiredDeclared product value in INR (min: 1)
cod_valuenumericOptionalCash on delivery amount (min: 0)
payment_modestringOptionalPayment mode: COD, Prepaid, or Partial
Contact Details
contact_personstringRequiredRecipient name (max 100 chars)
contact_numberstringRequiredRecipient phone number (max 15 chars)
special_instructionsstringOptionalAny special handling instructions (max 500 chars)
Pickup Location
pickup_addressstringRequiredFull pickup address (max 500 chars)
pickup_pincodestringOptionalPickup area pincode (max 6 chars)
pickup_latnumericRequiredPickup latitude (-90 to 90)
pickup_lngnumericRequiredPickup longitude (-180 to 180)
Delivery Location
delivery_addressstringRequiredFull delivery address (max 500 chars)
delivery_pincodestringOptionalDelivery area pincode (max 6 chars)
delivery_latnumericRequiredDelivery latitude (-90 to 90)
delivery_lngnumericRequiredDelivery longitude (-180 to 180)
Delivery Preferences
expected_delivery_minutesintegerOptionalExpected delivery time in minutes (15 - 120)
priority_levelintegerOptional1 = Normal, 2 = High, 3 = Urgent
requires_signaturebooleanOptionalWhether delivery requires customer signature
delivery_preferencesjsonOptionalAdditional delivery preferences as JSON
Package Dimensions
lengthnumericOptionalPackage length in cm
widthnumericOptionalPackage width in cm
heightnumericOptionalPackage height in cm
weightnumericOptionalPackage weight in kg

Sample Request

POST /api/v1/client/hld/create-order
{
  "customer_order_no": "ORD-2026-00456",
  "product_name": "Gold Necklace Set",
  "product_value": 45000.00,
  "cod_value": 0,
  "payment_mode": "Prepaid",
  "contact_person": "Priya Sharma",
  "contact_number": "9876543210",
  "special_instructions": "Handle with care - fragile jewelry box",

  "pickup_address": "Zaveri Bazaar, 42 Kalbadevi Road, Mumbai 400002",
  "pickup_pincode": "400002",
  "pickup_lat": 18.9488,
  "pickup_lng": 72.8310,

  "delivery_address": "Bandra West, Hill Road, Mumbai 400050",
  "delivery_pincode": "400050",
  "delivery_lat": 19.0596,
  "delivery_lng": 72.8295,

  "expected_delivery_minutes": 45,
  "priority_level": 2,
  "requires_signature": true,
  "weight": 0.5,
  "length": 20,
  "width": 15,
  "height": 8
}

Success Response 201 Created

{
  "success": true,
  "message": "HLD order created successfully",
  "data": {
    "order": {
      "id": "HLD2026040412345",
      "customer_order_no": "ORD-2026-00456",
      "service_type": "HLD",
      "status": 1,
      "status_text": "Order Placed",
      "is_hld_order": true,
      "pickup_address": "Zaveri Bazaar, 42 Kalbadevi Road, Mumbai 400002",
      "pickup_pincode": "400002",
      "pickup_lat": 18.9488,
      "pickup_lng": 72.8310,
      "delivery_address": "Bandra West, Hill Road, Mumbai 400050",
      "delivery_pincode": "400050",
      "delivery_lat": 19.0596,
      "delivery_lng": 72.8295,
      "product_name": "Gold Necklace Set",
      "product_value": 45000.00,
      "cod_value": 0.00,
      "contact_person": "Priya Sharma",
      "contact_number": "9876543210",
      "expected_delivery_minutes": 45,
      "priority_level": 2,
      "priority_text": "High",
      "tracking_token": "HLD67890ABCDEF",
      "pickup_otp": "4521",
      "delivery_otp": "7893",
      "created_at": "2026-04-04T10:30:00Z",
      "hld_assignment_deadline": "2026-04-04T10:35:00Z"
    },
    "tracking": {
      "token": "HLD67890ABCDEF",
      "url": "https://delivery.alfast.in/track/hld/HLD67890ABCDEF",
      "short_url": "https://delivery.alfast.in/track/hld/HLD67890ABCDEF",
      "live_tracking_enabled": true
    },
    "assignment": {
      "status": "finding_executive",
      "executive_id": null,
      "assigned_at": null,
      "deadline": "2026-04-04T10:35:00Z",
      "note": "Searching for available executive"
    }
  }
}

Error Responses

422 - Validation Error

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "product_value": ["The product value field is required."],
    "pickup_lat": ["Invalid latitude coordinate."]
  }
}

400 - Service Not Available

{
  "success": false,
  "message": "HLD service not available",
  "error_code": "SERVICE_NOT_AVAILABLE"
}

400 - Duplicate Order

{
  "success": false,
  "message": "Duplicate order detected - same order created within last 5 minutes",
  "error_code": "DUPLICATE_ORDER"
}
GET /track/{trackingToken} Public - No Auth

Get real-time order tracking information including executive location. This is a public endpoint - no authentication required. Share the tracking URL with your customers.

Full URL: https://delivery.alfast.in/api/v1/track/{trackingToken}
Example: https://delivery.alfast.in/api/v1/track/HLD67890ABCDEF

URL Parameters

ParameterTypeDescription
trackingTokenstringUnique tracking token received in create order response

Success Response 200 OK

{
  "success": true,
  "data": {
    "order_id": "HLD2026040412345",
    "status": 25,
    "status_text": "On the Way",
    "pickup_address": "Zaveri Bazaar, 42 Kalbadevi Road, Mumbai",
    "delivery_address": "Bandra West, Hill Road, Mumbai",
    "expected_delivery_minutes": 45,
    "delivery_eta": "2026-04-04T11:15:00Z",
    "delivery_time_remaining": "12 minutes",
    "created_at": "2026-04-04T10:30:00Z",
    "assigned_at": "2026-04-04T10:33:00Z",
    "pickup_completed_at": "2026-04-04T10:48:00Z",
    "completed_at": null,
    "executive": {
      "name": "Rajesh Kumar",
      "mobile": "9876543212",
      "current_location": {
        "lat": 19.0176,
        "lng": 72.8301
      }
    },
    "real_time_updates": [
      {
        "status": 1,
        "timestamp": "2026-04-04T10:30:00Z",
        "location": { "lat": 18.9488, "lng": 72.8310 }
      },
      {
        "status": 2,
        "timestamp": "2026-04-04T10:33:00Z",
        "location": { "lat": 18.9488, "lng": 72.8310 }
      },
      {
        "status": 3,
        "timestamp": "2026-04-04T10:48:00Z",
        "location": { "lat": 18.9492, "lng": 72.8315 }
      }
    ]
  }
}

Error Response 404 Not Found

{
  "success": false,
  "message": "Invalid tracking token"
}
Real-Time Updates via WebSocket
For live tracking, subscribe to the Pusher channel. See WebSocket section below.
GET /android-client/orders Auth Required

Get a paginated list of all orders placed by the authenticated client. Results are sorted by most recent first.

Full URL: https://delivery.alfast.in/api/v1/android-client/orders?per_page=10
Also available at: https://delivery.alfast.in/api/v1/web-client/orders?per_page=10

Query Parameters

ParameterTypeDefaultDescription
per_pageinteger3Number of orders per page
pageinteger1Page number for pagination

Success Response 200 OK

{
  "data": [
    {
      "id": "HLD2026040412345",
      "client_name": "Sunrise Jewellers",
      "customer_order_no": "ORD-2026-00456",
      "product_name": "Gold Necklace Set",
      "order_type": 1,
      "pickup": "Zaveri Bazaar, Mumbai",
      "pickup_address": "Zaveri Bazaar, 42 Kalbadevi Road, Mumbai",
      "pickup_pincode": "400002",
      "delivery": "Bandra West, Mumbai",
      "delivery_address": "Bandra West, Hill Road, Mumbai",
      "delivery_pincode": "400050",
      "status": "Delivered",
      "product_value": 45000.00,
      "cod_value": 0.00,
      "length": 20.00,
      "width": 15.00,
      "height": 8.00,
      "weight": 0.50,
      "assigned_to": "Rajesh Kumar",
      "product_payment_type": "Prepaid",
      "pickup_type": "Self",
      "contact_person": "Priya Sharma",
      "created_at": "04 Apr, 2026 10:30 am",
      "rating": {
        "rating_service": 4.5,
        "review_service": "Excellent delivery",
        "rating_executive": 5.0,
        "review_executive": "Very professional"
      }
    }
  ],
  "links": {
    "first": "https://delivery.alfast.in/api/v1/android-client/orders?page=1",
    "last": "https://delivery.alfast.in/api/v1/android-client/orders?page=5",
    "prev": null,
    "next": "https://delivery.alfast.in/api/v1/android-client/orders?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 10,
    "to": 10,
    "total": 48
  }
}
POST /client/hld/cancel-order Auth Required

Cancel an HLD order. Orders can only be cancelled before executive assignment.

Important: Cancellation is only allowed when order status is: Order Placed (1), Order Confirmed (12), Preparing (15), Ready for Pickup (23), or Finding Executive (13). Once an executive is assigned, cancellation is not permitted.
Full URL: https://delivery.alfast.in/api/v1/client/hld/cancel-order

Request Parameters

FieldTypeRequiredDescription
order_idstringRequiredHLD order ID to cancel
reasonstringRequiredCancellation reason (max 500 chars)

Sample Request

{
  "order_id": "HLD2026040412345",
  "reason": "Customer changed delivery address"
}

Success Response 200 OK

{
  "success": true,
  "message": "Order cancelled successfully",
  "data": {
    "order_id": "HLD2026040412345",
    "status": 17,
    "status_text": "Cancelled",
    "cancelled_at": "2026-04-04T10:32:00Z",
    "reason": "Customer changed delivery address"
  }
}

Error Response 400 - Cancellation Not Allowed

{
  "success": false,
  "message": "Order cannot be cancelled after executive assignment",
  "error_code": "CANCELLATION_NOT_ALLOWED",
  "data": {
    "current_status": 2,
    "status_text": "Executive Assigned",
    "hint": "Order can only be cancelled before executive is assigned"
  }
}
POST /client/hld/check-serviceability Auth Required

Check if HLD service is available between pickup and delivery locations. Returns pricing, ETA, and nearby executive availability. Recommended to call before creating an order.

Full URL: https://delivery.alfast.in/api/v1/client/hld/check-serviceability
Max Distance: 15 km between pickup and delivery

Request Parameters

FieldTypeRequiredDescription
pickup_latnumericRequired*Pickup latitude (required if no pickup_pincode)
pickup_lngnumericRequired*Pickup longitude (required if no pickup_pincode)
pickup_pincodestringRequired*6-digit pincode (required if no lat/lng)
delivery_latnumericRequired*Delivery latitude (required if no delivery_pincode)
delivery_lngnumericRequired*Delivery longitude (required if no delivery_pincode)
delivery_pincodestringRequired*6-digit pincode (required if no lat/lng)
product_valuenumericOptionalProduct value for pricing calculation
weightnumericOptionalPackage weight in kg
priority_levelintegerOptional1-3 priority level

* Either lat/lng OR pincode is required for each location

Sample Request

{
  "pickup_lat": 18.9488,
  "pickup_lng": 72.8310,
  "delivery_lat": 19.0596,
  "delivery_lng": 72.8295,
  "product_value": 45000,
  "weight": 0.5
}

Order Status Codes

Main Order Flow

CodeStatusDescription
1OrderPlacedOrder placed by client
13FindingExecutiveFinding nearby executive, pending acceptance
2ExecutiveAssignedExecutive accepted the order
24ExecutiveComingExecutive on way to pickup
3PickedUpOrder picked up
4DeliveredDelivered successfully (Prepaid)
9PaymentReceivedDelivered + COD payment collected
11CompletedOrder fully completed (Final)

Cancellation Statuses

CodeStatusDescription
17CustomerCancelledCancelled by customer
7SystemCancelledCancelled by system (timeout)

Exception Statuses

CodeStatusDescription
10ExecutiveRejectedExecutive rejected, reassigning

WebSocket - Real-Time Events

For live tracking updates, subscribe to Pusher WebSocket channels using the order's tracking token.

Channel: hld.order.{tracking_token}
Example: hld.order.HLD67890ABCDEF

Event: executive.location_updated

Fired when executive's GPS location changes during delivery.

{
  "order_id": "HLD2026040412345",
  "executive_id": "EXC-001",
  "location": {
    "lat": 19.0176,
    "lng": 72.8301
  },
  "timestamp": "2026-04-04T11:02:30Z"
}

Event: hld.order.status_changed

Fired when order status transitions (e.g., Picked Up, On the Way, Delivered).

{
  "order": {
    "id": "HLD2026040412345",
    "status": 25,
    "status_text": "On the Way"
  },
  "tracking_entry": {
    "status": 25,
    "timestamp": "2026-04-04T10:50:00Z"
  },
  "notification": "Your order is on the way!",
  "timestamp": "2026-04-04T10:50:00Z"
}

Error Codes Reference

HTTP CodeError CodeDescription
401UNAUTHENTICATEDInvalid or missing Bearer token
403ORDER_ACCESS_DENIEDOrder does not belong to this client
404NOT_FOUNDOrder or tracking token not found
422VALIDATION_FAILEDRequest validation failed - check errors object
400SERVICE_NOT_AVAILABLEHLD service not available at given location
400DUPLICATE_ORDERSame customer_order_no submitted within 5 minutes
400CANCELLATION_NOT_ALLOWEDOrder cannot be cancelled after executive assignment
400NOT_HLD_ORDEROrder is not an HLD type order
500SERVER_ERRORInternal server error - contact support

AL Services India — Secure Jewelry Logistics Excellence

alservicesindia.com  |  sales@alservicesindia.com  |  +91 7875566919

Amit Plaza, Indraprastha Society, Hadapsar, Pune - 411028, India