Customer Integration Guide

Connect your systems to FarEye in days, not months.

Whether you're a retailer, carrier, or 3PL, and whether you ship parcels or heavy goods, this guide walks you through integrating with FarEye for order orchestration, delivery management, and real-time tracking.

1
How do you run your last-mile delivery?
Changes which APIs, setup steps, and status events you'll see throughout this guide.
2
What do you ship?
Adjusts payload examples, field guidance, VAS options, and tips shown in this guide.
3
Offer fulfillment options at checkout?
Show delivery options, EDD promises, shipping charges, and delivery slot selection (if applicable) to the customer at time of purchase on the checkout page. Use the same APIs to show relevant information on Product Display or Listing Pages (Catalogue).
4
Expose delivery slot selection to customers?
Let customers choose a specific delivery date and time window before completing their order.
4
Do deliveries involve value added services?
Installation, assembly, or old unit haul-away at the customer premises.
Your profile
Outsourced — What FarEye does
  • Carrier selection & rate comparison
  • Label & manifest generation
  • Tracking number from carrier
  • Status normalisation across carriers
  • Webhook status updates to you
  • Checkout rate, TAT & Slot APIs (if applicable)
  • VAS scheduling — installation, assembly, haul-away
What FarEye does for Insourced Use Cases
  • Label & manifest generation
  • Tracking number generation
  • Route optimisation & planning
  • Stop sequencing & driver assignment
  • Driver App for execution & ePOD
  • Real-time driver tracking & ETAs
  • Webhook status updates to you
  • Checkout slot & TAT APIs
  • Slot APIs — Get, Reserve & Confirm
  • VAS scheduling — installation, assembly, haul-away

How it works The integration in 60 seconds

You push orders to FarEye via API. FarEye selects the right carrier, generates the label & manifest, and dispatches. As the carrier moves the parcelshipment, status updates flow back to your system via webhooks.

Your System
OMS / ERP / WMS
Create order
FarEye
Orchestrate
Label + Manifest
Carrier
DHL · UPS · TNT
Status events
FarEye
Normalise
Webhook
Your System
Update order
💡
You only build two things: (1) An API call to push orders into FarEye, and (2) a webhook endpoint to receive status updates. FarEye handles carrier selection, label generation, manifest, dispatch, and tracking.

You push orders to FarEye via API. FarEye plans optimised routes, sequences stops, and assigns them to your drivers. Drivers execute deliveries via the FarEye Driver App, and status updates flow back to your system in real time.

Your System
OMS / ERP / WMS
Create order
FarEye
Plan & Optimise
Assign route
Your Drivers
FarEye App
ePOD + Status
FarEye
Track & Update
Webhook
Your System
Update order
💡
You only build two things: (1) An API call to push orders into FarEye, and (2) a webhook endpoint to receive status updates. FarEye handles route optimisation, stop sequencing, driver assignment, and real-time tracking via the Driver App.

Your use cases What you're trying to do — and how FarEye helps

Start with the first two — they cover 90% of what you need on day one.

01
Day 1You → FarEye

Send delivery orders

Push orders to FarEye. We select the right carrier, generate the shipping label & manifest, and hand it off — optimising for speed and cost across your carrier mix.including special handling for items requiring two-man delivery, installation, and time-window scheduling.
API
Create Consignment
Method
POST
FarEye does
Carrier select + Label + Manifest
Effort
~2–3 days
02
Day 1FarEye → You

Receive delivery statuses

Get real-time status events pushed to your system — picked up, in transit, out for delivery, delivered, failed, returned. FarEye normalises carrier statuses so you handle one consistent format.
Mechanism
Webhook (push)
Format
JSON over HTTPS
Events
15+ lifecycle events
Effort
~1–2 days
03
Phase 2You → FarEye

Cancel or update orders

Push order modifications or cancellations before dispatch. FarEye cascades the change to the carrier — cancelling the label and manifest if needed.
API
Update / Cancel Consignment
Method
PUT / DELETE
Window
Before carrier pickup
Effort
~1 day
04
Phase 2You → FarEye

Initiate returns

Create a reverse consignment. FarEye schedules the return pickup with the carrier, including slot booking and two-man coordination for heavy goods.
API
Create Consignment (Reverse)
Method
POST
Order Type
Reverse
Effort
~1–2 days
01
Day 1You → FarEye

Send delivery orders

Push orders as tasks. FarEye groups them into optimised routes, sequences stops, and assigns drivers — maximising drops per route and minimising drive time.factoring in time windows, vehicle capacity, two-man requirements, and installation skills.
API
Create Order
Method
POST
FarEye does
Route plan + Sequence + Assign
Effort
~2–3 days
02
Day 1FarEye → You

Receive delivery statuses

As drivers execute routes via the FarEye Driver App, status updates flow in real time — en route, arrived, delivered with ePOD (signature, photo), or failed with reason code.
Mechanism
Webhook (push)
Format
JSON over HTTPS
Events
Route + stop-level events
Effort
~1–2 days
03
Day 1FarEye manages

Route planning & optimisation

FarEye automatically groups orders into optimised routes. You control constraints — max stops, density-based clustering, vehicle capacity by weight/count.vehicle type (van/truck), time windows, driver skills, and two-man crew rules.
Managed via
FarEye Dashboard + API
Optimises for
Distance, time, capacity
Config
Rules, not code
Effort
Config only
04
Phase 2You → FarEye

Cancel, reschedule, or return

Cancel a stop from a route, reschedule to a different date, or create a reverse pickup. FarEye re-optimises the remaining route automatically.
API
Update / Cancel Task
Method
PUT / DELETE
FarEye does
Re-optimise remaining route
Effort
~1 day

Setup checklist Everything you need before your first API call

Your FarEye implementation team walks you through these steps.

  • ✓ 1
    Access token generated — Authenticates every API call. Generated and provided by FarEye.
    FarEye
  • ✓ 2
    Webhook URL configured — Provide your HTTPS endpoint. Registered in Settings → Web-hooks. Choose which order types trigger notifications.
    Engineering
  • ✓ 3
    Carrier(s) subscribed — You provide your carrier account credentials. FarEye subscribes to the carrier and configures the connection.
    FarEye
  • ✓ 4
    Carrier event mapping confirmed — Map carrier status codes to FarEye normalised statuses. Carrier Subscription → Event Mapping.
    FarEye
  • ✓ 5
    Carrier services configured — Configure how each service is handled: label generation, tracking number assignment, and cancellation. FarEye can manage these internally or delegate them to the carrier.
    FarEye
  • ✓ 6
    Test round-trip verified — Push a test consignment → carrier assigned → label generated → status webhook received at your endpoint.
    Engineering
FarEye team
Your engineering team

Your FarEye implementation team walks you through these steps.

  • ✓ 1
    Access token generated — Authenticates every API call. Generated and provided by FarEye.
    FarEye
  • ✓ 2
    Webhook URL configured — Provide your HTTPS endpoint. Registered in Settings → Web-hooks for route + stop-level events.
    Engineering
  • ✓ 3
    Service zones & territories defined — Geographic areas, operating hours, delivery windows configured in FarEye Dashboard.
    FarEye
  • ✓ 4
    Vehicle fleet registered — Vehicles with capacity, type (van/truck for bulky), and constraints.
    FarEye
  • ✓ 5
    Drivers onboarded to FarEye App — Login, skills (installation-certified, bulky-trained), working hours configured.
    Operations
  • ✓ 6
    Route planning rules configured — Max stops, time windows, vehicle-to-order matching, optimisation priorities.
    FarEye
  • ✓ 7
    Test route end-to-end verified — Push test orders → route created → driver sees stops → mark delivered → webhook received with ePOD.
    Engineering
FarEye team
Your engineering team
Your operations team

Send orders to FarEye The API call that starts everything

Every order starts with a POST to Create Consignment. FarEye selects the carrier, generates the label & manifest, and dispatches.

Create Consignment — Parcel (Outsourced)POST
POST /v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "serviceType": "Express",
    "businessUnit": "ELEX",
    "shipByDate": "2023-07-04",
    "totalWeight": 12.92,
    "totalQuantity": 1,
    "totalWeightUom": "KG",
    "totalVolume": 4221.1,
    "totalVolumeUom": "MM3",
    "paymentTobeCollected": {
      "paymentMode": "PREPAID",
      "amount": 12.12,
      "currency": "USD"
    },
    "specialInstructions": "Handle with care and take sign with customer",
    "deliveryInstructions": "Leave at the my door",
    "labelFormat": "PDF",
    "packageDetails": [
      {
        "id": "PKG9131122",
        "type": "Carton",
        "description": "TV units",
        "value": 34.44,
        "width": 3.98,
        "length": 4.12,
        "height": 2.94,
        "dimensionUom": "CM",
        "weight": 5.98,
        "weightUom": "KG",
        "volumeUom": "MM3",
        "volume": 12.01,
        "packageStatus": "AVAILABLE",
        "tags": [
          "Fragile"
        ],
        "quantity": 1,
        "instructions": "Deliver to reception desk",
        "trackingDetails": [
          {
            "trackingNumber": "TRK987654321",
            "barcode": "123456789012",
            "labelUrl": "https://cdn.customer.com/labels/TRK987654321.pdf"
          }
        ],
        "additionalInformation": {
          "key1": "PART-21082522",
          "key2": "Samsung Electronics Ltd."
        }
      }
    ],
    "additionalInformation": {
      "isSignatureRequired": false,
      "atl": false
    }
  },
  "carrier": {
    "code": "DHL"
  },
  "shipFrom": {
    "originFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": null
    },
    "pickupStartDateTime": "2025-09-06 11:30:00",
    "pickupEndDateTime": "2025-09-06 12:30:00",
    "timezone": "Asia/Kolkata"
  },
  "shipTo": {
    "destinationFacilityCode": "MUM",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "Residential",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": "PO12345"
    },
    "deliveryStartDateTime": "2025-09-27 11:30:00",
    "deliveryEndDateTime": "2025-09-27 18:30:00",
    "timezone": "Asia/Kolkata"
  }
}

Every order starts with a POST to Create Consignment. FarEye selects the carrier, generates the label & manifest, and dispatches — including two-man and installation coordination.

Create Consignment — Big & Bulky (Outsourced)POST
POST /v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "serviceType": "Express",
    "businessUnit": "ELEX",
    "shipByDate": "2023-07-04",
    "totalWeight": 12.92,
    "totalQuantity": 1,
    "totalWeightUom": "KG",
    "totalVolume": 4221.1,
    "totalVolumeUom": "MM3",
    "specialInstructions": "Handle with care and take sign with customer",
    "deliveryInstructions": "Leave at the my door",
    "labelFormat": "PDF",
    "packageDetails": [
      {
        "id": "PKG9131122",
        "type": "Carton",
        "description": "TV units",
        "value": 34.44,
        "width": 3.98,
        "length": 4.12,
        "height": 2.94,
        "dimensionUom": "CM",
        "weight": 5.98,
        "weightUom": "KG",
        "volumeUom": "MM3",
        "volume": 12.01,
        "packageStatus": "AVAILABLE",
        "tags": [
          "Fragile"
        ],
        "quantity": 1,
        "instructions": "Deliver to reception desk",
        "trackingDetails": [
          {
            "trackingNumber": "TRK987654321",
            "barcode": "123456789012",
            "labelUrl": "https://cdn.customer.com/labels/TRK987654321.pdf"
          }
        ],
        "additionalInformation": {
          "key1": "PART-21082522",
          "key2": "Samsung Electronics Ltd."
        }
      }
    ],
    "skuDetails": [
      {
        "lineItemNo": "001",
        "code": "LPN04",
        "name": "021 Reserve Cabernet Sauvignon",
        "category": "electronics",
        "deliveryServiceTime": 30,
        "pickupServiceTime": 20,
        "hsnName": "220429",
        "quantity": 6,
        "uom": "BOX",
        "unitPrice": 13.91,
        "value": 12.91,
        "weight": 2.98,
        "weightUom": "KG",
        "length": 30,
        "width": 20,
        "height": 15,
        "dimensionUom": "CM",
        "volume": 12.01,
        "volumeUom": "MM3",
        "description": "Water Bottle - Pack of Six",
        "imageUrl": "https://example.com/image.jpg",
        "packageIds": [
          "PKG9131122"
        ],
        "originCountry": "US",
        "stackable": false,
        "fragile": true,
        "vip": false,
        "hazmat": false,
        "heavyWeight": true
      }
    ],
    "vas": [
      {
        "vasCode": "ROOM_OF_CHOICE",
        "level": "SKU",
        "targetIds": [
          "001"
        ],
        "serviceTime": 5,
        "remark": "Wall-mount 55-inch TV"
      }
    ],
    "additionalInformation": {
      "isSignatureRequired": false,
      "atl": false
    }
  },
  "carrier": {
    "code": "HERMES"
  },
  "shipFrom": {
    "originFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": null
    },
    "pickupStartDateTime": "2025-09-06 11:30:00",
    "pickupEndDateTime": "2025-09-06 12:30:00",
    "timezone": "Asia/Kolkata"
  },
  "shipTo": {
    "destinationFacilityCode": "MUM",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "Residential",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": "PO12345"
    },
    "deliveryStartDateTime": "2025-09-27 11:30:00",
    "deliveryEndDateTime": "2025-09-27 18:30:00",
    "timezone": "Asia/Kolkata"
  },
  "returnTo": {
    "returnFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173
    }
  }
}

