Carrier integration with FarEye — everything your tech team needs.

FarEye orchestrates deliveries for your shipper. When an order is dispatched to you, FarEye sends your API a consignment payload. You process it, return tracking details, and push status updates as delivery progresses.

You receive
Consignment →
You return
Tracking + Label
You push
← Status events

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
{
  "referenceId": "12778_2206901100_0001",
  "orderNumber": "2206901100",
  "consignmentNumber": "2206901100",
  "exchangeOrderNumber": "",
  "typeOfOrder": "FORWARD",
  "typeOfService": "GROUND",
  "typeOfAction": "UPDATE",
  "carrierCode": "UPS",
  "merchantCode": "AMAZON",
  "shipperTaxNumber": "12-3456789",

  "originType": "BUSINESS",
  "originTimezone": "America/New_York",
  "originCode": "NYC01",
  "originShipFromCode": "NYC01",
  "originName": "Amazon Fulfillment Center",
  "originCompanyName": "Amazon Inc.",
  "originContactPerson": "John Smith",
  "originContactNumber": "+1-212-555-7890",
  "originContactNumber2": "",
  "originEmail": "support@amazon.com",
  "originAddressLine1": "410 Terry Ave N",
  "originAddressLine2": "",
  "originAddressLine3": "",
  "originLandmark": "",
  "originCity": "Seattle",
  "originCounty": "King",
  "originStateProvince": "WA",
  "originCountry": "US",
  "originPostalCode": "98109",
  "originPoBoxNumber": "",
  "originLatitude": "47.6062",
  "originLongitude": "-122.3321",
  "originPreferredStartTime": "",
  "originPreferredEndTime": "",

  "destinationType": "RESIDENTIAL",
  "destinationTimezone": "America/Los_Angeles",
  "destinationCode": "LAX01",
  "destinationShipToCode": "LAX01",
  "destinationName": "Customer Address",
  "destinationCompanyName": "",
  "destinationContactPerson": "Emily Johnson",
  "destinationContactNumber": "+1-310-555-1234",
  "destinationContactNumber2": "",
  "destinationEmail": "emily.johnson@email.com",
  "destinationAddressLine1": "1234 Sunset Blvd",
  "destinationAddressLine2": "Apt 12",
  "destinationAddressLine3": "",
  "destinationLandmark": "",
  "destinationCity": "Los Angeles",
  "destinationCounty": "Los Angeles",
  "destinationStateProvince": "CA",
  "destinationCountry": "US",
  "destinationPostalCode": "90026",
  "destinationPoBoxNumber": "",
  "destinationLatitude": "34.0522",
  "destinationLongitude": "-118.2437",
  "destinationPreferredStartTime": "",
  "destinationPreferredEndTime": "",

  "numberOfShipments": 1,
  "totalQuantity": 1,
  "totalWeight": 5.5,
  "uomTotalWeight": "LB",
  "totalVolume": 2.5,
  "totalVolumeUom": "CFT",
  "paymentMode": "PREPAID",
  "amountToBeCollected": 0.0,
  "invoiceValue": 199.99,
  "currencyCode": "USD",
  "shippingDateTime": "2026-04-17 00:00:00",
  "deliveryInstructions": "Leave at front door",
  "labelFormat": "PDF",
  "slotToken": "a3693e24-0cc9-4ae4-9f43-23e773205019",

  "itemList": [
    {
      "itemReferenceNumber": "0001",
      "itemCode": "ELEC001",
      "itemName": "Wireless Headphones",
      "itemStatus": "",
      "itemQuantity": 1,
      "itemValue": 199.99,
      "itemSpecialInstruction": "Handle with care",
      "itemDeliveryServiceTime": 0,
      "itemLength": 10.0,
      "itemWidth": 8.0,
      "itemHeight": 6.0,
      "itemDimensionUom": "IN",
      "itemWeight": 5.5,
      "itemWeightUom": "LB",
      "itemVolume": 2.5,
      "itemVolumeUom": "CFT",
      "itemTrackingNumber": "",
      "instructions": "",
      "tags": []
    }
  ],
  "skuList": [
    {
      "itemReferenceNumber": "0001",
      "skuCode": "WH-1000XM5",
      "skuNumber": "WH-1000XM5",
      "skuItemName": "Sony Headphones",
      "skuItemDescription": "Noise Cancelling Headphones",
      "skuCategory": "Electronics",
      "skuQuantity": 1,
      "skuItemUnitPrice": "199.99",
      "skuWeight": 5.5,
      "skuWeightUom": "LB",
      "skuLength": 10.0,
      "skuWidth": 8.0,
      "skuHeight": 6.0,
      "skuDimensionUom": "IN",
      "skuVolume": 2.5,
      "skuVolumeUom": "CFT",
      "skuHsnCode": "851830",
      "skuOriginCountry": "US",
      "skuDeliveryServiceTime": 0,
      "skuPickupServiceTime": 0,
      "skuLineItemNo": "0001",
      "skuItemSequence": 0,
      "skuUom": "",
      "skuImageUrl": ""
    }
  ],
  "vas": [
    {
      "vasCode": "TWO_MAN_DELIVERY",
      "level": "SKU",
      "targetIds": ["0001"],
      "serviceTime": 5,
      "remark": "Customer signature required"
    }
  ],
  "shipper": {
    "name": "Amazon Inc.",
    "addressLine1": "410 Terry Ave N",
    "city": "Seattle",
    "stateProvince": "WA",
    "country": "US",
    "postalCode": "98109",
    "contactPerson": "John Smith",
    "contactNumber": "+1-212-555-7890",
    "email": "support@amazon.com",
    "companyName": "Amazon Inc."
  },
  "billTo": {
    "name": "Emily Johnson",
    "addressLine1": "1234 Sunset Blvd",
    "city": "Los Angeles",
    "stateProvince": "CA",
    "country": "US",
    "postalCode": "90026",
    "contactPerson": "Emily Johnson",
    "contactNumber": "+1-310-555-1234",
    "email": "emily.johnson@email.com"
  },
  "info": {}
}

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.

