GROperator

Overview and quickstart

The LastMile Public API lets a shipping company build its own website, mobile app or back-office integration on top of its LastMile account. It is a JSON over HTTPS API: everything you can do for a shipment in the dashboard (book it, price it, track it, print its label, cancel it) you can do from your own code, plus the supporting data you need to build a good experience, such as countries, cities, districts, coverage, merchants and their saved addresses.

All endpoints live under one versioned base path, /api/public/v1. The examples in this site use the API address configured for this documentation, followed by that path.

  • A tracking page: look up any shipment by tracking number and show its status timeline.
  • A price calculator and a coverage checker for visitors who have not ordered yet.
  • An order form that validates the address, quotes the price and creates the shipment.
  • A merchant portal where each merchant signs in with its own username and password and sees only its own shipments.
  • Back-office automation: bulk creation from a spreadsheet or an e-commerce platform, with status updates pushed to you by webhook.
API key and secret Username and password
How Send X-API-Key and X-API-Secret on every request POST /auth/login, then Authorization: Bearer <accessToken>
Created by A company admin in the dashboard (Settings, API access) An existing dashboard user, including a merchant login
Permissions The scopes you choose for the key The permissions of that user
Best for Websites and server-to-server integrations Acting as a specific user, or a merchant portal

Both work on the same endpoints. Read Authentication before you choose, and never put a key or secret in browser or mobile code.

The API only works for your company when two switches are on: the platform has granted your company the API integration channel, and your company admin has switched it on. Otherwise every call answers 403 channel_disabled. Enable the API walks through both and the creation of a key.

You need an API key and secret with the scopes geography:read, pricing:read, shipments:read and shipments:write. The examples use placeholders; replace them with your own values.

GET /auth/me needs no scope. It tells you which company you are and which scopes the credential holds.

GET /auth/me
curl "https://api.goldrock.live/api/public/v1/auth/me" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"
JSON
{
  "authMethod": "api_key",
  "company": {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "name": "Fast Express",
    "slug": "fast-express"
  },
  "user": null,
  "apiKey": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Website integration"
  },
  "scopes": [
    "geography:read",
    "pricing:read",
    "shipments:read",
    "shipments:write"
  ],
  "permissions": [
    "orders:create",
    "orders:read"
  ]
}

If you get 401 unauthorized, one of the two headers is missing or wrong. If you get 403 channel_disabled, the API is not enabled for the company yet.

Places are matched by name, in Arabic or English, and nothing is ever created from an API call. Check the address before you use it. The spelling variants are tolerated: here جده finds جدة and حي البرية finds البرية. See Places by name.

GET /geography/resolve
curl -G "https://api.goldrock.live/api/public/v1/geography/resolve" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  --data-urlencode 'country=SA' \
  --data-urlencode 'city=جده' \
  --data-urlencode 'district=حي البرية'
JSON
{
  "country": {
    "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
    "nameAr": "المملكة العربية السعودية",
    "nameEn": "Saudi Arabia"
  },
  "city": {
    "id": "a1d3c2b4-0e7f-4f5a-8a62-9c1e2d3b4a05",
    "nameAr": "جدة",
    "nameEn": "Jeddah"
  },
  "district": {
    "id": "e4b7a9d2-6c13-4d8e-b1f0-2a5c7e9f3b18",
    "nameAr": "البرية",
    "nameEn": "Al Bariyah"
  }
}

A quote creates nothing and uses no quota. If the company does not cover the route you still get 200, with deliverable: false and a reason.

POST /pricing/quote
curl -X POST "https://api.goldrock.live/api/public/v1/pricing/quote" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant": "Noor Electronics",
  "pickup": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya"
  },
  "recipient": {
    "country": "SA",
    "city": "Jeddah",
    "district": "Al Rawdah"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10
  },
  "payment": {
    "codAmount": 199.5
  },
  "serviceType": "delivery",
  "serviceTier": "standard"
}'
JSON
{
  "deliverable": true,
  "reason": null,
  "shippingFee": 25,
  "codFee": 5,
  "total": 30,
  "chargeableWeightKg": 1.5,
  "zone": {
    "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",
    "name": "Zone 2"
  },
  "breakdown": [
    {
      "code": "baseShipping",
      "label": "Base shipping",
      "amount": 25
    },
    {
      "code": "codFee",
      "label": "Cash on delivery fee",
      "amount": 5
    }
  ]
}

Send an Idempotency-Key so a retry after a network error can never create a duplicate. Saudi addresses need the national short address (4 letters and 4 digits). The shipping fee always comes from your rate card: you cannot send one.

