Developer REST API & Webhooks

Integrate Recover Package Tracking

Programmatically create tamper-proof dispatches, generate dual-layer QR stickers, verify PIN handovers, and stream real-time logistics webhooks directly into your ERP or e-commerce store.

Getting Started Guide API Reference View Quota Tiers

Getting Started: From Sign-Up to First Dispatch

Follow these 5 steps to go from zero to a fully automated package tracking integration.

Create a Merchant Account

Sign up on Recover using Google, Email, Apple or Facebook. During profile setup, select "Logistics & Delivery Merchant" as your account type. This unlocks the shipment tracking workspace and API access.

Generate Your Secret API Key

Open your Settings page and scroll to the Developer REST API section. Click "Generate API Key" to create a secret key in the format rec_live_.... Copy this key securely — it authenticates all your server-to-server API calls.

Go to Settings →

Register Your First Dispatch

Call POST /api/v1/shipments/create with your API key in the Authorization header. The response returns a unique packageId, consumer trackingCode, RCVR-prefixed handover secret (innerSecret), and shipment record.

See Code Example ↓

Print & Affix QR Sticker to Package

Use the tracking code URL to generate or print a tamper-proof label onto the shipping box or poly-mailer. When anyone (rider, warehouse, recipient) scans the QR, Recover shows the live package status without any app install.

Complete Delivery with PIN Handover

At delivery, the recipient provides their secret scratch-off PIN. The recipient or rider enters it on the scan page (or your backend calls POST /api/v1/shipments/[id]/verify). On match, the package status updates to Verified and your webhook fires.

Authentication

All authenticated endpoints require your secret API key. You can pass it in one of two ways:

Option 1: Authorization Header (Recommended)Authorization: Bearer rec_live_8f921a4b901e23f...

Option 2: Custom Headerx-api-key: rec_live_8f921a4b901e23f...

🔒 Security: Never expose your API key in client-side browser code. Only use it in server-to-server calls from your backend (Node.js, Python, PHP, etc.). If your key is compromised, roll it immediately from Settings.

🧪 Sandbox Testing Console

Interactive REST API Playground

Test making live requests with your API key (`rec_test_...` or `rec_live_...`) directly in your browser.

Manage API Keys in Settings →

Enter Your API Key (Authorization Bearer Header):Generate Key in Settings →

💡 Tip: Use a Test Sandbox Key (`rec_test_...`) to simulate requests safely without consuming live shipment quota or broadcasting to mainnet.

Select Endpoint to Test:

Request JSON Body:

API Response Output:

Click "Execute API Request" above to test this endpoint live and inspect response output.

API Request Code Examples:

REST API Endpoint Reference

Base URL: https://userecover.xyz/api/v1

POST/shipments/create

🔑 API Key Required

Registers a new commercial shipment, reserves your monthly quota, writes a tamper-proof record to the Electroneum blockchain, and returns a unique packageId, trackingCode, RCVR-prefixed handover secret (innerSecret), and shipment object.

curl -X POST https://userecover.xyz/api/v1/shipments/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rec_live_8f921a4b901e23f..." \
  -d '{
    "packageName": "iPhone 15 Pro Dispatch",
    "weight": "0.45",
    "receiverPhone": "+2348012345678"
  }'

Request Body Parameters:

• packageName (string, required): Reference title
• receiverName (string, optional): Recipient full name
• receiverPhone (string, optional): Recipient phone number
• destination (string, optional): Destination city / area
• weight (string, optional): Weight in kg
• metadata (object, optional): Custom key-value data
• webhookUrl (string, optional): Per-shipment callback URL

200 OK Response:

• success: true
• packageId: "0x4a91b2..." (internal package ID)
• trackingCode: "RCV-4A91B2C3E8F0" (consumer-facing tracking code)
• innerSecret: "RCVR-A8F2B1C0" (8-character RCVR-prefixed hex handover secret)
• shipment: Full Shipment Object (status: "Created", metadata, events)

GET/shipments

🔑 API Key Required

Returns all shipments belonging to your merchant account, sorted by most recent first. Useful for syncing your order management system or building custom dashboards.

