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.
curl "https://api.goldrock.live/api/public/v1/auth/me" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET"const response = await fetch("https://api.goldrock.live/api/public/v1/auth/me", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/auth/me';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/auth/me",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.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.
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=حي البرية'const params = new URLSearchParams({
"country": "SA",
"city": "جده",
"district": "حي البرية"
});
const response = await fetch(`https://api.goldrock.live/api/public/v1/geography/resolve?${params}`, {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/geography/resolve?' . http_build_query([
'country' => 'SA',
'city' => 'جده',
'district' => 'حي البرية',
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/geography/resolve",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
params={
"country": "SA",
"city": "جده",
"district": "حي البرية",
},
timeout=30,
)
print(response.status_code, response.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.
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"
}'const response = await fetch("https://api.goldrock.live/api/public/v1/pricing/quote", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json"
},
body: JSON.stringify({
"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"
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/pricing/quote';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'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_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/pricing/quote",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
json={
"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",
},
timeout=30,
)
print(response.status_code, response.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.
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
}
}'const response = await fetch("https://api.goldrock.live/api/public/v1/shipments", {
method: "POST",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Content-Type": "application/json",
"Idempotency-Key": "order-1001"
},
body: JSON.stringify({
"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
}
}),
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
'Content-Type: application/json',
'Idempotency-Key: order-1001',
],
CURLOPT_POSTFIELDS => json_encode([
'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,
],
], JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"POST",
"https://api.goldrock.live/api/public/v1/shipments",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
"Idempotency-Key": "order-1001",
},
json={
"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,
},
},
timeout=30,
)
print(response.status_code, response.json())The answer is 201 with the full shipment. Keep the trackingNumber: it identifies the shipment in every other route.
{
"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
}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"const response = await fetch("https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/shipments/AWB-RUH-000123/tracking",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.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
}
]
}- Conventions: pagination, languages, rate limits, idempotency and errors.
- Shipments: every field, returns and exchanges, the status lifecycle.
- Webhooks: get notified instead of polling.
- Build your shipping company website: a page-by-page tutorial.
- The API reference lists every endpoint, generated from the OpenAPI document.