CI Core Identifiers 7 mandatory
Field Required Description
referenceId
 Mandatory Unique order reference from the shipper’s system. Used for correlation across all systems.
orderNumber
 Mandatory Order number — the carrier should return this in all status updates.
consignmentNumber
 Mandatory FarEye’s internal consignment identifier. Used for cross-referencing in FarEye’s system.
exchangeOrderNumber
 Optional Exchange order reference for swap or exchange flows.
typeOfOrder
 Mandatory FORWARD (delivery) or REVERSE (return pickup).
typeOfService
 Mandatory Service level: GROUND, EXPRESS, STANDARD, ECONOMY.
typeOfAction
 Mandatory CREATE, UPDATE, or CANCEL. Tells the carrier what operation to perform.
carrierCode
 Mandatory Carrier identifier in FarEye (e.g., UPS, DHL, TNT).
merchantCode
 Recommended Merchant identifier for multi-merchant setups.
shipperTaxNumber
 Optional Shipper’s tax identification number (e.g., EIN, VAT).
OA Origin Address 6 mandatory
Field Required Description
originType
 Recommended BUSINESS or RESIDENTIAL.
originTimezone
 Recommended IANA timezone (e.g., America/New_York).
originCode
 Recommended Facility identifier for the origin warehouse or DC.
originShipFromCode
 Optional Ship-from location code.
originName
 Mandatory Origin location name (warehouse, DC, store).
originCompanyName
 Optional Company name at origin.
originContactPerson
 Recommended Contact person at origin.
originContactNumber
 Mandatory Phone number for pickup coordination.
originContactNumber2
 Optional Alternate phone number.
originEmail
 Recommended Email address at origin.
originAddressLine1
 Mandatory Street address. originAddressLine2 and originAddressLine3 are optional.
originLandmark
 Optional Nearby landmark for location identification.
originCity
 Mandatory City name.
originCounty
 Optional County or district.
originStateProvince
 Optional State or province code.
originCountry
 Mandatory Country code (ISO 3166-1 alpha-2).
originPostalCode
 Mandatory Postal / ZIP code.
originPoBoxNumber
 Optional PO Box number.
originLatitude / originLongitude
 Recommended GPS coordinates for precise pickup location.
originPreferredStartTime / EndTime
 Optional Preferred pickup time window.
DA Destination Address 5 mandatory
Field Required Description
destinationType
 Recommended BUSINESS or RESIDENTIAL.
destinationTimezone
 Recommended IANA timezone (e.g., America/Los_Angeles).
destinationCode
 Recommended Internal destination location code.
destinationShipToCode
 Optional Ship-to location code.
destinationName
 Optional Recipient name or location.
destinationCompanyName
 Optional Company name at destination.
destinationContactPerson
 Recommended Contact person at destination.
destinationContactNumber
 Mandatory Recipient phone — used for delivery notifications and driver contact.
destinationContactNumber2
 Optional Alternate phone number.
destinationEmail
 Recommended Recipient email address.
destinationAddressLine1
 Mandatory Street address. destinationAddressLine2 and destinationAddressLine3 are optional.