Every order starts with a POST to Create Consignment. FarEye selects the carrier, generates the label & manifest, and dispatches.

Create Consignment — Freight (Outsourced)POST
POST /v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "serviceType": "Express",
    "businessUnit": "ELEX",
    "shipByDate": "2023-07-04",
    "totalWeight": 12.92,
    "totalQuantity": 1,
    "totalWeightUom": "KG",
    "totalVolume": 4221.1,
    "totalVolumeUom": "MM3",
    "specialInstructions": "Handle with care and take sign with customer",
    "deliveryInstructions": "Leave at the my door",
    "labelFormat": "PDF",
    "packageDetails": [
      {
        "id": "PKG9131122",
        "type": "Carton",
        "description": "TV units",
        "value": 34.44,
        "width": 3.98,
        "length": 4.12,
        "height": 2.94,
        "dimensionUom": "CM",
        "weight": 5.98,
        "weightUom": "KG",
        "volumeUom": "MM3",
        "volume": 12.01,
        "packageStatus": "AVAILABLE",
        "tags": [
          "Fragile"
        ],
        "quantity": 1,
        "instructions": "Deliver to reception desk",
        "trackingDetails": [
          {
            "trackingNumber": "TRK987654321",
            "barcode": "123456789012",
            "labelUrl": "https://cdn.customer.com/labels/TRK987654321.pdf"
          }
        ],
        "additionalInformation": {
          "key1": "PART-21082522",
          "key2": "Samsung Electronics Ltd."
        }
      }
    ],
    "additionalInformation": {
      "isSignatureRequired": false,
      "atl": false
    }
  },
  "carrier": {
    "code": "DHL"
  },
  "shipFrom": {
    "originFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": null
    },
    "pickupStartDateTime": "2025-09-06 11:30:00",
    "pickupEndDateTime": "2025-09-06 12:30:00",
    "timezone": "Asia/Kolkata"
  },
  "shipTo": {
    "destinationFacilityCode": "MUM",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "Residential",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": "PO12345"
    },
    "deliveryStartDateTime": "2025-09-27 11:30:00",
    "deliveryEndDateTime": "2025-09-27 18:30:00",
    "timezone": "Asia/Kolkata"
  }
}
🚛
Freight payload — same structure as Parcels for now. Freight-specific fields (pallet count, LTL/FTL flag, BoL reference, consignment-level weight thresholds) will be documented here. Contact your FarEye implementation manager for a freight-specific field checklist.

Every delivery starts with a POST to create a task. FarEye groups tasks into optimised routes for your drivers.

Create order — Parcel (Own Fleet)POST
POST /v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "consignmentGroupId": "GROUP-2025-08-15-01",
    "routingPriority": 2,
    "serviceType": "Express",
    "businessUnit": "ELEX",
    "shipByDate": "2023-07-04",
    "totalWeight": 12.92,
    "totalQuantity": 1,
    "totalWeightUom": "KG",
    "totalVolume": 4221.1,
    "totalVolumeUom": "MM3",
    "totalPalletQuantity": 0,
    "paymentTobeCollected": {
      "paymentMode": "PREPAID",
      "amount": 12.12,
      "currency": "USD"
    },
    "specialInstructions": "Handle with care and take sign with customer",
    "deliveryInstructions": "Leave at the my door",
    "routingTags": [
      "TwoPerson"
    ],
    "routingType": "sameday_nextday",
    "labelFormat": "PDF",
    "packageDetails": [
      {
        "id": "PKG9131122",
        "type": "Carton",
        "description": "TV units",
        "value": 34.44,
        "width": 3.98,
        "length": 4.12,
        "height": 2.94,
        "dimensionUom": "CM",
        "weight": 5.98,
        "weightUom": "KG",
        "volumeUom": "MM3",
        "volume": 12.01,
        "packageStatus": "AVAILABLE",
        "tags": [
          "Fragile"
        ],
        "quantity": 1,
        "instructions": "Deliver to reception desk",
        "trackingDetails": [
          {
            "trackingNumber": "TRK987654321",
            "barcode": "123456789012",
            "labelUrl": "https://cdn.customer.com/labels/TRK987654321.pdf"
          }
        ],
        "additionalInformation": {
          "key1": "PART-21082522",
          "key2": "Samsung Electronics Ltd."
        }
      }
    ],
    "skuDetails": [
      {
        "lineItemNo": "001",
        "code": "LPN04",
        "name": "021 Reserve Cabernet Sauvignon",
        "category": "electronics",
        "deliveryServiceTime": 30,
        "pickupServiceTime": 20,
        "hsnName": "220429",
        "quantity": 6,
        "uom": "BOX",
        "unitPrice": 13.91,
        "value": 12.91,
        "weight": 2.98,
        "weightUom": "KG",
        "length": 30,
        "width": 20,
        "height": 15,
        "dimensionUom": "CM",
        "volume": 12.01,
        "volumeUom": "MM3",
        "description": "Water Bottle - Pack of Six",
        "imageUrl": "https://example.com/image.jpg",
        "packageIds": [
          "PKG9131122"
        ],
        "originCountry": "US",
        "stackable": false,
        "fragile": true,
        "vip": false,
        "hazmat": false,
        "heavyWeight": true
      }
    ],
    
    "slotToken": "a3693e24-0cc9-4ae4-9f43-23e773205019",
    "additionalInformation": {
      "isSignatureRequired": false,
      "atl": false
    },
    "stackable": false,
    "fragile": true,
    "vip": false,
    "hazmat": false,
    "heavyWeight": false,
    "scannable": true
  },
  "carrier": {
    "code": "OWNFLEET"
  },
  "shipFrom": {
    "originFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": null
    },
    "pickupStartDateTime": "2025-09-06 11:30:00",
    "pickupEndDateTime": "2025-09-06 12:30:00",
    "timezone": "Asia/Kolkata"
  },
  "shipTo": {
    "destinationFacilityCode": "MUM",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "Residential",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": "PO12345"
    },
    "deliveryStartDateTime": "2025-09-27 11:30:00",
    "deliveryEndDateTime": "2025-09-27 18:30:00",
    "timezone": "Asia/Kolkata"
  },
  "returnTo": {
    "returnFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173
    }
  }
}

Every delivery starts with a POST to create a task. FarEye groups tasks into optimised routes — matching orders to the right vehicle and driver skills.

Create order — Big & Bulky (Own Fleet)POST
POST /v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "consignmentGroupId": "GROUP-2025-08-15-01",
    "routingPriority": 2,
    "serviceType": "Express",
    "businessUnit": "ELEX",
    "shipByDate": "2023-07-04",
    "totalWeight": 12.92,
    "totalQuantity": 1,
    "totalWeightUom": "KG",
    "totalVolume": 4221.1,
    "totalVolumeUom": "MM3",
    "totalPalletQuantity": 0,
    "paymentTobeCollected": {
      "paymentMode": "PREPAID",
      "amount": 12.12,
      "currency": "USD"
    },
    "specialInstructions": "Handle with care and take sign with customer",
    "deliveryInstructions": "Leave at the my door",
    "routingTags": [
      "TwoPerson"
    ],
    "routingType": "sameday_nextday",
    "labelFormat": "PDF",
    "packageDetails": [
      {
        "id": "PKG9131122",
        "type": "Carton",
        "description": "TV units",
        "value": 34.44,
        "width": 3.98,
        "length": 4.12,
        "height": 2.94,
        "dimensionUom": "CM",
        "weight": 5.98,
        "weightUom": "KG",
        "volumeUom": "MM3",
        "volume": 12.01,
        "packageStatus": "AVAILABLE",
        "tags": [
          "Fragile"
        ],
        "quantity": 1,
        "instructions": "Deliver to reception desk",
        "trackingDetails": [
          {
            "trackingNumber": "TRK987654321",
            "barcode": "123456789012",
            "labelUrl": "https://cdn.customer.com/labels/TRK987654321.pdf"
          }
        ],
        "additionalInformation": {
          "partNumber": "PART-21082522",
          "manufacturerInfo": "Samsung Electronics Ltd."
        }
      }
    ],
    "skuDetails": [
      {
        "lineItemNo": "001",
        "code": "LPN04",
        "name": "021 Reserve Cabernet Sauvignon",
        "category": "electronics",
        "deliveryServiceTime": 30,
        "pickupServiceTime": 20,
        "hsnName": "220429",
        "quantity": 6,
        "uom": "BOX",
        "unitPrice": 13.91,
        "value": 12.91,
        "weight": 2.98,
        "weightUom": "KG",
        "length": 30,
        "width": 20,
        "height": 15,
        "dimensionUom": "CM",
        "volume": 12.01,
        "volumeUom": "MM3",
        "description": "Water Bottle - Pack of Six",
        "imageUrl": "https://example.com/image.jpg",
        "packageIds": [
          "PKG9131122"
        ],
        "originCountry": "US",
        "stackable": false,
        "fragile": true,
        "vip": false,
        "hazmat": false,
        "heavyWeight": true
      }
    ],
    "vas": [
      {
        "vasCode": "ROOM_OF_CHOICE",
        "level": "SKU",
        "targetIds": [
          "001"
        ],
        "serviceTime": 5,
        "remark": "Wall-mount 55-inch TV"
      }
    ],
    "slotToken": "a3693e24-0cc9-4ae4-9f43-23e773205019",
    "additionalInformation": {
      "isSignatureRequired": false,
      "atl": false
    },
    "stackable": false,
    "fragile": true,
    "vip": false,
    "hazmat": false,
    "heavyWeight": false,
    "scannable": true
  },
  "carrier": {
    "code": "OWNFLEET"
  },
  "shipFrom": {
    "originFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": null
    },
    "pickupStartDateTime": "2025-09-06 11:30:00",
    "pickupEndDateTime": "2025-09-06 12:30:00",
    "timezone": "Asia/Kolkata"
  },
  "shipTo": {
    "destinationFacilityCode": "MUM",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "Residential",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173,
      "poBoxNumber": "PO12345"
    },
    "deliveryStartDateTime": "2025-09-27 11:30:00",
    "deliveryEndDateTime": "2025-09-27 18:30:00",
    "timezone": "Asia/Kolkata"
  },
  "returnTo": {
    "returnFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "secondaryContactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "code": "HDC001",
      "line1": "620 North LaSalle Drive",
      "line2": "Apt 24, Building B",
      "line3": "Chicago, IL 60654",
      "landmark": "Near Lotus Garden",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "county": "Cook",
      "country": "US",
      "latitude": 41.8929706,
      "longitude": -87.6330173
    }
  }
}

