How it works The integration in 60 seconds
FarEye is a delivery orchestration platform used by your shipper (the retailer or brand) to manage their last-mile operations. When the shipper dispatches an order to you, FarEye sends your API a structured consignment payload. You accept it, return tracking details, and push status updates as the delivery progresses.
Shipper
Retailer / Brand
Order
FarEye
Orchestrate
Consignment
You
Carrier
Track + Label
FarEye
Normalise
Status
Shipper
Order updated
💡
Three things you need to build: (1) An endpoint to receive consignment payloads from FarEye, (2) a response that returns tracking numbers and label URLs, and (3) a mechanism to push delivery status updates back to FarEye.
What you need to build Your integration deliverables
A. Receive Consignment endpoint (POST)
Expose an HTTPS endpoint that accepts FarEye's Create Consignment payload. This is the primary API. When FarEye dispatches an order to you, it POSTs the consignment to this endpoint. You process it (create the shipment in your system, generate tracking, generate label) and return a response.
B. Return tracking details + label URL
Your response must include a tracking number for each shipment in the consignment and (optionally) a label URL. FarEye forwards these to the shipper and their end customer. See Response format for the exact structure.
C. Push status updates to FarEye
As the delivery progresses (picked up, in transit, out for delivery, delivered, failed), push status events to FarEye's status update API. FarEye normalises these and forwards them to the shipper. See Pushing statuses.
📋
If you already have a standard API (e.g., DHL Shipment API, UPS Shipping API, FedEx Ship API), FarEye can often map to your existing format during implementation. This spec is for carriers building a new integration endpoint for consignments flowing through FarEye.
Request payload What FarEye sends to your endpoint
When FarEye dispatches a consignment to you, it POSTs the following JSON payload to your endpoint. Below is a representative example with all key fields populated.
FarEye → Your Endpoint: Create ConsignmentPOST
{
// ── Core identifiers ──
"reference_id": "ORD-2026-44821",
"order_number": "ORD-2026-44821",
"consignment_number": "CON-FE-88412",
"tracking_number": "7803820965",
"carrier_code": "DHL",
"carrier_name": "DHL Express",
"shipper_code": "ACME",
"merchant_code": "merchant_eu_01",
// ── Order classification ──
"type_of_action": "CREATE", // CREATE | UPDATE | CANCEL
"type_of_order": "Forward", // Forward | Reverse
"type_of_service": "Express", // Express | Standard | Economy | White Glove
"main_modality": "Parcel", // Parcel | LTL | FTL
// ── Origin (warehouse / pickup) ──
"origin_code": "WH-AMS-01",
"origin_name": "Warehouse Amsterdam",
"origin_address_line1": "Schipholweg 275",
"origin_address_line2": "Building B, Dock 4",
"origin_city": "Hoofddorp",
"origin_state_province": "NH",
"origin_country": "NL",
"origin_postal_code": "2142 LD",
"origin_contact_person": "Warehouse Ops",
"origin_contact_number": "+31201234567",
"origin_email": "warehouse@shipper.com",
"origin_latitude": "52.2867",
"origin_longitude": "4.6846",
"origin_preferred_start_time": "2026-04-15 08:00:00",
"origin_preferred_end_time": "2026-04-15 12:00:00",
// ── Destination (end customer) ──
"destination_name": "Jan de Vries",
"destination_address_line1": "Kalverstraat 92",
"destination_city": "Amsterdam",
"destination_state_province": "NH",
"destination_country": "NL",
"destination_postal_code": "1012 PH",
"destination_contact_person": "Jan de Vries",
"destination_contact_number": "+31612345678",
"destination_email": "jan@email.nl",
"destination_latitude": "52.3702",
"destination_longitude": "4.8952",
// ── Shipment details ──
"total_weight": 11.13,
"uom_total_weight": "KG",
"total_volume": 0.08,
"total_volume_uom": "CBM",
"number_of_shipments": 1,
"shipping_date_time": "2026-04-15 10:00:00",
"shipping_timezone": "CET",
"delivery_slot": "14:00:00 - 18:00:00",
"delivery_instructions": "Leave at front desk if not home",
"special_instructions": "Fragile — handle with care",
"label_format": "PDF",
"payment_mode": "Prepaid",
"currency_code": "EUR",
// ── Line items ──
"item_list": [
{
"item_reference_number": "SKU-8842-01",
"item_code": "LAMP-TBL-01",
"item_name": "Table Lamp — Nordic Oak",
"item_quantity": 2,
"item_value": 89.99,
"item_weight": 3.2,
"item_weight_uom": "KG",
"item_length": 45,
"item_width": 25,
"item_height": 25,
"item_dimension_uom": "CM",
"item_volume": 0.028,
"item_volume_uom": "CBM",
"item_uom": "EACH",
"harmonized_code": "9405.20",
"instructions": "Fragile — glass shade"
}
],
// ── Value-added services (optional) ──
"vas": [
{
"vas_code": "SIGNATURE_REQUIRED",
"level": "ORDER",
"service_time": 5,
"remark": "Signature required at delivery"
}
],
// ── SKU details (optional — for customs / compliance) ──
"sku_list": [
{
"sku_code": "LAMP-TBL-01",
"sku_item_name": "Table Lamp — Nordic Oak",
"sku_quantity": 2,
"sku_item_unit_price": "89.99",
"sku_weight": 3.2,
"sku_weight_uom": "KG",
"sku_hsn_code": "9405.20",
"sku_origin_country": "CN"
}
]
}Field reference Every field, its requirement level, and what it means
Fields marked Mandatory will always be present and your endpoint must accept them. Recommended fields are sent when available and should be processed if present. Optional fields may or may not be included.
| Field | Required? | Description |
|---|---|---|
| Core Identifiers | ||
| reference_id | Mandatory | Unique order reference from the shipper. Use this to correlate across all systems. |
| order_number | Mandatory | Order number. Return this in all status updates and in the response. |
| consignment_number | Mandatory | FarEye's internal consignment ID. |
| tracking_number | Recommended | Pre-assigned tracking number. If blank, you must generate one and return it in the response. |
| carrier_code | Mandatory | Your carrier code in FarEye (e.g., DHL, UPS). |
| carrier_name | Mandatory | Your carrier display name. |
| shipper_code | Mandatory | Shipper/customer identifier. Used for billing and routing rules. |
| merchant_code | Recommended | Merchant ID for multi-merchant shippers. |
| Order Classification | ||
| type_of_action | Mandatory | CREATE, UPDATE, or CANCEL. |
| type_of_order | Mandatory | Forward (delivery) or Reverse (return/pickup). |
| type_of_service | Mandatory | Express, Standard, Economy, White Glove. |
| main_modality | Mandatory | Parcel, LTL, FTL. |
| Origin Address (pickup / warehouse) | ||
| origin_name | Mandatory | Location name. |
| origin_address_line1 | Mandatory | Street address. line2 and line3 are optional. |
| origin_city | Mandatory | City. |
| origin_state_province | Recommended | State or province code. |
| origin_country | Mandatory | Country name or ISO code. |
| origin_postal_code | Mandatory | Postal / ZIP code. |
| origin_contact_number | Mandatory | Phone for pickup coordination. |
| origin_latitude / longitude | Recommended | GPS for precise pickup. |
| origin_preferred_start/end_time | Recommended | Pickup time window. Format: YYYY-MM-DD HH:MM:SS. |
| Destination Address (end customer) | ||
| destination_name | Mandatory | Recipient name. |
| destination_address_line1 | Mandatory | Street address. |
| destination_city | Mandatory | City. |
| destination_country | Mandatory | Country. |
| destination_postal_code | Mandatory | Postal code. |
| destination_contact_number | Mandatory | Recipient phone — used for delivery notifications. |
| destination_latitude / longitude | Recommended | GPS for delivery accuracy. |
| Shipment Details | ||
| total_weight / uom | Mandatory | Total weight with unit (KG or LB). |
| total_volume / uom | Recommended | Total volume (CBM). Critical for big & bulky. |
| number_of_shipments | Mandatory | Number of physical packages. |
| shipping_date_time | Mandatory | When shipment is ready for pickup. Format: YYYY-MM-DD HH:MM:SS. |
| shipping_timezone | Recommended | Timezone of shipping_date_time (e.g., CET, GMT). |
| delivery_slot | Recommended | Requested delivery window (e.g., 14:00:00 - 18:00:00). |
| delivery_instructions | Recommended | General delivery instructions. |
| special_instructions | Recommended | Special handling (fragile, two-man, call before). |
| label_format | Recommended | Preferred label format: PDF, ZPL, PNG. |
| payment_mode | Optional | Prepaid or COD. |
| amount_to_be_collected | Optional | COD amount (if payment_mode is COD). |
| currency_code | Recommended | ISO currency code (e.g., EUR, USD). |
| Item List (line items — array) | ||
| item_reference_number | Mandatory | Unique item identifier. |
| item_name | Mandatory | Item description. |
| item_quantity | Mandatory | Quantity of this item. |
| item_weight / uom | Mandatory | Item weight with unit. |
| item_length / width / height / uom | Recommended | Dimensions. Important for volumetric pricing. |
| item_value | Recommended | Declared value per item. |
| harmonized_code | Optional | HS code for cross-border customs. |
| instructions | Optional | Per-item handling instructions. |
| VAS — Value-Added Services (array, optional) | ||
| vas_code | Recommended | Service code: TWO_MAN_DELIVERY, INSTALLATION, HAUL_AWAY_OLD, SIGNATURE_REQUIRED. |
| level | Recommended | ORDER or SKU — whether the VAS applies to the whole order or specific items. |
| target_ids | Optional | Array of item/SKU codes this VAS applies to (when level = SKU). |
| service_time | Optional | Estimated service time in minutes. |
| SKU List (optional — for customs / compliance) | ||
| sku_code / sku_item_name | Optional | SKU-level product details for customs declarations. |
| sku_origin_country | Optional | Country of manufacture — required for cross-border. |
| sku_hsn_code | Optional | Harmonised code at SKU level. |
⚠️
Additional objects: The full payload may also include
shipper (if shipper differs from origin), bill_to (billing address + tax ID), and info.packageVehicleDetails (vehicle, BoL, RMA references). Your FarEye implementation contact will confirm which objects are active for your integration.Response format What you must return to FarEye
Your endpoint must respond with HTTP 200 and a JSON body containing tracking details for each shipment in the consignment.
Your Endpoint → FarEye: Response200 OK
{
"status": 200,
"reference_id": "ORD-2026-44821",
"timestamp": 1713178800000,
"execution_time": 1530,
"items_track_details": [
{
"tracking_number": "7803820965",
"label_url": "https://your-cdn.com/labels/7803820965.pdf",
"carrier_code": "DHL",
"order_number": "ORD-2026-44821"
}
]
}Response field reference
| Field | Required? | Description |
|---|---|---|
| status | Mandatory | HTTP status code. 200 for success. |
| reference_id | Mandatory | Echo back the reference_id from the request. |
| timestamp | Recommended | Unix timestamp (ms) of when you processed the request. |
| execution_time | Optional | Processing time in ms (useful for performance monitoring). |
| items_track_details | Mandatory | Array — one entry per shipment/package in the consignment. |
| → tracking_number | Mandatory | Your tracking number for this shipment. If one was pre-assigned in the request, echo it back. Otherwise generate and return a new one. |
| → label_url | Recommended | URL to download the shipping label (PDF, ZPL, or PNG). FarEye fetches this and forwards to the shipper. |
| → carrier_code | Mandatory | Your carrier code (echo from request). |
| → order_number | Mandatory | Order number (echo from request). |
💡
Multi-package consignments: If the consignment contains multiple packages (e.g., a sofa shipped in 2 boxes), return one entry in
items_track_details per package, each with its own tracking number and label URL.Pushing status updates Keep FarEye informed as delivery progresses
As the consignment moves through your network, push status events to FarEye's status update endpoint. FarEye normalises your statuses and forwards them to the shipper in real time.
1. FarEye provides a status update endpoint
During implementation, FarEye shares an HTTPS endpoint URL and credentials. You push status events to this endpoint as they occur.
2. You POST status updates for each event
When a shipment is picked up, in transit, at hub, out for delivery, delivered, or failed — send a status update with the tracking number, new status, timestamp, and any supporting details (GPS, POD).
3. FarEye normalises and forwards
FarEye maps your status codes to its normalised status model and pushes the update to the shipper's system via webhook. The shipper only handles one consistent format regardless of how many carriers they use.
📋
Status update API details (endpoint URL, authentication, exact payload format) will be shared by your FarEye implementation contact during onboarding. The format is standardised across all carriers integrated with FarEye.
Status mapping Your statuses → FarEye normalised statuses
FarEye will map your status codes to its normalised model during implementation. Below are the standard lifecycle events that FarEye expects. You can use your own status codes — the mapping is configured per carrier.
SHIPMENT_CREATED
→
Order Created
PICKED_UP
→
Order Picked Up
IN_TRANSIT
→
In Transit
AT_HUB / AT_FACILITY
→
At Facility
OUT_FOR_DELIVERY
→
Out for Delivery
DELIVERED
→
Order Delivered
DELIVERY_FAILED
→
Delivery Failed
RETURNED_TO_ORIGIN
→
Returned to Origin
🔄
Your own codes are fine. If you use
PKG_PICKED instead of PICKED_UP, that's no problem — FarEye's event mapping is configured per carrier during onboarding. Just make sure you can push the status events listed above (or equivalents) for a complete delivery lifecycle.Authentication How FarEye authenticates with you (and vice versa)
FarEye → Your endpoint
FarEye will authenticate with your endpoint using the method you specify — typically Bearer token, API key header, or Basic Auth. Provide your preferred authentication method and credentials to the FarEye implementation team during onboarding.
Your system → FarEye status endpoint
FarEye will provide you with an access token and endpoint URL for pushing status updates. Include the token as a Bearer token in the Authorization header of every status update request.
FAQ & troubleshooting Common questions from carrier tech teams
Your endpoint must accept the full JSON payload without error. However, you only need to process the fields marked Mandatory and Recommended. Optional fields can be safely ignored if they're not relevant to your system. Do not reject the request because of unexpected fields.
If you have an existing API (DHL Shipment API, UPS Shipping API, etc.), FarEye can often map to your format. Share your API documentation with the FarEye implementation team and they'll build a mapping layer. This spec is primarily for carriers building a new endpoint.
FarEye retries failed consignment dispatches with configurable retry logic. Exact retry count and intervals are agreed during implementation. The shipper's team can also manually retry from the FarEye dashboard.
When
type_of_action is UPDATE, treat it as a modification to an existing consignment (use reference_id to look up the original). When CANCEL, cancel the shipment and any pending labels/tracking. Return a 200 response confirming the action.At minimum, support
PDF. ZPL (Zebra Printer Language) is needed if the shipper uses thermal printers. The label_format field in the request tells you which format to generate. Return the label as a URL in label_url — FarEye will fetch it.FarEye expects a response within 30 seconds. If label generation takes longer, consider responding immediately with the tracking number and a placeholder label URL, then updating the label URL asynchronously via a status update.
Common VAS codes:
TWO_MAN_DELIVERY (two-person crew), INSTALLATION (install the product), HAUL_AWAY_OLD (remove old item), ROOM_OF_CHOICE (deliver to specific room), SIGNATURE_REQUIRED. The shipper's FarEye setup determines which VAS codes are active — you'll be told during onboarding.Ready to integrate?
Contact the FarEye implementation team to get your endpoint URL, authentication credentials, and access to the sandbox environment for testing.