FarEye is a delivery management platform: multi-carrier shipping, route planning, last-mile tracking and delivery experience software sold to retailers, couriers and logistics operators. It is not a carrier. For a connector it sits one level above the couriers, so a single FarEye integration yields carrier-attributed rate shopping, consignment creation with labels, pickup booking, delivery slots and a harmonised tracking event stream across whatever carrier panel the client has configured. The documentation is genuinely good: a public Redoc portal at developer.fareye.com backed by downloadable OpenAPI 3.0.1 specifications for both v1 and v2, with per-region servers and webhook definitions.
At a glance
What it is
FarEye Technologies Pvt Ltd is a delivery management software company of Indian origin, now operating globally. Its product set is modular and named per capability: Ship (multi-carrier shipping), Route (route planning), Plan (territory planning), Smart, Track (last-mile tracking), Execute, Experience (delivery experience), Grow and Analyze. Industry verticals it targets are big and bulky, courier and logistics, e-commerce, grocery, pharmaceuticals, retail and auto parts distribution.
The "big and bulky" emphasis shows up all over the API: delivery slot reservation, two-person delivery routing tags, installation progress in the webhook payload, pallet quantities on consignments and technician service orders as a consignment type. If you are connecting a seller who ships appliances, furniture or white goods, this is the shape of API you should expect.
Geographic footprint is visible in the server list: US, EU, Singapore, Australia, Canada and India each get their own API host, plus staging and UAT. Data residency is therefore a first-class concern, and the base URL is part of the account configuration, not a constant.
API access
- Portal: developer.fareye.com. The OpenAPI file is downloadable from the footer. Both v1 and v2 are served; v2 is the default.
- Contact for credentials and integration support:
integration@fareye.com. - Servers, from the specification:
developer.fareyeconnect.comredirects todeveloper.fareye.com. Per-client documentation instances also exist (for example a Miele-specific portal), which confirms the spec is tailored per account: the endpoints your account exposes and the fields it requires may differ from the public spec.- No official SDK is published. The spec itself is the artefact; generate a client from it.
The specification says explicitly that not every customer uses every flow and that mandatory attributes vary by account setup. Package details, for instance, may be required for one client and optional for another. Treat the public spec as the superset and get your account's actual requirements confirmed during onboarding.
Authentication
Simple, and entirely out of band.
- Request a token from the FarEye integration team at
integration@fareye.comor through a support ticket. There is no token endpoint in either specification. - Send it on every request:
curl -X POST "https://api-in.fareyeconnect.com/v2/checkout" \
-H "Authorization: Bearer $FAREYE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"consignmentDetails": {}}'
- The v1 spec declares a single security scheme named
Bearerapplied globally. No expiry, refresh grant, scope or role model is documented. FarEye's own guidance is to store tokens securely and rotate them per your organisation's policy, which implies rotation is a manual request rather than an API operation. - Multi-account support is one token plus one regional base URL per
channel_account_id.
Objects we can read
Rates and serviceability (Checkout)
POST /v2/checkout is the rate shopping call: given origin, destination and package details, it returns the serviceable carriers ranked with rates and promised transit times. In v1 the equivalent is POST /v1/serviceability.
{
"referenceNumber": "127121232",
"timestamp": 1732093077572,
"status": "OK",
"carriers": [
{
"name": "DHL-EXPRESS",
"code": "DHL-EXPRESS",
"rank": 1,
"rate": {
"totalAmount": 34,
"currency": "GBP",
"breakUp": {
"freightCharge": 32,
"additionalCharges": [{ "amount": 2, "chargeHead": "Fuel Surcharge" }]
},
"uuid": "2e086999-eeba-4f5d-94d3-3a2b7673a6bc"
},
"score": 0,
"serviceType": "FIRST_OVERNIGHT",
"serviceName": "FedEx First Overnight",
"tatUnit": "DAY",
"tatValue": 2
}
]
}
The rate.uuid is worth holding: it is the handle for the quoted rate, which matters if you want the booked shipment to use the price you showed the customer. rank and score expose FarEye's own allocation decision.
The same endpoint is documented as usable on product display and listing pages, not just checkout, to show estimated delivery dates.
Consignments and shipments
A consignment is the order-level shipment record; a package is one physical box inside it. Consignments are tracked and billed as a single reference.
GET /v2/consignments/{referenceNumber}fetches one.- v1 additionally has
GET /v1/consignmentandGET /v1/shipmentsfor bulk listing, andGET /v1/shipments/{referenceNumber}. v2 drops the bulk list, so if you need to enumerate rather than look up, v1 is the version with that capability.
Consignment creation returns the tracking numbers and label URLs:
{
"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/staging/Carrier/UPS-NEW/label/ORDER_MB155.zpl",
"carrierDetails": { "name": "UPS-NEW", "code": "UPS-NEW", "info": {} }
}
]
}
]
}
Four identifiers coexist: your referenceNumber, your orderNumber, FarEye's consignmentNumber, and the carrier's trackingNumber per package, with a masterTrackingNumber across them. Store all of them.
Consignment types are FORWARD, REVERSE, EXCHANGE, TRANSFER and SERVICE, covering outbound delivery, customer returns, linked return-plus-replacement, internal stock movement between facilities, and technician visits.
Delivery slots
POST /v2/slots fetches available slots, POST /v2/reserve holds one to prevent double booking, and POST /v2/confirm-slot links it to the consignment. This three-step reserve-then-confirm pattern is designed for showing slots to a customer at checkout and is the right model for appointment-based delivery.
Routes, hubs, cities and fleet
POST/GET /v2/routes, plusPOST /v2/group-ordersto group orders by geofence.POST/PUT/GET /v2/hubsandGET /v2/hubs/{hubCode}for facility master data.POST/GET /v2/citiesfor city and pincode master data used in serviceability and rating.POST/GET /v2/vehicles,POST /v2/vehicles-delete,POST/PUT /v2/assetsandPOST /v2/assets-fetchfor fleet.POST/PUT/GET /v2/rostersandPOST /v2/rosters-deletefor workforce scheduling, processed in bulk with per-record success and failure feedback.POST /v2/etareturns an ETA,POST /v2/gps-pingspushes location pings, andPOST /v2/pickups-locationsfinds pickup points and lockers by address.
Users
POST/PUT/GET /v2/users and GET /v2/users/{hubCode} manage delivery agents, store managers, warehouse staff and administrators. These are operational staff records, not end customers.
Customers, orders, products, listings, inventory, settlements
Not applicable, this is a delivery platform. There is no catalogue, no inventory and no settlement object. Consignee details travel on the consignment as shipTo and are PII. Package-level item detail is carried as packageDetails[] with description, value, dimensions, weight, tags and an additionalInformation block that includes partNumber, manufacturerInfo and hazmatClass.
Writing back: listings, price and stock
Not applicable, this is a delivery platform. FarEye holds no catalogue, channel price or sellable stock, so there is nothing to write back in the listings sense.
The write surface is the consignment lifecycle:
The two-stage creation model is the interesting part and fits a warehouse workflow well:
- Planning stage. Create a consignment with no packages, using only order-level fields such as
referenceNumber,shipByDate,serviceTypeand routing information. This reserves a slot, plans a route and allocates a carrier before anything is packed. - Execution stage. Once pick and pack is done, update the consignment with
packageDetails. FarEye then generates carrier labels and tracking numbers.
Consignment request fields worth knowing: consignmentType, consignmentGroupId, routingPriority, serviceType, businessUnit, shipByDate, totalWeight and totalWeightUom, totalVolume and totalVolumeUom, totalPalletQuantity, paymentTobeCollected (with paymentMode, amount, currency), specialInstructions, deliveryInstructions, routingTags (for example TwoPerson), routingType (for example sameday_nextday) and labelFormat (PDF, with ZPL appearing in sample label URLs).
Updates are partial: referenceNumber is the only required field, omitted fields are left unchanged, and nested objects must be structurally complete if included. orderNumber cannot be changed, and carrier details cannot be changed once a label has been generated. A consignment cannot be edited once it is in Dispatched state or beyond, which is the constraint that will bite a naive sync job.
Pickup booking is a separate call and supports a pickup window, for example 10:00 to 14:00, so carrier SLA adherence can be measured.
Webhooks and notifications
The specification declares webhooks under x-webhooks, which means they are documented with full schemas rather than described in prose. Four are defined:
The v2 shipment payload is structured with event type, occurrence timestamp and data separated:
{
"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" }],
"driverName": "John",
"vehicleNumber": "DL12AAA1234",
"comments": "Left package with security guard"
}
}
This is the richest tracking payload of any carrier in this section. Three things make it valuable: the event carries both FarEye's harmonised status and the carrier's raw status, sub-status code and description, so you can normalise without losing the original; proof of delivery (signature or photo) arrives inline as a typed array rather than needing a second call; and receivedBy plus receivedByRelation capture who actually took the parcel, which is what disputes turn on.
Event types use a shipment:: or consignment:: prefix, for example shipment::out_for_delivery, shipment::delivered, consignment::delivered. The consignment webhook summarises all shipments under the consignment, so use it for order-level notifications and the shipment webhook for parcel-level detail.
The client supplies the endpoint, and the specification notes that if you prefer, FarEye will instead share its own endpoint for you to push to. No signature, HMAC or verification scheme is documented for the inbound direction, and no retry policy, timeout or ordering guarantee is published. Use an unguessable callback path, deduplicate on the webhook id, order events by occurredAt rather than arrival, and keep GET /v2/consignments/{referenceNumber} as a reconciliation path.
Rate limits and pagination
No rate limits are published in either specification. There are no quota headers, no 429 documentation and no throttling guidance anywhere in the OpenAPI files. Ask FarEye for numbers before running any sweep, and implement exponential backoff regardless.
Pagination is thin. GET /v2/rosters is documented as paginated. GET /v1/consignment and GET /v1/shipments are bulk list endpoints; v2 removed them, leaving only lookup by reference number. Everything else is keyed by identifier.
The practical consequence: on v2 there is no way to enumerate consignments, so the webhook stream is not optional. Design the connector around webhook ingestion with per-reference lookups for reconciliation, and keep a v1 fallback in mind if bulk enumeration turns out to be necessary.
Mapping to the unified model
Gaps and open questions
- No rate limits are published anywhere in either specification. Get numbers in writing.
- No webhook signature or verification mechanism is documented, and no retry or ordering guarantee is stated.
- v2 has no bulk consignment list endpoint, unlike v1. Confirm whether that is deliberate and what the supported backfill path is.
- The spec is tailored per account (per-client documentation portals exist), so required fields and available endpoints may differ from the public version. Get your account's spec.
- No token endpoint, no documented expiry and no programmatic rotation.
- Which regional host applies to a given account is an onboarding question with data-residency consequences.
- No COD remittance or settlement reporting appears anywhere, despite
paymentTobeCollectedbeing modelled on consignments. - ClickPost lists two FarEye entries, partner ids 31 and 38 ("Fareye" and "Fareye Reverse"), with order creation, cancellation, polling and webhook supported, POD and NDR not supported, and country listed as Kuwait and Oman. That contradicts FarEye's own specification, which documents POD inline in the webhook and covers eight regions. The aggregator matrix describes one specific ClickPost deployment, not FarEye's capability.
- The self-guide at
developer.fareye.com/self-guide.htmlwas not read in depth for this page and may contain onboarding detail worth checking.
Sources
- FarEye developer portal, read 2026-09-21, and the OpenAPI 3.0.1 specifications it serves for v1 and v2 (downloaded from the portal's Base64-encoded specification paths). Source of every endpoint, field, sample response, webhook schema and server URL above.
- FarEye homepage, read 2026-09-21. Product modules Ship, Route, Plan, Smart, Track, Execute, Experience, Grow and Analyze; industry verticals; corporate entity FarEye Technologies Pvt Ltd.
- Host probing on 2026-09-21:
docs.fareye.com,developers.fareye.com,api.fareye.com,apidocs.fareye.comandhelp.fareye.comdo not resolve.developer.fareye.comis the portal, anddeveloper.fareyeconnect.comredirects to it. - ClickPost, FarEye carrier integration, read 2026-09-21. Third-party capability matrix, partner ids 31 and 38. It disagrees with FarEye's own specification on POD support and geography.