destinationLandmark
 Optional Nearby landmark for location identification.
destinationCity
 Mandatory City name.
destinationCounty
 Optional County or district.
destinationStateProvince
 Recommended State or province code.
destinationCountry
 Mandatory Country code (ISO 3166-1 alpha-2).
destinationPostalCode
 Mandatory Postal / ZIP code.
destinationPoBoxNumber
 Optional PO Box number.
destinationLatitude / destinationLongitude
 Recommended GPS coordinates for precise delivery location.
destinationPreferredStartTime / EndTime
 Optional Preferred delivery time window.
SD Shipment Details 6 mandatory
Field Required Description
numberOfShipments
 Mandatory Number of physical packages in this consignment.
totalQuantity
 Mandatory Total item quantity across all packages.
totalWeight
 Mandatory Total shipment weight. Used for rate calculation and vehicle planning.
uomTotalWeight
 Mandatory Weight unit: KG or LB.
totalVolume
 Recommended Total shipment volume. Critical for big & bulky shipments.
totalVolumeUom
 Recommended Volume unit: CBM, CFT.
paymentMode
 Optional PREPAID, COD, or CREDIT.
amountToBeCollected
 Optional Cash-on-delivery amount to collect from recipient.
invoiceValue
 Optional Declared invoice value of the shipment.
currencyCode
 Optional ISO 4217 currency code (e.g., USD, EUR).
shippingDateTime
 Mandatory When the shipment is ready for carrier pickup. Format: YYYY-MM-DD HH:MM:SS.
deliveryInstructions
 Recommended General delivery instructions (e.g., “Leave at front door”).
labelFormat
 Recommended Preferred label format: PDF, ZPL, PNG.
slotToken
 Optional Delivery slot reservation token from slot-booking flow.
IL Item List · itemList[] 4 mandatory
Field Required Description
itemReferenceNumber
 Mandatory Unique item / line identifier.
itemCode
 Optional Item code.
itemName
 Optional Item description for manifesting and proof of delivery.
itemStatus
 Optional Current item status.
itemQuantity
 Mandatory Number of units of this item.
itemValue
 Optional Declared value of this item.
itemSpecialInstruction
 Optional Special handling instructions for this item (e.g., “Handle with care”).
itemDeliveryServiceTime
 Optional Service time in minutes at the delivery stop for this item.
itemLength / itemWidth / itemHeight
 Recommended Item dimensions. Important for bulky items and volumetric pricing.
itemDimensionUom
 Recommended Dimension unit: IN, CM.
itemWeight
 Mandatory Per-item weight.
itemWeightUom
 Mandatory Weight unit: KG or LB.
itemVolume / itemVolumeUom
 Optional Per-item volume with unit.
itemTrackingNumber
 Optional Item-level tracking number (if pre-assigned).
instructions
 Optional Additional delivery instructions for this item.
tags
 Optional Array of tags for custom categorisation or filtering.
SK SKU List · skuList[] 4 mandatory
Field Required Description
itemReferenceNumber
 Mandatory Links this SKU entry to an itemList item.
skuCode / skuNumber
 Mandatory SKU code and number identifiers.
skuItemName
 Mandatory SKU item display name.
skuItemDescription
 Recommended Detailed item description.
skuCategory
 Optional Product category (e.g., Electronics, Apparel).
skuQuantity
 Mandatory Quantity of this SKU.
skuItemUnitPrice
 Optional Unit price for customs and insurance.
skuWeight / skuWeightUom
 Recommended SKU weight and unit.
skuLength / skuWidth / skuHeight
 Optional SKU dimensions.
skuDimensionUom
 Optional Dimension unit: IN, CM.
skuVolume / skuVolumeUom
 Optional SKU volume and unit.
skuHsnCode
 Optional HSN / HS code for customs and compliance.
skuOriginCountry
 Optional Country of origin (ISO code).
skuDeliveryServiceTime / skuPickupServiceTime
Optional Service time in minutes at delivery/pickup stop.
skuLineItemNo / skuItemSequence
 Optional Line-item number and sort sequence.
skuUom
 Optional Unit of measure for this SKU.
skuImageUrl
 Optional Product image URL.
VA Value-Added Services · vas[] 0 mandatory
Field Required Description
vasCode
 Recommended Service code (e.g., TWO_MAN_DELIVERY, HAUL_AWAY_OLD, INSTALLATION). Carriers must support these if the shipper requires them.
level
 Recommended Application level: SKU (per-item) or CONSIGNMENT (whole shipment).
targetIds
 Recommended Array of item reference numbers this VAS applies to.