Every delivery starts with a POST to create a task. FarEye groups tasks into optimised routes for your drivers.

Create order — Freight (Own Fleet)POST
POST /v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "consignmentGroupId": "GROUP-2025-08-15-01",
    "routingPriority": 2,
    "serviceType": "Express",
    "businessUnit": "ELEX",
    "shipByDate": "2023-07-04",
    "totalWeight": 12.92,
    "totalQuantity": 1,
    "totalWeightUom": "KG",
    "totalVolume": 4221.1,
    "totalVolumeUom": "MM3",
    "specialInstructions": "Handle with care",
    "deliveryInstructions": "Deliver to loading bay",
    "labelFormat": "PDF",
    "packageDetails": [
      {
        "id": "PKG9131122",
        "type": "Carton",
        "description": "TV units",
        "value": 34.44,
        "width": 3.98,
        "length": 4.12,
        "height": 2.94,
        "dimensionUom": "CM",
        "weight": 5.98,
        "weightUom": "KG",
        "volumeUom": "MM3",
        "volume": 12.01,
        "packageStatus": "AVAILABLE",
        "quantity": 1,
        "instructions": "Deliver to loading bay",
        "trackingDetails": [
          {
            "trackingNumber": "TRK987654321",
            "barcode": "123456789012",
            "labelUrl": "https://cdn.customer.com/labels/TRK987654321.pdf"
          }
        ],
        "additionalInformation": {
          "key1": "PART-21082522",
          "key2": "Samsung Electronics Ltd."
        }
      }
    ],
    "additionalInformation": {
      "isSignatureRequired": false,
      "atl": false
    }
  },
  "shipFrom": {
    "originFacilityCode": "DEL",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "email": "xyz@company.com",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "line1": "620 North LaSalle Drive",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "country": "US"
    },
    "pickupStartDateTime": "2025-09-06 11:30:00",
    "pickupEndDateTime": "2025-09-06 12:30:00",
    "timezone": "Asia/Kolkata"
  },
  "shipTo": {
    "destinationFacilityCode": "MUM",
    "contact": {
      "name": "Vasu",
      "contactNumber": "0123456789",
      "companyName": "Elex Pvt Ltd"
    },
    "address": {
      "type": "FACILITY",
      "line1": "620 North LaSalle Drive",
      "city": "Chicago",
      "state": "IL",
      "pincode": "60654",
      "country": "US"
    },
    "deliveryStartDateTime": "2025-09-27 11:30:00",
    "deliveryEndDateTime": "2025-09-27 18:30:00",
    "timezone": "Asia/Kolkata"
  }
}
🚛
Freight payload — same structure as Parcels for now. Freight-specific fields will be documented here. Contact your FarEye implementation manager for a freight-specific field checklist.

Mandatory & recommended fields

CD Consignment Details · consignmentDetails 9 mandatory
Field Required Description
referenceNumber
consignmentDetails.referenceNumber
 Mandatory Your internal reference ID. Correlates all webhook status updates to your system. Must be unique per order.
orderNumber
consignmentDetails.orderNumber
 Mandatory Your platform's order number. Cross-references orders between your OMS and FarEye.
consignmentNumber
consignmentDetails.consignmentNumber
 Mandatory Unique consignment identifier within FarEye. Used for tracking and label generation.
consignmentType
consignmentDetails.consignmentType
 Mandatory FORWARD (delivery) or REVERSE (return). Determines the carrier service direction.
serviceType
consignmentDetails.serviceType
 Mandatory Carrier service level, e.g. Express, Standard, Economy. Must match a service configured in FarEye for the selected carrier.
shipByDate
consignmentDetails.shipByDate
 Mandatory Date the order must leave the warehouse. Format: YYYY-MM-DD. Drives carrier selection and SLA calculation.
totalWeight
consignmentDetails.totalWeight
 Mandatory Total consignment weight. Used for carrier rate calculation.
totalWeightUom
consignmentDetails.totalWeightUom
 Mandatory Weight unit of measure. Accepted values: KG, LB.
totalQuantity
consignmentDetails.totalQuantity
 Mandatory Total number of packages in the consignment.
businessUnit
consignmentDetails.businessUnit
 Recommended Business unit code. Required for multi-BU accounts to route to the correct carrier contracts.
totalVolume / totalVolumeUom
consignmentDetails.totalVolume / totalVolumeUom
 Recommended Total volume and unit (e.g. MM3). Used for volumetric rate calculation.
specialInstructions
consignmentDetails.specialInstructions
 Recommended Handling instructions passed to the carrier (e.g. fragile, keep upright, signature required).
deliveryInstructions
consignmentDetails.deliveryInstructions
 Recommended Delivery-specific instructions for the driver (e.g. leave at door, call before delivery).
paymentTobeCollected
consignmentDetails.paymentTobeCollected
 Optional Required for COD orders. Object with paymentMode (PREPAID or COD), amount, and currency.
labelFormat
consignmentDetails.labelFormat
 Optional Label output format. PDF (default) or ZPL for thermal printers.
PD Package Details · consignmentDetails.packageDetails[] 7 mandatory
Field Required Description
id
packageDetails[].id
 Mandatory Unique package identifier. Used for per-package tracking and label generation.
type
packageDetails[].type
 Mandatory Package unit type, e.g. Carton, Pallet, Envelope. Drives carrier rate calculation.
length / width / height
packageDetails[].length / width / height
 Mandatory Package dimensions. Used for volumetric weight and carrier rate selection.
dimensionUom
packageDetails[].dimensionUom
 Mandatory Dimension unit of measure. Accepted values: CM, IN.
weight
packageDetails[].weight
 Mandatory Per-package weight. Used alongside total weight for carrier billing and manifest generation.
weightUom
packageDetails[].weightUom
 Mandatory Per-package weight unit. Accepted values: KG, LB.
quantity
packageDetails[].quantity
 Mandatory Number of units in this package entry.
description
packageDetails[].description
 Recommended Human-readable description of package contents. Printed on shipping label and customs docs.
value
packageDetails[].value
 Recommended Declared value of contents. Required for insurance and customs declarations.
tags
packageDetails[].tags
 Optional Array of handling tags, e.g. ["Fragile"]. Displayed on labels and passed to carriers.
instructions
packageDetails[].instructions
 Optional Per-package delivery instructions. Overrides consignment-level instructions for this package.
trackingDetails
packageDetails[].trackingDetails[]
 Optional Array of tracking objects. Each entry: trackingNumber, barcode, labelUrl. Pre-populate if labels are generated externally.
additionalInformation
packageDetails[].additionalInformation
 Optional Free-form key-value map for custom metadata (e.g. part numbers, manufacturer info).
CR Carrier · carrier 1 mandatory
Field Required Description
code
carrier.code
 Mandatory Carrier identifier configured in FarEye, e.g. DHL, HERMES, OWNFLEET. Maps the consignment to the correct rate card and service rules.
SF Ship From · shipFrom 8 mandatory
Field Required Description
contact.name
shipFrom.contact.name
 Mandatory Sender / warehouse contact name. Printed on the shipping label and shared with the carrier.
contact.contactNumber
shipFrom.contact.contactNumber
 Mandatory Sender's phone number. Used by the carrier for pickup coordination.
address.line1
shipFrom.address.line1
 Mandatory Primary street address of the origin location.
address.city
shipFrom.address.city
 Mandatory City of the origin location.
address.pincode
shipFrom.address.pincode
 Mandatory Postal / ZIP code. Used for carrier zone determination and rate calculation.
address.country
shipFrom.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format (e.g. US, IN).
pickupStartDateTime
shipFrom.pickupStartDateTime
 Recommended Earliest time the carrier can collect. Format: YYYY-MM-DD HH:MM:SS.
pickupEndDateTime
shipFrom.pickupEndDateTime
 Recommended Latest time the carrier can collect. Defines the pickup window.
originFacilityCode
shipFrom.originFacilityCode
 Recommended Origin hub or facility code configured in FarEye. Enables address auto-fill and facility-based carrier rules.
contact.email
shipFrom.contact.email
 Recommended Sender's email. Used for dispatch confirmations and exception notifications.
contact.companyName
shipFrom.contact.companyName
 Recommended Sender's company name. Printed on the label and shared with the carrier.
timezone
shipFrom.timezone
 Recommended IANA timezone for pickup date/time (e.g. Asia/Kolkata). Ensures correct SLA calculation across regions.
address.latitude / longitude
shipFrom.address.latitude / longitude
 Optional Geo-coordinates of the origin. Improves address matching accuracy.
address.type
shipFrom.address.type
 Optional Address classification: FACILITY or Residential.
ST Ship To · shipTo 8 mandatory
Field Required Description
contact.name
shipTo.contact.name
 Mandatory Recipient name. Printed on label and used for delivery notifications.
contact.contactNumber
shipTo.contact.contactNumber
 Mandatory Recipient's phone number. Mandatory — used for delivery notifications and carrier contact.
address.line1
shipTo.address.line1
 Mandatory Primary delivery street address.
address.city
shipTo.address.city
 Recommended Delivery city.
address.pincode
shipTo.address.pincode
 Mandatory Postal / ZIP code of the delivery location.
address.county
shipTo.address.pincode
 Mandatory Suburb/county of the delivery location.
address.country
shipTo.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format.
destinationFacilityCode
shipTo.destinationFacilityCode
 Recommended Destination hub or facility code. Used to pre-assign last-mile carrier or delivery zone.
contact.email
shipTo.contact.email
 Recommended Recipient's email for delivery notifications and tracking link delivery.
address.type
shipTo.address.type
 Recommended Address classification: Residential or FACILITY. Carriers may apply different rates per type.
deliveryStartDateTime
shipTo.deliveryStartDateTime
 Recommended Earliest acceptable delivery time. Format: YYYY-MM-DD HH:MM:SS.
deliveryEndDateTime
shipTo.deliveryEndDateTime
 Recommended Latest acceptable delivery time. Defines the delivery window for the carrier.
timezone
shipTo.timezone
 Recommended IANA timezone for delivery date/time. Ensures SLA windows are interpreted correctly.
address.latitude / longitude
shipTo.address.latitude / longitude
 Optional Geo-coordinates of the delivery location. Improves address matching and route optimization.
address.poBoxNumber
shipTo.address.poBoxNumber
 Optional PO Box number for carriers that support PO Box delivery.
RT Return To · returnTo 0 mandatory
Field Required Description
returnFacilityCode
returnTo.returnFacilityCode
 Recommended Return hub or facility code configured in FarEye. Auto-fills address from facility master data. Preferred over specifying the full address manually.
contact.name
returnTo.contact.name
 Recommended Contact name at the return facility.
contact.contactNumber
returnTo.contact.contactNumber
 Recommended Phone number at the return facility. Used by the carrier for drop-off coordination.
address.line1
returnTo.address.line1
 Recommended Street address of the return location. Required if returnFacilityCode is not provided.
address.city
returnTo.address.city
 Recommended City of the return location.
address.pincode
returnTo.address.pincode
 Recommended Postal / ZIP code of the return location.
address.country
returnTo.address.country
 Recommended Country code in ISO 3166-1 alpha-2 format.
contact.email
returnTo.contact.email
 Optional Email at the return facility. Used for return confirmation notifications.
contact.companyName
returnTo.contact.companyName
 Optional Company name at the return facility.
address.type
returnTo.address.type
 Optional Address classification: FACILITY or Residential.
address.state
returnTo.address.state
 Optional State / province of the return location.
address.latitude / longitude
returnTo.address.latitude / longitude
 Optional Geo-coordinates of the return location. Improves address matching accuracy.
CD Consignment Details · consignmentDetails 11 mandatory
Field Required Description
referenceNumber
consignmentDetails.referenceNumber
 Mandatory Your internal reference ID. Correlates all webhook status updates to your system. Must be unique per order.
orderNumber
consignmentDetails.orderNumber
 Mandatory Your platform's order number. Cross-references orders between your OMS and FarEye.