curl -X GET "https://userecover.xyz/api/v1/shipments" \
  -H "Authorization: Bearer rec_live_8f921a4b901e23f..."

GET/shipments/[id]/verify

Public · No Auth Required

Public endpoint for QR scan verification. Returns package weight, carrier info, current status (InTransit, Delivered, Disputed), and chain-of-custody timeline. This is the same endpoint called when anyone scans a physical QR sticker.

curl -X GET "https://userecover.xyz/api/v1/shipments/RCV-8F912A3B4C5D/verify"

POST/shipments/[id]/handover

🔑 API Key Required

Transfers package custody to a courier, rider, or warehouse handler. Updates status to "InTransit", logs an on-chain event, and fires a package.handover webhook callback.

curl -X POST "https://userecover.xyz/api/v1/shipments/RCV-8F912A3B4C5D/handover" \
  -H "Authorization: Bearer rec_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "riderName": "John Rider", "riderPhone": "+2348011223344", "location": "Ikeja Hub, Lagos" }'

POST/shipments/[id]/verify

PIN Verification

Verifies the 8-character Secret Handover PIN at physical delivery. On a match, status updates to "Verified" and a package.delivered webhook callback fires with company details.

curl -X POST "https://userecover.xyz/api/v1/shipments/RCV-8F912A3B4C5D/verify" \
  -H "Authorization: Bearer rec_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "innerSecret": "RCVR-A8F2B1C0", "location": "Lekki, Lagos" }'

GET/shipments/[id]/history

Public Timeline

Fetches the complete custody event timeline (Created, InTransit, Handover, Verified, Disputed) for a package. Passing an authorized courier PIN unlocks rider contact details.

curl -X GET "https://userecover.xyz/api/v1/shipments/RCV-8F912A3B4C5D/history"

POST/shipments/[id]/dispute

🔑 API Key Required

Files a formal delivery dispute for damaged, stolen, or missing contents. Updates package status to "Disputed", records an on-chain event, and triggers a shipment.disputed webhook.

curl -X POST "https://userecover.xyz/api/v1/shipments/RCV-8F912A3B4C5D/dispute" \
  -H "Authorization: Bearer rec_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "innerSecret": "RCVR-A8F2B1C0", "reason": "Damaged contents on arrival", "location": "Lagos" }'

GET/health

Public Health Check

Returns the real-time operational status of the REST API, MongoDB connection, Electroneum mainnet chain configuration, backend relayer configuration status, and system response latency (in ms).

curl -X GET "https://userecover.xyz/api/v1/health"

HTTP Status Codes

200Success

201Created

401Invalid API Key

402Quota Exhausted

403Not a Merchant

404Package Not Found

400Bad Request

409State Conflict

429Rate Limited

500Server Error

Real-Time Webhook Subscriptions

Receive instant HTTP POST callbacks when dispatches are created, scanned, delivered, or disputed.

Supported Event Types:

package.delivered— Triggered on successful PIN verification & delivery
shipment.disputed— Triggered when a delivery dispute is logged

Configure your target webhook URL in your Settings Page or pass a per-shipment webhookUrl in the create request body.

Example Webhook JSON Body:

{
  "event": "package.delivered",
  "timestamp": "2026-08-03T14:30:00Z",
  "data": {
    "packageId": "RCV-8F912A3B4C5D",
    "companyName": "Big Eazi Logistics",
    "shipperAddress": "0x6e799abd05b044acb6d9a59605de21ec845c2180",
    "packageName": "iPhone 15 Pro Dispatch",
    "status": "Verified",
    "recipient": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b",
    "location": "Lagos, NG",
    "onChainTxHash": "0x8f912a3b4c5d..."
  }
}

Rate Limits & Quota

Free Bootstrap100dispatches / month

Pro Starter10,000dispatches / month

Pro Growth100,000dispatches / month

Pro Scale500,000dispatches / month

When your monthly quota is exhausted on the Free tier, the API returns 402 Payment Required. Pro tiers automatically apply metered overage auto-billing ($0.02–$0.01/package). View all tier details →