POST /shipments
curl -X POST "https://api.goldrock.live/api/public/v1/shipments" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
  "reference": "ORD-1001",
  "serviceType": "delivery",
  "serviceTier": "standard",
  "sender": {
    "type": "merchant",
    "merchant": "Noor Electronics"
  },
  "recipient": {
    "country": "SA",
    "city": "Riyadh",
    "district": "Al Olaya",
    "addressLine": "King Fahd Road, Building 12, Floor 3",
    "shortAddress": "RNBA6769",
    "name": "Khaled Alotaibi",
    "phone": "0555123456"
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10,
    "pieces": 1,
    "description": "Mobile phone case",
    "declaredValue": 250,
    "fragile": false
  },
  "payment": {
    "codAmount": 199.5,
    "freightOnDelivery": false
  },
  "delivery": {
    "allowOpenPackage": false,
    "requireSignature": true
  }
}'

The answer is 201 with the full shipment. Keep the trackingNumber: it identifies the shipment in every other route.

JSON
{
  "trackingNumber": "AWB-RUH-000123",
  "reference": "ORD-1001",
  "status": "created",
  "statusCode": 1020,
  "statusLabelAr": "تم إنشاء الطلب",
  "statusLabelEn": "Order Created",
  "isFinal": false,
  "serviceType": "delivery",
  "serviceTier": "standard",
  "source": "api",
  "createdAt": "2026-01-15T09:30:00Z",
  "estimatedDeliveryDate": "2026-01-17",
  "sender": {
    "type": "merchant",
    "name": "Noor Electronics",
    "phone": "0501234567",
    "email": "orders@noor-electronics.example",
    "merchant": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Noor Electronics"
    }
  },
  "pickup": {
    "country": {
      "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
      "nameAr": "المملكة العربية السعودية",
      "nameEn": "Saudi Arabia"
    },
    "city": {
      "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
      "nameAr": "الرياض",
      "nameEn": "Riyadh"
    },
    "district": {
      "id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
      "nameAr": "العليا",
      "nameEn": "Al Olaya"
    },
    "addressLine": "King Fahd Road, Warehouse 4",
    "shortAddress": "RNBA6769",
    "latitude": null,
    "longitude": null
  },
  "recipient": {
    "name": "Khaled Alotaibi",
    "phone": "0555123456",
    "secondaryPhone": null,
    "country": {
      "id": "5a6f7c1c-1a3e-4c1f-9d5c-3f0d7d2a1b01",
      "nameAr": "المملكة العربية السعودية",
      "nameEn": "Saudi Arabia"
    },
    "city": {
      "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
      "nameAr": "الرياض",
      "nameEn": "Riyadh"
    },
    "district": {
      "id": "c2d3e4f5-0a1b-4c2d-8e3f-4a5b6c7d8e91",
      "nameAr": "العليا",
      "nameEn": "Al Olaya"
    },
    "addressLine": "King Fahd Road, Building 12, Floor 3",
    "shortAddress": "RNBA6769",
    "latitude": null,
    "longitude": null
  },
  "parcel": {
    "weightKg": 1.5,
    "lengthCm": 20,
    "widthCm": 15,
    "heightCm": 10,
    "chargeableWeightKg": 1.5,
    "pieces": 1,
    "description": "Mobile phone case",
    "declaredValue": 250,
    "fragile": false,
    "requiresColdChain": false,
    "coldChainRange": null,
    "flammable": false,
    "hazardous": false,
    "containsAlcohol": false,
    "liquid": false,
    "highValue": false
  },
  "delivery": {
    "allowOpenPackage": false,
    "requireSignature": true,
    "requireIdVerification": false,
    "allowNeighborDelivery": true
  },
  "payment": {
    "codAmount": 199.5,
    "shippingFee": 30,
    "freightOnDelivery": false
  },
  "pieces": [
    {
      "barcode": "AWB-RUH-000123-P1"
    }
  ],
  "branch": {
    "id": "8d3c7f52-4b1e-4a90-b6d2-1e5f9a0c3b74",
    "name": "Riyadh Hub"
  },
  "canCancel": true,
  "isEditable": true
}
GET /shipments/AWB-RUH-000123/tracking
curl "https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"
JSON
{
  "trackingNumber": "AWB-RUH-000123",
  "status": "outForDelivery",
  "statusLabelAr": "خرج للتوصيل",
  "statusLabelEn": "Out For Delivery",
  "estimatedDeliveryDate": "2026-01-17",
  "events": [
    {
      "status": "created",
      "statusLabelAr": "تم إنشاء الطلب",
      "statusLabelEn": "Order Created",
      "at": "2026-01-15T09:30:00Z",
      "note": null,
      "location": null
    },
    {
      "status": "pickedUp",
      "statusLabelAr": "تم الاستلام",
      "statusLabelEn": "Picked Up",
      "at": "2026-01-15T14:05:00Z",
      "note": null,
      "location": null
    },
    {
      "status": "outForDelivery",
      "statusLabelAr": "خرج للتوصيل",
      "statusLabelEn": "Out For Delivery",
      "at": "2026-01-17T07:40:00Z",
      "note": null,
      "location": null
    }
  ]
}