consignmentNumber
consignmentDetails.consignmentNumber
 Mandatory Unique consignment identifier within FarEye. Used for tracking and label generation.
consignmentType
consignmentDetails.consignmentType
 Mandatory FORWARD (delivery) or REVERSE (return). Determines the carrier service direction.
serviceType
consignmentDetails.serviceType
 Mandatory Carrier service level, e.g. White Glove, Two-Man, Standard. Must match a service configured in FarEye for the selected carrier.
shipByDate
consignmentDetails.shipByDate
 Mandatory Date the order must leave the warehouse. Format: YYYY-MM-DD. Drives carrier selection and SLA calculation.
totalWeight
consignmentDetails.totalWeight
 Mandatory Total consignment weight. Critical for bulky carrier rate calculation and vehicle matching.
totalWeightUom
consignmentDetails.totalWeightUom
 Mandatory Weight unit of measure. Accepted values: KG, LB.
totalQuantity
consignmentDetails.totalQuantity
 Mandatory Total number of packages in the consignment.
totalVolume / totalVolumeUom
consignmentDetails.totalVolume / totalVolumeUom
 Mandatory Total volume and unit (e.g. MM3, CM3). Required for big & bulky — incorrect or missing volume causes carrier mis-quoting.
specialInstructions
consignmentDetails.specialInstructions
 Mandatory Handling instructions for the carrier (e.g. two-man lift, installation required, fragile). Missing instructions lead to failed deliveries when a single driver arrives for a two-man job.
businessUnit
consignmentDetails.businessUnit
 Recommended Business unit code. Required for multi-BU accounts to route to the correct carrier contracts.
deliveryInstructions
consignmentDetails.deliveryInstructions
 Recommended Delivery-specific instructions for the driver (e.g. call before delivery, floor level, access code).
paymentTobeCollected
consignmentDetails.paymentTobeCollected
 Optional Required for COD orders. Object with paymentMode (PREPAID or COD), amount, and currency.
labelFormat
consignmentDetails.labelFormat
 Optional Label output format. PDF (default) or ZPL for thermal printers.
PD Package Details · consignmentDetails.packageDetails[] 9 mandatory
Field Required Description
id
packageDetails[].id
 Mandatory Unique package identifier. Used for per-package tracking and label generation.
type
packageDetails[].type
 Mandatory Package unit type, e.g. Pallet, Crate, Carton. Drives carrier rate calculation for bulky items.
length / width / height
packageDetails[].length / width / height
 Mandatory Package dimensions. Critical for bulky items — missing dimensions cause incorrect carrier quoting and vehicle mis-matching.
dimensionUom
packageDetails[].dimensionUom
 Mandatory Dimension unit of measure. Accepted values: CM, IN.
weight
packageDetails[].weight
 Mandatory Per-package weight. Used alongside total weight for carrier billing and vehicle load planning.
weightUom
packageDetails[].weightUom
 Mandatory Per-package weight unit. Accepted values: KG, LB.
quantity
packageDetails[].quantity
 Mandatory Number of units in this package entry.
volume / volumeUom
packageDetails[].volume / volumeUom
 Mandatory Per-package volume and unit (e.g. MM3, CM3). Required for big & bulky to ensure accurate carrier quoting and vehicle fill rate.
description
packageDetails[].description
 Mandatory Human-readable description of package contents (e.g. Washing Machine, Sofa 3-Seater). Printed on shipping label and required for bulky carrier manifests.
value
packageDetails[].value
 Recommended Declared value of contents. Required for insurance and customs declarations.
tags
packageDetails[].tags
 Recommended Array of handling tags, e.g. ["Fragile", "Do Not Stack", "This Side Up"]. Displayed on labels and passed to carriers.
instructions
packageDetails[].instructions
 Recommended Per-package handling instructions (e.g. keep upright, tail-lift required). Overrides consignment-level instructions for this package.
trackingDetails
packageDetails[].trackingDetails[]
 Optional Array of tracking objects. Each entry: trackingNumber, barcode, labelUrl. Pre-populate if labels are generated externally.
additionalInformation
packageDetails[].additionalInformation
 Optional Free-form key-value map for custom metadata (e.g. assembly notes, SKU details).
SK SKU Details · consignmentDetails.skuDetails[] 0 mandatory
Field Required Description
code
skuDetails[].code
 Recommended Your SKU / product code. Used for customs declarations and order reconciliation.
name
skuDetails[].name
 Recommended Product name. Printed on customs documentation and manifests.
quantity
skuDetails[].quantity
 Recommended Item quantity. Must match the sum of units in the linked package.
unitPrice / value
skuDetails[].unitPrice / value
 Recommended Unit price and total declared value. Required for customs declarations and insurance.
packageIds
skuDetails[].packageIds[]
 Recommended Array of package IDs this SKU belongs to. Links SKU to the correct packageDetails[] entry.
lineItemNo
skuDetails[].lineItemNo
 Optional Order line item number. Used to correlate SKUs back to your OMS line items.
category
skuDetails[].category
 Optional Product category (e.g. electronics, furniture). Used for carrier service rule matching.
hsnName
skuDetails[].hsnName
 Optional HSN / tariff code. Required for cross-border shipments and customs declarations.
originCountry
skuDetails[].originCountry
 Optional Country of origin in ISO 3166-1 alpha-2 format. Required for international customs.
weight / weightUom
skuDetails[].weight / weightUom
 Optional Per-SKU weight and unit. Used for customs and compliance checks.
length / width / height / dimensionUom
skuDetails[].length / width / height / dimensionUom
 Optional Per-SKU dimensions with unit. Used for volumetric calculations and customs documentation.
volume / volumeUom
skuDetails[].volume / volumeUom
 Optional Per-SKU volume and unit.
description
skuDetails[].description
 Optional Product description. Included in customs documentation and carrier manifests.
imageUrl
skuDetails[].imageUrl
 Optional URL of the product image. Displayed in the FarEye Dashboard for identification.
uom
skuDetails[].uom
 Optional Unit of measure for the item, e.g. BOX, EACH, PAIR.
deliveryServiceTime / pickupServiceTime
skuDetails[].deliveryServiceTime / pickupServiceTime
 Optional Estimated service time in minutes at delivery / pickup stop. Influences route optimiser dwell time.
fragile / stackable / hazmat / heavyWeight / vip
skuDetails[].fragile / stackable / hazmat / heavyWeight / vip
 Optional Boolean handling flags. Surfaced in the FarEye Driver App and passed to carriers that support them.
VA Value-Added Services · vas[] 0 mandatory
Field Required Description
vasCode
vas[].vasCode
 Recommended Service code identifying the value-added service, e.g. ROOM_OF_CHOICE, TWO_MAN_DELIVERY, HAUL_AWAY_OLD, INSTALLATION. Carrier must support the service.
level
vas[].level
 Recommended Scope of the service: SKU (applies to specific items identified in targetIds) or CONSIGNMENT (applies to the whole shipment).
targetIds
vas[].targetIds[]
 Recommended Array of SKU line item numbers or package IDs this VAS applies to. Required when level is SKU.
serviceTime
vas[].serviceTime
 Recommended Estimated time in minutes at the stop for this service (e.g. 30 for installation). Influences route optimiser dwell time.
remark
vas[].remark
 Optional Free-text instruction for the driver or carrier (e.g. Wall-mount 55-inch TV).
CR Carrier · carrier 1 mandatory
Field Required Description
code
carrier.code
 Mandatory Carrier identifier configured in FarEye, e.g. XDP, OWNFLEET. Must support big & bulky service capabilities. Maps the consignment to the correct rate card and service rules.
SF Ship From · shipFrom 8 mandatory
Field Required Description
contact.name
shipFrom.contact.name
 Mandatory Sender / warehouse contact name. Printed on the shipping label and shared with the carrier.
contact.contactNumber
shipFrom.contact.contactNumber
 Mandatory Sender's phone number. Used by the carrier for pickup coordination.
address.line1
shipFrom.address.line1
 Mandatory Primary street address of the origin location.
address.city
shipFrom.address.city
 Mandatory City of the origin location.
address.pincode
shipFrom.address.pincode
 Mandatory Postal / ZIP code. Used for carrier zone determination and rate calculation.
address.country
shipFrom.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format (e.g. US, IN).
pickupStartDateTime
shipFrom.pickupStartDateTime
 Mandatory Earliest time the carrier can collect. Format: YYYY-MM-DD HH:MM:SS. Strongly recommended for bulky to coordinate driver and vehicle availability.
pickupEndDateTime
shipFrom.pickupEndDateTime
 Mandatory Latest time the carrier can collect. Defines the pickup window. Required for bulky — open-ended pickup windows cause scheduling failures.
originFacilityCode
shipFrom.originFacilityCode
 Recommended Origin hub or facility code configured in FarEye. Enables address auto-fill and facility-based carrier rules.
contact.email
shipFrom.contact.email
 Recommended Sender's email. Used for dispatch confirmations and exception notifications.
contact.companyName
shipFrom.contact.companyName
 Recommended Sender's company name. Printed on the label and shared with the carrier.
timezone
shipFrom.timezone
 Recommended IANA timezone for pickup date/time (e.g. Asia/Kolkata). Ensures correct SLA calculation across regions.
address.latitude / longitude
shipFrom.address.latitude / longitude
 Optional Geo-coordinates of the origin. Improves address matching accuracy.
address.type
shipFrom.address.type
 Optional Address classification: FACILITY or Residential.
ST Ship To · shipTo 8 mandatory
Field Required Description
contact.name
shipTo.contact.name
 Mandatory Recipient name. Printed on label and used for delivery notifications.
contact.contactNumber
shipTo.contact.contactNumber
 Mandatory Recipient's phone number. Mandatory — used for pre-delivery call and carrier contact for bulky deliveries.
address.line1
shipTo.address.line1
 Mandatory Primary delivery street address.
address.pincode
shipTo.address.pincode
 Mandatory Postal / ZIP code of the delivery location.
address.county
shipTo.address.county
 Mandatory Suburb/county of the delivery location.
address.country
shipTo.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format.
deliveryStartDateTime
shipTo.deliveryStartDateTime
 Mandatory Earliest acceptable delivery time. Format: YYYY-MM-DD HH:MM:SS. Required for bulky — customers must be home for large item delivery.
deliveryEndDateTime
shipTo.deliveryEndDateTime
 Mandatory Latest acceptable delivery time. Defines the delivery window. Required for bulky — open windows cause failed delivery attempts.
destinationFacilityCode
shipTo.destinationFacilityCode
 Recommended Destination hub or facility code. Used to pre-assign last-mile carrier or delivery zone.
contact.email
shipTo.contact.email
 Recommended Recipient's email for delivery notifications and tracking link delivery.
address.type
shipTo.address.type
 Recommended Address classification: Residential or FACILITY. Carriers may apply different rates and crew requirements per type.
timezone
shipTo.timezone
 Recommended IANA timezone for delivery date/time. Ensures SLA windows are interpreted correctly.
address.city
shipTo.address.city
 Recommended Delivery city. Improves address matching and carrier zone determination for bulky items.
address.latitude / longitude
shipTo.address.latitude / longitude
 Optional Geo-coordinates of the delivery location. Improves address matching and route optimisation.
address.poBoxNumber
shipTo.address.poBoxNumber
 Optional PO Box number for carriers that support PO Box delivery.
RT Return To · returnTo 0 mandatory
Field Required Description
returnFacilityCode
returnTo.returnFacilityCode
 Recommended Return hub or facility code configured in FarEye. Auto-fills address from facility master data. Preferred over specifying the full address manually.
contact.name
returnTo.contact.name
 Recommended Contact name at the return facility.
contact.contactNumber
returnTo.contact.contactNumber
 Recommended Phone number at the return facility. Used by the carrier for drop-off coordination.
address.line1
returnTo.address.line1
 Recommended Street address of the return location. Required if returnFacilityCode is not provided.
address.city
returnTo.address.city
 Recommended City of the return location.