serviceTime
 Optional Estimated service time in minutes at the stop (e.g., 30 for installation).
remark
 Optional Additional notes for this service (e.g., “Customer signature required”).
SH Shipper · shipper 0 mandatory
Field Required Description
name
 Recommended Shipper’s name.
companyName
 Recommended Shipper company name.
addressLine1
 Recommended Shipper street address.
city / stateProvince / country / postalCode
 Recommended Shipper location details.
contactPerson / contactNumber / email
 Recommended Shipper contact details.
BT Bill To · billTo 0 mandatory
Field Required Description
name
 Optional Billing contact name.
addressLine1
 Optional Billing street address.
city / stateProvince / country / postalCode
 Optional Billing location details.
contactPerson / contactNumber / email
 Optional Billing contact details.
IN Info · info 0 mandatory
Field Required Description
info
 Optional Extensible JSON object for custom key-value pairs (e.g., vehicle details, BoL references). Your FarEye implementation manager will confirm which keys are relevant.
⚠️
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,
  "referenceId": "ORD-2026-44821",
  "timestamp": 1713178800000,
  "itemsTrackDetails": [
    {
      "itemReferenceNumber": "911121176-1",
      "trackingNumber": "7803820965",
      "labelUrl": "https://carrier.com/labels/7803820965.pdf",
      "carrierCode": "DHL",
      "orderNumber": "ORD-2026-44821"
    }
  ]
}

If the request is invalid or missing required fields, the carrier should respond with a 400 status and return an array of error messages describing what went wrong.

Carrier → FarEye: Error Response400
{
  "status": 400,
  "referenceId": "TPKSD2002060000778-KNJ020000013",
  "timestamp": 1582546365396,
  "errors": [
    "The order number is missing"
  ]
}

Response field reference

Field Required? Description
status Mandatory HTTP status code. 200 for success.
referenceId Mandatory Echo back the reference_id from the request.
timestamp Recommended Unix timestamp (ms) of when you processed the request.
executionTime Optional Processing time in ms (useful for performance monitoring).
itemsTrackDetails Mandatory Array — one entry per shipment/package in the consignment.
→ trackingNumber 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.
→ labelUrl Recommended URL to download the shipping label (PDF, ZPL, or PNG). FarEye fetches this and forwards to the shipper.
→ carrierCode Mandatory Your carrier code (echo from request).
→ orderNumber 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.
4. FarEye Respond with 200 OK
FarEye return HTTP 200 within 30 seconds. Failed webhooks are retried up to 4 times (30-min buffer).

Sample webhook payload

Below is a representative webhook event payload. Carrier can use this JSON to POSTs FarEye system.

Carrier → FarEye: Push Status UpdatePOST
{
  "orderNo": "ORD123456",
  "type": "Tracking",
  "value": "1Z999AA10123456784",
  "consignmentNumber": "CON123456789",
  "carrierCode": "DHL",
  "carrierStatus": "Delivered",
  "carrierStatusCode": "DLV",
  "carrierStatusDescription": "Shipment Delivered Successfully",
  "carrierSubStatus": "Consignee Not Available",
  "carrierSubStatusCode": "016",
  "carrierSubStatusDescription": "Customer not available at delivery address",
  "statusReceivedAt": "2025-08-06 07:45:00",
  "eventTimezone": "Asia/Kolkata",
  "locationCode": "DL112",
  "locationName": "Delhi Hub",
  "latitude": "28.6448",
  "longitude": "77.216721",
  "lastUpdatedAt": "2025-08-06 08:00:00",
  "statusIdentifierValue": "FORWARD",
  "extraInfo": {
    "comments": "Left package with security guard",
    "promisedDeliveryDate": "2025-08-10",
    "expectedDeliveryDate": "2025-08-09",
    "receivedBy": "John Doe",
    "relation": "Security Guard",
    "pod": [
      {
        "type": "SIGNATURE",
        "url": "https://cdn.fareye.com/pod/12345-signature.png"
      }
    ],
    "signature": "https://cdn.fareye.com/pod/12345-signature.png"
  },
  "driverName": "John",
  "vehicleNumber": "DL12AAA1234",
  "info": {
    "additionalNotes": "Handle with care"
  },
  "installationItems": [
    {
      "itemReferenceNumber": "SKU-12345",
      "level": "SKU",
      "targetIds": [
        "SKU0001"
      ],
      "vasCode": "ROOM_OF_CHOICE",
      "status": "Completed",
      "statusCode": "ASSEMBLED",
      "statusTime": "2025-08-06 10:00:00"
    }
  ]
}
📋
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.

Contact FarEye Integration Team