address.pincode
returnTo.address.pincode
 Recommended Postal / ZIP code of the return location.
address.country
returnTo.address.country
 Recommended Country code in ISO 3166-1 alpha-2 format.
contact.email
returnTo.contact.email
 Optional Email at the return facility. Used for return confirmation notifications.
contact.companyName
returnTo.contact.companyName
 Optional Company name at the return facility.
address.type
returnTo.address.type
 Optional Address classification: FACILITY or Residential.
address.state
returnTo.address.state
 Optional State / province of the return location.
address.latitude / longitude
returnTo.address.latitude / longitude
 Optional Geo-coordinates of the return location. Improves address matching accuracy.
CD Consignment Details · consignmentDetails 9 mandatory
Field Required Description
referenceNumber
consignmentDetails.referenceNumber
 Mandatory Your internal reference ID. Correlates all webhook status updates to your system. Must be unique per order.
orderNumber
consignmentDetails.orderNumber
 Mandatory Your platform's order number. Cross-references orders between your OMS and FarEye.
consignmentNumber
consignmentDetails.consignmentNumber
 Mandatory Unique consignment identifier within FarEye. Used for task creation and driver dispatch.
consignmentType
consignmentDetails.consignmentType
 Mandatory FORWARD (delivery) or REVERSE (return/pickup). Determines routing direction and driver workflow.
serviceType
consignmentDetails.serviceType
 Mandatory Service level, e.g. Express, Standard, Economy. Must match a service configured in FarEye. Determines driver skill match and SLA grouping.
shipByDate
consignmentDetails.shipByDate
 Mandatory Date the order must leave the warehouse. Format: YYYY-MM-DD. FarEye groups all orders for the same date when building routes.
totalWeight
consignmentDetails.totalWeight
 Mandatory Total consignment weight. Used for vehicle load planning and driver assignment.
totalWeightUom
consignmentDetails.totalWeightUom
 Mandatory Weight unit of measure. Accepted values: KG, LB.
totalQuantity
consignmentDetails.totalQuantity
 Mandatory Total number of packages in the consignment. Drives vehicle capacity planning.
businessUnit
consignmentDetails.businessUnit
 Recommended Business unit code. Required for multi-BU accounts to route to the correct service area and driver pool.
totalVolume / totalVolumeUom
consignmentDetails.totalVolume / totalVolumeUom
 Recommended Total volume and unit (e.g. CBM, MM3). Helps the route optimiser calculate vehicle fill rate accurately.
specialInstructions
consignmentDetails.specialInstructions
 Recommended Handling instructions for the driver (e.g. fragile, keep upright, signature required).
deliveryInstructions
consignmentDetails.deliveryInstructions
 Recommended Delivery-specific instructions for the driver (e.g. leave at door, call before delivery, access code).
paymentTobeCollected
consignmentDetails.paymentTobeCollected
 Optional Required for COD orders. Object with paymentMode (PREPAID or COD), amount, and currency.
PD Package Details · consignmentDetails.packageDetails[] 7 mandatory
Field Required Description
id
packageDetails[].id
 Mandatory Unique package identifier. Used for per-package tracking and ePOD matching.
type
packageDetails[].type
 Mandatory Package unit type, e.g. Carton, Envelope, Bag. Used for vehicle load matching.
length / width / height
packageDetails[].length / width / height
 Recommended Package dimensions. Used for volumetric weight and vehicle capacity optimisation.
dimensionUom
packageDetails[].dimensionUom
 Recommended Dimension unit of measure. Accepted values: CM, IN.
weight
packageDetails[].weight
 Mandatory Per-package weight. Used for vehicle load planning and route optimisation.
weightUom
packageDetails[].weightUom
 Mandatory Per-package weight unit. Accepted values: KG, LB.
quantity
packageDetails[].quantity
 Mandatory Number of units in this package entry.
description
packageDetails[].description
 Recommended Human-readable description of package contents. Shown in driver app and ePOD.
volume / volumeUom
packageDetails[].volume / volumeUom
 Recommended Per-package volume and unit. Helps the route optimiser calculate vehicle fill rate accurately.
value
packageDetails[].value
 Recommended Declared value of contents. Used for insurance and ePOD documentation.
tags
packageDetails[].tags
 Optional Array of handling tags, e.g. ["Fragile"]. Displayed in driver app at the stop.
instructions
packageDetails[].instructions
 Optional Per-package delivery instructions. Overrides consignment-level instructions for this package.
additionalInformation
packageDetails[].additionalInformation
 Optional Free-form key-value map for custom metadata (e.g. part numbers, manufacturer info).
CR Carrier · carrier 1 mandatory
Field Required Description
code
carrier.code
 Mandatory Carrier identifier configured in FarEye, e.g. DHL, HERMES, OWNFLEET. Maps the consignment to the correct rate card and service rules.
SF Ship From · shipFrom 6 mandatory
Field Required Description
contact.name
shipFrom.contact.name
 Mandatory Sender / warehouse contact name. Shown in driver app for pickup reference.
contact.contactNumber
shipFrom.contact.contactNumber
 Mandatory Sender's phone number. Used by the driver for pickup coordination.
address.line1
shipFrom.address.line1
 Mandatory Primary street address of the origin location.
address.city
shipFrom.address.city
 Mandatory City of the origin location. Used for route zone determination.
address.pincode
shipFrom.address.pincode
 Mandatory Postal / ZIP code. Used for service zone determination and route clustering.
address.country
shipFrom.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format (e.g. US, IN).
pickupStartDateTime
shipFrom.pickupStartDateTime
 Recommended Earliest time for pickup. Format: YYYY-MM-DD HH:MM:SS. Used by the route optimiser for stop sequencing.
pickupEndDateTime
shipFrom.pickupEndDateTime
 Recommended Latest time for pickup. Defines the pickup window for route planning.
originFacilityCode
shipFrom.originFacilityCode
 Recommended Origin hub or facility code configured in FarEye. Enables address auto-fill and facility-based routing rules.
contact.email
shipFrom.contact.email
 Recommended Sender's email. Used for dispatch confirmations.
contact.companyName
shipFrom.contact.companyName
 Recommended Sender's company name. Shown to driver in the FarEye Driver App.
timezone
shipFrom.timezone
 Recommended IANA timezone for pickup date/time (e.g. Asia/Kolkata). Ensures correct SLA calculation across regions.
address.latitude / longitude
shipFrom.address.latitude / longitude
 Optional Geo-coordinates of the origin. Improves address matching and route optimisation accuracy.
address.type
shipFrom.address.type
 Optional Address classification: FACILITY or Residential.
ST Ship To · shipTo 6 mandatory
Field Required Description
contact.name
shipTo.contact.name
 Mandatory Recipient name. Shown in driver app and used for delivery notifications.
contact.contactNumber
shipTo.contact.contactNumber
 Mandatory Recipient's phone number. Mandatory — used for delivery notifications and driver contact.
address.line1
shipTo.address.line1
 Mandatory Primary delivery street address.
address.pincode
shipTo.address.pincode
 Mandatory Postal / ZIP code. Used for service zone matching and route clustering.
address.county
shipTo.address.county
 Mandatory Suburb/county of the delivery location. Used for route zone determination.
address.country
shipTo.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format.
address.city
shipTo.address.city
 Recommended Delivery city. Improves address matching and route zone determination.
deliveryStartDateTime
shipTo.deliveryStartDateTime
 Recommended Earliest acceptable delivery time. Format: YYYY-MM-DD HH:MM:SS. The route optimiser respects this window when sequencing stops.
deliveryEndDateTime
shipTo.deliveryEndDateTime
 Recommended Latest acceptable delivery time. Defines the customer delivery window.
destinationFacilityCode
shipTo.destinationFacilityCode
 Recommended Destination hub or facility code. Used to pre-assign delivery zone and driver pool.
contact.email
shipTo.contact.email
 Recommended Recipient's email for delivery notifications and tracking link delivery.
address.type
shipTo.address.type
 Recommended Address classification: Residential or FACILITY. Affects driver instructions and route sequencing.
timezone
shipTo.timezone
 Recommended IANA timezone for delivery date/time. Ensures SLA windows are interpreted correctly.
address.latitude / longitude
shipTo.address.latitude / longitude
 Optional Geo-coordinates of the delivery location. Improves address matching and route optimisation.
address.poBoxNumber
shipTo.address.poBoxNumber
 Optional PO Box number where applicable.
RT Return To · returnTo 0 mandatory
Field Required Description
returnFacilityCode
returnTo.returnFacilityCode
 Recommended Return hub or facility code configured in FarEye. Auto-fills address from facility master data. Preferred over specifying the full address manually.
contact.name
returnTo.contact.name
 Recommended Contact name at the return facility.
contact.contactNumber
returnTo.contact.contactNumber
 Recommended Phone number at the return facility. Used by the carrier for drop-off coordination.
address.line1
returnTo.address.line1
 Recommended Street address of the return location. Required if returnFacilityCode is not provided.
address.city
returnTo.address.city
 Recommended City of the return location.
address.pincode
returnTo.address.pincode
 Recommended Postal / ZIP code of the return location.
address.country
returnTo.address.country
 Recommended Country code in ISO 3166-1 alpha-2 format.
contact.email
returnTo.contact.email
 Optional Email at the return facility. Used for return confirmation notifications.
contact.companyName
returnTo.contact.companyName
 Optional Company name at the return facility.
address.type
returnTo.address.type
 Optional Address classification: FACILITY or Residential.
address.state
returnTo.address.state
 Optional State / province of the return location.
address.latitude / longitude
returnTo.address.latitude / longitude
 Optional Geo-coordinates of the return location. Improves address matching accuracy.
📦
Parcel tip: For standard parcels, the mandatory fields above are usually sufficient. Include Weight and Item Count — dimensions are optional for small packages but help the route optimiser with vehicle fill rate.
CD Consignment Details · consignmentDetails 11 mandatory
Field Required Description
referenceNumber
consignmentDetails.referenceNumber
 Mandatory Your internal reference ID. Correlates all webhook status updates to your system. Must be unique per order.
orderNumber
consignmentDetails.orderNumber
 Mandatory Your platform's order number. Cross-references orders between your OMS and FarEye.
consignmentNumber
consignmentDetails.consignmentNumber
 Mandatory Unique consignment identifier within FarEye. Used for task creation and driver dispatch.
consignmentType
consignmentDetails.consignmentType
 Mandatory FORWARD (delivery) or REVERSE (return/pickup). Determines routing direction and driver workflow.
serviceType
consignmentDetails.serviceType
 Mandatory Service level, e.g. White Glove, Two-Man Delivery, Installation. Must correspond to a driver skill configured in FarEye.
shipByDate
consignmentDetails.shipByDate
 Mandatory Date the order must leave the warehouse. Format: YYYY-MM-DD. FarEye groups all orders for the same date when building routes.
totalWeight
consignmentDetails.totalWeight
 Mandatory Total consignment weight. Critical for vehicle load planning and two-man threshold assessment.
totalWeightUom
consignmentDetails.totalWeightUom
 Mandatory Weight unit of measure. Accepted values: KG, LB.
totalQuantity
consignmentDetails.totalQuantity
 Mandatory Total number of packages. Drives vehicle capacity planning and crew size determination.
totalVolume / totalVolumeUom
consignmentDetails.totalVolume / totalVolumeUom
 Mandatory Total volume and unit (e.g. CBM, MM3). Required for big & bulky — missing volume causes incorrect vehicle matching.
specialInstructions
consignmentDetails.specialInstructions
 Mandatory Handling instructions for the driver (e.g. two-man lift, installation required, call ahead, floor level). Missing instructions lead to failed deliveries when a single driver arrives for a two-man job.
businessUnit
consignmentDetails.businessUnit
 Recommended Business unit code. Required for multi-BU accounts to route to the correct service area and driver pool.
deliveryInstructions
consignmentDetails.deliveryInstructions
 Recommended Delivery-specific instructions for the driver (e.g. access code, floor level, customer call required).
paymentTobeCollected
consignmentDetails.paymentTobeCollected
 Optional Required for COD orders. Object with paymentMode (PREPAID or COD), amount, and currency.
PD Package Details · consignmentDetails.packageDetails[] 9 mandatory
Field Required Description
id
packageDetails[].id
 Mandatory Unique package identifier. Used for per-package tracking and ePOD matching.
type
packageDetails[].type
 Mandatory Package unit type, e.g. Pallet, Crate, Carton. Used for vehicle load matching.
length / width / height
packageDetails[].length / width / height
 Mandatory Package dimensions. Required for big & bulky — missing dimensions cause incorrect vehicle matching and failed deliveries.
dimensionUom
packageDetails[].dimensionUom
 Mandatory Dimension unit of measure. Accepted values: CM, IN.
weight
packageDetails[].weight
 Mandatory Per-package weight. Used for vehicle load planning and two-man threshold assessment.
weightUom
packageDetails[].weightUom
 Mandatory Per-package weight unit. Accepted values: KG, LB.
quantity
packageDetails[].quantity
 Mandatory Number of units in this package entry.
volume / volumeUom
packageDetails[].volume / volumeUom
 Mandatory Per-package volume and unit (e.g. CBM, MM3). Required for big & bulky vehicle fill rate calculation.
description
packageDetails[].description
 Mandatory Human-readable description of package contents (e.g. Washing Machine, Sofa 3-Seater). Shown in driver app and required for ePOD documentation.
value
packageDetails[].value
 Recommended Declared value of contents. Used for insurance and ePOD documentation.
tags
packageDetails[].tags
 Recommended Array of handling tags, e.g. ["Do Not Stack", "This Side Up", "Fragile"]. Displayed in driver app at the stop.
instructions
packageDetails[].instructions
 Recommended Per-package handling instructions (e.g. keep upright, tail-lift required). Overrides consignment-level instructions for this package.
additionalInformation
packageDetails[].additionalInformation
 Optional Free-form key-value map for custom metadata (e.g. assembly notes, SKU details).
SK SKU Details · consignmentDetails.skuDetails[] 0 mandatory
Field Required Description
code
skuDetails[].code
 Recommended Your SKU / product code. Used for customs declarations and order reconciliation.
name
skuDetails[].name
 Recommended Product name. Printed on customs documentation and manifests.
quantity
skuDetails[].quantity
 Recommended Item quantity. Must match the sum of units in the linked package.
unitPrice / value
skuDetails[].unitPrice / value
 Recommended Unit price and total declared value. Required for customs declarations and insurance.
packageIds
skuDetails[].packageIds[]
 Recommended Array of package IDs this SKU belongs to. Links SKU to the correct packageDetails[] entry.
lineItemNo
skuDetails[].lineItemNo
 Optional Order line item number. Used to correlate SKUs back to your OMS line items.
category
skuDetails[].category
 Optional Product category (e.g. electronics, furniture). Used for carrier service rule matching.
hsnName
skuDetails[].hsnName
 Optional HSN / tariff code. Required for cross-border shipments and customs declarations.
originCountry
skuDetails[].originCountry
 Optional Country of origin in ISO 3166-1 alpha-2 format. Required for international customs.
weight / weightUom
skuDetails[].weight / weightUom
 Optional Per-SKU weight and unit. Used for customs and compliance checks.
length / width / height / dimensionUom
skuDetails[].length / width / height / dimensionUom
 Optional Per-SKU dimensions with unit. Used for volumetric calculations and customs documentation.
volume / volumeUom
skuDetails[].volume / volumeUom
 Optional Per-SKU volume and unit.
description
skuDetails[].description
 Optional Product description. Included in customs documentation and carrier manifests.
imageUrl
skuDetails[].imageUrl
 Optional URL of the product image. Displayed in the FarEye Dashboard for identification.
uom
skuDetails[].uom
 Optional Unit of measure for the item, e.g. BOX, EACH, PAIR.
deliveryServiceTime / pickupServiceTime
skuDetails[].deliveryServiceTime / pickupServiceTime
 Optional Estimated service time in minutes at delivery / pickup stop. Influences route optimiser dwell time.
fragile / stackable / hazmat / heavyWeight / vip
skuDetails[].fragile / stackable / hazmat / heavyWeight / vip
 Optional Boolean handling flags. Surfaced in the FarEye Driver App and passed to carriers that support them.
VA Value-Added Services · vas[] 0 mandatory
Field Required Description
vasCode
vas[].vasCode
 Recommended Service code identifying the value-added service, e.g. ROOM_OF_CHOICE, TWO_MAN_DELIVERY, HAUL_AWAY_OLD, INSTALLATION. Carrier must support the service.
level
vas[].level
 Recommended Scope of the service: SKU (applies to specific items identified in targetIds) or CONSIGNMENT (applies to the whole shipment).
targetIds
vas[].targetIds[]
 Recommended Array of SKU line item numbers or package IDs this VAS applies to. Required when level is SKU.
serviceTime
vas[].serviceTime
 Recommended Estimated time in minutes at the stop for this service (e.g. 30 for installation). Influences route optimiser dwell time.
remark
vas[].remark
 Optional Free-text instruction for the driver or carrier (e.g. Wall-mount 55-inch TV).
CR Carrier · carrier 1 mandatory
Field Required Description
code
carrier.code
 Mandatory Carrier identifier configured in FarEye, e.g. DHL, HERMES, OWNFLEET. Maps the consignment to the correct rate card and service rules.
SF Ship From · shipFrom 8 mandatory
Field Required Description
contact.name
shipFrom.contact.name
 Mandatory Sender / warehouse contact name. Shown in driver app for pickup reference.
contact.contactNumber
shipFrom.contact.contactNumber
 Mandatory Sender's phone number. Used by the driver for pickup coordination.
address.line1
shipFrom.address.line1
 Mandatory Primary street address of the origin location.
address.city
shipFrom.address.city
 Mandatory City of the origin location. Used for route zone determination.
address.pincode
shipFrom.address.pincode
 Mandatory Postal / ZIP code. Used for service zone determination and route clustering.
address.country
shipFrom.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format (e.g. US, IN).
pickupStartDateTime
shipFrom.pickupStartDateTime
 Mandatory Earliest time for pickup. Format: YYYY-MM-DD HH:MM:SS. Required for bulky — needed to coordinate vehicle and crew availability.
pickupEndDateTime
shipFrom.pickupEndDateTime
 Mandatory Latest time for pickup. Required for bulky — open-ended windows cause scheduling failures.
originFacilityCode
shipFrom.originFacilityCode
 Recommended Origin hub or facility code configured in FarEye. Enables address auto-fill and facility-based routing rules.
contact.email
shipFrom.contact.email
 Recommended Sender's email. Used for dispatch confirmations.
contact.companyName
shipFrom.contact.companyName
 Recommended Sender's company name. Shown to driver in the FarEye Driver App.
timezone
shipFrom.timezone
 Recommended IANA timezone for pickup date/time (e.g. Asia/Kolkata). Ensures correct SLA calculation across regions.
address.latitude / longitude
shipFrom.address.latitude / longitude
 Optional Geo-coordinates of the origin. Improves address matching and route optimisation accuracy.
address.type
shipFrom.address.type
 Optional Address classification: FACILITY or Residential.
ST Ship To · shipTo 8 mandatory
Field Required Description
contact.name
shipTo.contact.name
 Mandatory Recipient name. Shown in driver app and used for delivery notifications.
contact.contactNumber
shipTo.contact.contactNumber
 Mandatory Recipient's phone number. Mandatory — used for pre-delivery call and driver contact on bulky deliveries.
address.line1
shipTo.address.line1
 Mandatory Primary delivery street address.
address.pincode
shipTo.address.pincode
 Mandatory Postal / ZIP code. Used for service zone matching and route clustering.
address.county
shipTo.address.county
 Mandatory Suburb/county of the delivery location.
address.country
shipTo.address.country
 Mandatory Country code in ISO 3166-1 alpha-2 format.
deliveryStartDateTime
shipTo.deliveryStartDateTime
 Mandatory Earliest acceptable delivery time. Format: YYYY-MM-DD HH:MM:SS. Mandatory for big & bulky — customers must be home; required for route optimiser window compliance.
deliveryEndDateTime
shipTo.deliveryEndDateTime
 Mandatory Latest acceptable delivery time. Mandatory for big & bulky — open windows cause failed delivery attempts.
address.city
shipTo.address.city
 Recommended Delivery city. Improves address matching and delivery zone determination.
destinationFacilityCode
shipTo.destinationFacilityCode
 Recommended Destination hub or facility code. Used to pre-assign delivery zone and driver pool.
contact.email
shipTo.contact.email
 Recommended Recipient's email for delivery notifications and tracking link delivery.
address.type
shipTo.address.type
 Recommended Address classification: Residential or FACILITY. Affects driver instructions and crew requirements for bulky deliveries.
timezone
shipTo.timezone
 Recommended IANA timezone for delivery date/time. Ensures SLA windows are interpreted correctly.
address.latitude / longitude
shipTo.address.latitude / longitude
 Optional Geo-coordinates of the delivery location. Improves address matching and route optimisation.
address.poBoxNumber
shipTo.address.poBoxNumber
 Optional PO Box number where applicable.
RD Route & Driver · routeDetails 1 mandatory
Field Required Description
skills
routeDetails.skills[]
 Mandatory Array of driver skill tags required for this stop, e.g. ["installation_certified", "two_man"]. FarEye only assigns drivers with all matching skills. Missing skills cause incorrect driver assignment.
serviceAreaCode
routeDetails.serviceAreaCode
 Recommended Service area or territory code configured in FarEye. Restricts assignment to drivers operating in this zone.
priority
routeDetails.priority
 Optional Stop priority level. Higher-priority stops are sequenced earlier in the route by the optimiser.
vehicleType
routeDetails.vehicleType
 Recommended Required vehicle type for this stop, e.g. Truck, Van with Tail-Lift. Route optimiser will prefer matching vehicles when available.
🚛
Big & bulky tip: Always include Dimensions, Volume, Weight, Time Window, and Special Instructions. Missing dimensions cause incorrect vehicle matching. Missing special instructions lead to failed deliveries when a single driver shows up for a two-man job.
📦
Parcel tip: For standard parcels, the mandatory fields above are usually sufficient. Include Weight and Item Count — dimensions are optional for small packages but help carriers optimise vehicle loading.
🚛
Big & bulky tip: Always include Dimensions, Volume, Weight, and Special Instructions. Missing dimensions cause incorrect carrier quoting. Missing special instructions lead to failed deliveries when a single driver shows up for a two-man job.
🚛
Freight field guide — coming soon. The freight payload extends the standard consignment schema with pallet counts, LTL/FTL flags, BoL references, and consignment-level weight/volume thresholds. Detailed field tables will be published here. In the meantime, speak to your FarEye implementation manager for a freight-specific field checklist.

Response payload

Success — Order created200
{
  "timestamp": "2025-08-05 02:12:24 GMT+0000",
  "status": "OK",
  "data": [
    {
      "referenceNumber": "MBFE004",
      "orderNumber": "ORDER_MB155",
      "consignmentNumber": "ORDER_MB155-1",
      "masterTrackingNumber": "string",
      "trackingDetails": [
        {
          "packageId": "2023_11_23_10_4223",
          "trackingNumber": "1ZXXXXXXXXXXXXXXXX",
          "label": "https://fes-expand-staging.s3.us-west-2.amazonaws.com/...ORDER_MB155_1ZXXXXXXXXXXXXXXXX.zpl",
          "carrierDetails": {
            "name": "UPS-NEW",
            "code": "UPS-NEW",
            "info": {}
          }
        }
      ]
    }
  ]
}
Bad Request — validation failed400
{
  "timestamp": "2025-08-05 06:48:01 GMT+0000",
  "status": "BAD_REQUEST",
  "errors": [
    {
      "referenceNumber": "41245154555511",
      "details": [
        "Invalid request type"
      ]
    }
  ]
}
Conflict — duplicate consignment409
{
  "timestamp": "2025-08-05 07:38:02 GMT+0000",
  "status": "CONFLICT",
  "message": "Error",
  "errors": [
    "Consignment details already mapped with another Consignment"
  ],
  "data": {
    "orderNumber": "9293993803",
    "consignmentNumber": "3667443006",
    "referenceNumber": "3667443006",
    "trackingDetails": [
      {
        "packageId": "2023_11_23_10_4223",
        "carrierDetails": {
          "name": "UPS-NEW",
          "code": "UPS-NEW",
          "info": {}
        }
      }
    ]
  }
}
Unprocessable Entity — field validation422
{
  "timestamp": "2025-08-05 06:00:01 GMT+0000",
  "status": "UNPROCESSABLE_ENTITY",
  "message": "Error",
  "errors": [
    "'packag.length' at index 0 does not satisfy the condition 'NOT_EQUALS 2.0'",
    "'package.width' at index 0 does not satisfy the condition 'NOT_EQUALS 2.0'",
    "'package.height' at index 0 does not satisfy the condition 'NOT_EQUALS 2.0'"
  ],
  "data": {
    "orderNumber": "16431424",
    "referenceNumber": "JBH|AU|0b82a403-efa7-429c-b686-f3d2d89333cc",
    "trackingDetails": []
  }
}
Internal Server Error500
{
  "errors": [
    "Issue in request payload"
  ],
  "message": "Internal server error",
  "timestamp": "2025-08-05 06:48:01 GMT+0000",
  "status": "INTERNAL_SERVER_ERROR"
}

Update orders Modify consignment details before dispatch

Update an existing consignment by sending the same payload structure as Send orders, matched on referenceNumber. Only the fields you include will be updated — omitted fields remain unchanged.

Update ConsignmentPUT 
PUT /api/v2/consignments

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignmentDetails": {
    "referenceNumber": "MBFE0004",
    "orderNumber": "OD01231231212",
    "consignmentNumber": "CON12345678",
    "consignmentType": "FORWARD",
    "serviceType": "Express",
    // ... same structure as send orders
  },
  "shipTo": {
    "contact": {
      "contactName": "Updated Name",
      "phoneNumber": "+91-9876543210"
    },
    "address": {
      "addressLine1": "New Address Line 1",
      "city": "Mumbai",
      "state": "Maharashtra",
      "pinCode": "400001",
      "country": "IN"
    }
  }
}
📄
Same payload as Create Consignment: The update request uses the same JSON structure documented in Section 4 — Send orders. FarEye matches the order using referenceNumber and applies only the fields you include. Refer to the mandatory & recommended fields tables in that section for the complete field reference.
⚠️
Update window: Orders can only be updated before carrier dispatch. Once a label has been generated and the carrier has picked up, modifications are no longer possible via this endpoint.

How partial updates work

  1. referenceNumber is the only required field — it identifies which consignment you're updating.
  2. Send only the fields you want to change. Fields you omit will not be modified.
  3. Nested objects (like packageDetails or shipTo) must still follow their own required structure if included.

Fields you cannot change

  1. orderNumber
  2. Carrier details — once a label is generated, carrier cannot be changed.
  3. Dispatched consignments — consignments cannot be edited once in Dispatched state or beyond. Any update request will return a 409 Conflict response containing the existing tracking numbers and labels.

Conflict handling

If an update conflicts with carrier processes (e.g., label already generated, consignment dispatched), the API returns a 409 Conflict with tracking details of the existing consignment.

When to use this API

  1. Fix a wrong or incomplete delivery address.
  2. Update or add special delivery instructions (e.g., "Leave with building security").
  3. Modify delivery time windows (start / end).
  4. Add or update value-added services (VAS) like installation or haul-away.
  5. Correct package details (weight, dimensions, tags).

Response payload

Success — Order updated200
{
  "timestamp": "2025-08-05 02:12:24 GMT+0000",
  "status": "OK",
  "data": [
    {
      "referenceNumber": "MBFE004",
      "orderNumber": "ORDER_MB155",
      "consignmentNumber": "ORDER_MB155-1",
      "masterTrackingNumber": "string",
      "trackingDetails": [
        {
          "packageId": "2023_11_23_10_4223",
          "trackingNumber": "1ZXXXXXXXXXXXXXXXX",
          "label": "https://fes-expand-staging.s3.us-west-2.amazonaws.com/...ORDER_MB155_1ZXXXXXXXXXXXXXXXX.zpl",
          "carrierDetails": {
            "name": "UPS-NEW",
            "code": "UPS-NEW",
            "info": {}
          }
        }
      ]
    }
  ]
}
Bad Request — validation failed400
{
  "timestamp": "2025-08-05 06:48:01 GMT+0000",
  "status": "BAD_REQUEST",
  "errors": [
    {
      "referenceNumber": "41245154555511",
      "details": [
        "Invalid request type"
      ]
    }
  ]
}
Conflict — duplicate consignment409
{
  "timestamp": "2025-08-05 07:38:02 GMT+0000",
  "status": "CONFLICT",
  "message": "Error",
  "errors": [
    "Consignment details already mapped with another Consignment"
  ],
  "data": {
    "orderNumber": "9293993803",
    "consignmentNumber": "3667443006",
    "referenceNumber": "3667443006",
    "trackingDetails": [
      {
        "packageId": "2023_11_23_10_4223",
        "carrierDetails": {
          "name": "UPS-NEW",
          "code": "UPS-NEW",
          "info": {}
        }
      }
    ]
  }
}
Unprocessable Entity — field validation422
{
  "timestamp": "2025-08-05 06:00:01 GMT+0000",
  "status": "UNPROCESSABLE_ENTITY",
  "message": "Error",
  "errors": [
    "'package.length' at index 0 does not satisfy the condition 'NOT_EQUALS 2.0'",
    "'package.width' at index 0 does not satisfy the condition 'NOT_EQUALS 2.0'",
    "'package.height' at index 0 does not satisfy the condition 'NOT_EQUALS 2.0'"
  ],
  "data": {
    "orderNumber": "16431424",
    "referenceNumber": "JBH|AU|0b82a403-efa7-429c-b686-f3d2d89333cc",
    "trackingDetails": []
  }
}
Internal Server Error500
{
  "errors": [
    "Issue in request payload"
  ],
  "message": "Internal server error",
  "timestamp": "2025-08-05 06:48:01 GMT+0000",
  "status": "INTERNAL_SERVER_ERROR"
}

Cancel orders Cancel consignments before carrier pickup

Cancel one or more consignments in a single request. Include a remark to record the cancellation reason. FarEye cascades the cancellation to the carrier — revoking labels and manifests.

Cancel ConsignmentPOST
POST /v2/consignments-cancel

Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "consignments": [
    {
      "referenceNumber": "MBFE0004",
      "remark": "Customer don't want order"
    },
    {
      "referenceNumber": "MBFE0005",
      "remark": "Customer don't want order."
    }
  ]
}

Payload field reference

CD Consignments · consignments[] 1 mandatory
Field Required Description
referenceNumber
consignments[].referenceNumber
 Mandatory Your internal reference ID that was used when creating the consignment. Identifies which order to cancel.
remark
consignments[].remark
 Recommended Cancellation reason. Logged for audit and available in reporting.
⚠️
Cancellation window: Orders can only be cancelled before carrier pickup. Once the carrier has scanned the shipment, use the Returns flow instead.

Response payload

Success — cancellation results per consignment200
{
  "timestamp": 2025-08-05 06:48:01 GMT+0000,
  "successCount": 1,
  "failedCount": 2,
  "data": [
    {
      "referenceNumber": "CN001",
      "trackingDetails": [
        {
          "trackingNumber": "x1",
          "status": "Success",
          "remark": "Cancellation successful"
        },
        {
          "trackingNumber": "x2",
          "status": "Failed",
          "remark": "Cancellation not allowed as status is cancelled"
        }
      ],
      "status": "Failed",
      "message": "The consignment has not been cancelled"
    },
    {
      "referenceNumber": "CN002",
      "trackingDetails": [
        {
          "trackingNumber": "y1",
          "status": "Success",
          "remark": "Cancellation successful"
        },
        {
          "trackingNumber": "y2",
          "status": "Success",
          "remark": "Cancellation successful"
        }
      ],
      "status": "Success",
      "message": "The consignment has been cancelled"
    },
    {
      "referenceNumber": "CN003",
      "trackingDetails": [
        {
          "trackingNumber": "z1",
          "status": "Failed",
          "remark": "Cancellation not allowed as status is cancelled"
        },
        {
          "trackingNumber": "z2",
          "status": "Failed",
          "remark": "Consignment not found"
        }
      ],
      "status": "Failed",
      "message": "The consignment has not been cancelled"
    }
  ]
}
Bad Request — invalid reference400
{
  "timestamp": 2025-08-05 06:48:01 GMT+0000,
  "successCount": 0,
  "failedCount": 1,
  "errors": [
    {
      "referenceNumber": "41245154555511",
      "details": [
        "Invalid reference_number attribute"
      ]
    }
  ]
}
Internal Server Error500
{
  "errors": [
    "Issue in request payload"
  ],
  "message": "Internal server error",
  "timestamp": "2025-08-05 06:48:01 GMT+0000",
  "status": "INTERNAL_SERVER_ERROR"
}

Receive status updates Webhooks — FarEye pushes events to you

Register a webhook URL and FarEye pushes every status change in real time. Same mechanism for both outsourced and insourced — the events differ.

1. Provide a webhook URL
Give your FarEye implementation manager an HTTPS endpoint, e.g. https://api.yourcompany.com/fareye/webhook.
2. Choose event subscriptions
Subscribe to order types: Forward, Reverse, Transfer, Exchange. Each can have its own URL or share one endpoint.
3. FarEye pushes events as they happen
Every carrier status change is normalised and posted to your webhook.Every driver action (arrival, completion, ePOD) is POSTed to your webhook with GPS coordinates and proof of delivery.
4. Respond with 200 OK
Return HTTP 200 within 30 seconds. Failed webhooks are retried up to 4 times (30-min buffer). Monitor and bulk-retry in Web-hook Logs.
⚠️
Idempotency: Webhooks may arrive out of order or duplicated after retries. Use timestamp for ordering and order_reference + event as an idempotency key.

Sample webhook payload

Below is a representative webhook event payload. FarEye POSTs this JSON to your registered endpoint whenever a status change occurs.

Consignment-level webhooks deliver milestone updates derived from across all shipments in the order. Shipment-level webhooks deliver a status event per package, each time a label is scanned.

Webhook Event — ShipmentWEBHOOK
{
  "id": "wh_01J5KXMN8RTYQZAB",
  "type": "shipment::out_for_delivery",
  "occurredAt": "2025-08-06T07:45:00+05:30",
  "data": {
    "trackingNumber": "1Z999AA10123456784",
    "consignmentNumber": "CON123456789",
    "orderNumber": "ORD123456",
    "status": "OUT_FOR_DELIVERY",
    "description": "Shipment is out for delivery"
  },
  "location": {
    "code": "DL112",
    "name": "Delhi Hub",
    "lat": 28.6448,
    "lng": 77.216721
  },
  "carrier": {
    "code": "DHL",
    "statusCode": "100",
    "statusDescription": "Shipment Delivered Successfully",
    "subStatusCode": "016",
    "subStatusDescription": "Customer not available at delivery address",
    "rawStatus": "Delivered"
  },
  "metadata": {
    "customerStatusCode": "Harmonized status",
    "receivedBy": "John Doe",
    "receivedByRelation": "Security Guard",
    "eta": "2025-08-07T14:30:00+05:30",
    "expectedDate": "2025-08-09",
    "promisedDate": "2025-08-10",
    "pod": [
      {
        "type": "SIGNATURE",
        "url": "https://cdn.fareye.com/pod/12345-signature.png"
      },
      {
        "type": "PHOTO",
        "url": "https://cdn.fareye.com/pod/12345-photo.png"
      }
    ],
    "driverName": "John",
    "vehicleNumber": "DL12AAA1234",
    "comments": "Left package with security guard",
    "additionalNotes": "Handle with care"
  }
}

Payload field reference

EV Event Envelope · top-level 3 fields
Field Required Description
id
id
 Mandatory Unique webhook event identifier. Use for deduplication.
type
type
 Mandatory Event type in resource::action format, e.g. shipment::out_for_delivery.
occurredAt
occurredAt
 Mandatory ISO 8601 timestamp when the event occurred (with timezone offset).
DA Data · data 5 fields
Field Required Description
trackingNumber
data.trackingNumber
 Mandatory Carrier-assigned tracking number for the shipment.
consignmentNumber
data.consignmentNumber
 Mandatory FarEye consignment identifier.
orderNumber
data.orderNumber
 Mandatory Your platform's order number. Correlates the event to your OMS.
status
data.status
 Mandatory Normalised FarEye status code, e.g. OUT_FOR_DELIVERY, DELIVERED.
description
data.description
 Mandatory Human-readable description of the current status.
LC Location · location 4 fields
Field Required Description
code
location.code
 Mandatory Hub or facility code where the event occurred.
name
location.name
 Mandatory Human-readable name of the hub or facility.
lat
location.lat
 Recommended Latitude of the event location (decimal degrees).
lng
location.lng
 Recommended Longitude of the event location (decimal degrees).
CR Carrier · carrier 6 fields
Field Required Description
code
carrier.code
 Mandatory Carrier identifier code, e.g. DHL, FEDEX.
statusCode
carrier.statusCode
 Mandatory Carrier's native status code.
statusDescription
carrier.statusDescription
 Mandatory Carrier's human-readable status description.
subStatusCode
carrier.subStatusCode
 Recommended Carrier's sub-status code for granular tracking.
subStatusDescription
carrier.subStatusDescription
 Recommended Human-readable sub-status detail, e.g. "Customer not available at delivery address".
rawStatus
carrier.rawStatus
 Recommended The carrier's original unmodified status string.
MT Metadata · metadata 12 fields
Field Required Description
customerStatusCode
metadata.customerStatusCode
 Recommended Harmonised customer-facing status code.
receivedBy
metadata.receivedBy
 Recommended Name of the person who received the shipment.
receivedByRelation
metadata.receivedByRelation
 Recommended Relation of the receiver to the consignee, e.g. "Security Guard", "Family Member".
eta
metadata.eta
 Recommended Estimated time of arrival. ISO 8601 with timezone offset.
expectedDate
metadata.expectedDate
 Recommended Expected delivery date. Format: YYYY-MM-DD.
promisedDate
metadata.promisedDate
 Recommended Promised delivery date communicated to the customer. Format: YYYY-MM-DD.
pod[]
metadata.pod[]
 Recommended Proof of delivery array. Each entry has a type (SIGNATURE, PHOTO) and a url to the asset.
pod[].type
metadata.pod[].type
 Mandatory Type of proof: SIGNATURE or PHOTO.
pod[].url
metadata.pod[].url
 Mandatory CDN URL to the proof-of-delivery asset.
driverName
metadata.driverName
 Recommended Name of the delivery driver.
vehicleNumber
metadata.vehicleNumber
 Recommended Vehicle registration number used for the delivery.
comments
metadata.comments
 Recommended Driver or system comments about the delivery.
additionalNotes
metadata.additionalNotes
 Recommended Freeform notes or special handling instructions.
Webhook Event — ConsignmentWEBHOOK
{
  "id": "wh_01J5KXMN8RTYQZAB",
  "type": "consignment::delivered",
  "occurredAt": "2025-08-06T07:45:00+05:30",
  "data": {
    "orderNumber": "ORD123456",
    "consignmentNumber": "CON123456789",
    "status": "DELIVERED",
    "shipments": [
      {
        "trackingNumber": "1Z999...",
        "eventCode": "shipment::delivered",
        "occurredAt": "2025-08-06T07:45:00+05:30"
      },
      {
        "trackingNumber": "1Z991...",
        "eventCode": "shipment::delivered",
        "occurredAt": "2025-08-06T07:45:00+05:30"
      }
    ]
  },
  "metadata": {
  }
}

Payload field reference

EV Event Envelope · top-level 3 fields
Field Required Description
id
id
 Mandatory Unique webhook event identifier. Use for deduplication.
type
type
 Mandatory Event type in resource::action format, e.g. consignment::delivered.
occurredAt
occurredAt
 Mandatory ISO 8601 timestamp when the event occurred (with timezone offset).
CD Consignment Data · data 3 fields
Field Required Description
orderNumber
data.orderNumber
 Mandatory Your platform's order number. Correlates the event to your OMS.
consignmentNumber
data.consignmentNumber
 Mandatory FarEye consignment identifier.
status
data.status
 Mandatory Normalised consignment-level status code, e.g. DELIVERED.
SH Shipments · data.shipments[] 3 fields per item
Field Required Description
trackingNumber
data.shipments[].trackingNumber
 Mandatory Carrier-assigned tracking number for this shipment within the consignment.
eventCode
data.shipments[].eventCode
 Mandatory Shipment-level event code, e.g. shipment::delivered.
occurredAt
data.shipments[].occurredAt
 Mandatory ISO 8601 timestamp when this individual shipment event occurred.
MT Metadata · metadata 0 fields
Field Required Description
Reserved for future use. Currently empty for consignment-level events.

Checkout API Surface delivery options at time of purchase

Use FarEye's Checkout API to show delivery options, EDD promises, shipping charges, and available delivery slots to customers on your checkout page — and on Product Display or Listing Pages (Catalogue).

Full API reference

Detailed request/response schema, parameters, and examples are available in the FarEye developer portal.

View Checkout API docs →
💡
Same APIs, two surfaces: The Checkout API response can be used both on your checkout page and on Product Display / Listing Pages to show estimated delivery dates and shipping charges before the customer adds to cart.

Pickup & Locker locations Let customers choose their collection point

Fetch available PUDO (Pick Up / Drop Off) points and parcel locker locations near the customer's address. Surface these on your checkout page so customers can choose to collect their parcel from a convenient location instead of home delivery.

Full API reference

Detailed request/response schema, query parameters (radius, carrier, location type), and examples are available in the FarEye developer portal.

View Pickup & Locker locations API docs →

Slot APIs Get, reserve, and confirm delivery windows

Use these three APIs in sequence to surface available delivery windows to your customer, hold their chosen slot, and confirm it when the order is placed.

Full API reference

Complete request/response schemas for all three slot APIs are in the FarEye developer portal.

View Slot APIs docs →
💡
Always pass the slot token in Create Order. Once confirmed, include the slotToken in your Create Consignment payload. FarEye uses it to assign the order to the correct route window during planning.

Carrier setup Done by your FarEye admin — here's what happens

FarEye comes pre-integrated with 150+ carriers. Your admin subscribes and configures them through the dashboard.

Settings → Carrier Subscription → Subscribe Carrier. Search, enter carrier credentials, name the region (e.g., "DHL Express North Region"). Success confirmation appears.
Carrier card → ⋮ → Manage Services. Choose Outsourced Fleet (carrier handles label/tracking) or Managed Fleet (FarEye handles). Most customers select Outsourced Fleet.
Carrier card → ⋮ → Event Mapping. Map every carrier status code to a normalised FarEye status. Ensures consistent webhooks. Download/upload as CSV.
Deactivate blocks new assignments (in-flight orders unaffected). Edit Details updates credentials.

Route & driver setup Configuration in FarEye Dashboard

No carrier integrations needed. Configure your fleet, drivers, and route planning rules in the FarEye Dashboard.

Geographic zones, operating hours, delivery windows per zone. Orders outside zones are flagged for manual review or carrier fallback.
Add vehicles with type (van, truck), capacity (weight + volume), and capabilities (tail-lift, two-man crew). Route optimiser matches orders to the right vehicle.
Drivers download the FarEye Driver App (iOS/Android). Configure login, skills (installation-certified, bulky-trained), working hours, and home base.
Max stops per route, time window priority, vehicle-to-order matching, optimisation objective (shortest distance / least time / fewest vehicles). For bulky: set service time per stop (e.g., 30 min for install).
1. Orders pushed via API → 2. FarEye batches by date & runs optimiser → 3. Routes assigned to drivers → 4. Drivers see stops in app with navigation → 5. Each stop: arrive → deliver → capture ePOD → 6. Webhooks fire in real time.

Quick API reference The endpoints you'll actually use

Action Method Endpoint When to use
Create order POST /v2/consignments New order — push for carrier dispatch
Update order PUT /api/v2/consignments Address change, reschedule
Cancel order POST /v2/consignments-cancel Cancel before carrier pickup
Get status GET /api/v1/consignment/{id}/status On-demand check (prefer webhooks)
Create return POST /v2/consignments Same endpoint, Order Type: Reverse
Action Method Endpoint When to use
Create order POST /v2/consignments New order — push for route planning
Update order PUT /api/v2/consignments Reschedule, change instructions
Cancel orders POST /v2/consignments-cancel Remove stop — route re-optimises
Create return POST /v2/consignments Same endpoint, Task Type: Reverse
🔐
Authentication: Every API call requires Authorization: Bearer <token>. Generate in Settings → General Settings. Generating a new token permanently invalidates the old one.

Status mapping Lifecycle events your system receives

FarEye normalises carrier-specific codes so your system handles one consistent set of events.

Label created by sender
→
Created
Picked up from Sender
→
Picked Up
It's on its way
→
In Transit
Arrived at facility
→
At Facility
Onboard for delivery
→
Out for Delivery
DELIVERED
→
Delivered
Attempted delivery - No one in attendance
→
Undelivered
Returned to Sender - Item not collected
→
Returned to Origin

Statuses come from the FarEye Driver App — richer than carrier events, with GPS and ePOD at each stop.

CREATED
→
Order Received
ROUTE ASSIGNED
→
Route Planned
DRIVER ASSIGNED FOR DELIVERY
→
Driver En Route
REACHED AT LOCATION
→
Driver Arrived
DELIVERED
→
Delivered (with ePOD)
UNDELIVERED
→
Failed (with reason)
RTO COMPLETED
→
All Stops Done

Value-added services Installation, assembly & haul-away

For Big & Bulky operations with on-site services, use the vas[] array in the consignment payload to specify service codes, target SKUs, and estimated dwell time.

VAS service codes
CodeDescriptionTypical dwell
TWO_MAN_DELIVERYTwo-man lift and placement at room of choice20–30 min
INSTALLATIONFull installation at customer premises (e.g. washing machine plumb-in)45–90 min
ASSEMBLYFurniture or appliance assembly on-site30–60 min
HAUL_AWAY_OLDRemoval and disposal of customer's old unit15–20 min
ROOM_OF_CHOICEDelivery to a specific room, not just doorstep10–15 min
💡
Always set serviceTime: Route optimisation uses this to allocate the correct stop dwell time. Under-estimating dwell times cascades into late deliveries for all subsequent stops on the route.

Troubleshooting Common issues and fixes

Settings → Logs → Web-hooks → filter Failed. Check request/response payload. Common: non-200 response, timeout (>30s), unreachable URL. Select failed rows → Retry.
Token may have been regenerated. Check Settings → General Settings. New token permanently invalidates the old one.
Check: carrier is active, service type matches, carrier covers destination, credentials valid.
Check: delivery date is an operating day, address is within a service zone, vehicle with capacity exists, driver with matching skills is available.
Check: route is published (not draft), driver assigned correctly, app is latest version, network connectivity.
Check: webhook URL toggled ON for the order type. Verify carrier event is mapped in Event Mapping — unmapped events are dropped.Verify event type is included in subscription — some route-level events need opt-in.

Need help? Your integration team is here.

For detailed API schemas, sandbox credentials, and hands-on support, reach out to your FarEye implementation manager.

Email support@fareye.com Full API Docs →

Webhook Event CatalogAll shipment & consignment lifecycle events