Relay API

endpoints

What merchants call, what recipients call without an account, and what handhelds push

Shipments5 endpointsGET /v1/shipments · List the calling merchant's shipments, newest first · auth: api-key · → Shipment[]GET/v1/shipments200 401🔒 api-keyList the calling merchant's shipments, newest firstPOST /v1/shipments · Book a shipment and mint a tracking number per parcel · auth: api-key · → ShipmentPOST/v1/shipments201 400 402 422🔒 api-keyBook a shipment and mint a tracking number per parcelGET /v1/shipments/{id} · One shipment with all of its parcels · auth: api-key · → ShipmentGET/v1/shipments/{id}200 404🔒 api-keyOne shipment with all of its parcelsPOST /v1/shipments/{id}/cancel · Cancel before collection; fails once any parcel has been scanned · auth: api-key · → ShipmentPOST/v1/shipments/{id}/cancel200 404 409🔒 api-keyCancel before collection; fails once any parcel has been scannedGET /v1/parcels/{id}/label · The printable label as a PDF · auth: api-key · → application/pdfGET/v1/parcels/{id}/label200 404🔒 api-keyThe printable label as a PDFTracking4 endpointsGET /v1/track/{tracking_number} · Public tracking history for one parcel · → TrackingEvent[]GET/v1/track/{tracking_number}200 404 429Public tracking history for one parcelPOST /v1/track/{tracking_number}/reschedule · Pick another delivery day · auth: otp · → TrackingEventPOST/v1/track/{tracking_number}/reschedule200 409 410🔒 otpPick another delivery dayPOST /v1/track/{tracking_number}/redirect · Send it to a neighbour or a safe place instead · auth: otp · → TrackingEventPOST/v1/track/{tracking_number}/redirect200 409 410🔒 otpSend it to a neighbour or a safe place insteadGET /track/{tracking_number} · Unversioned tracking; use /v1/track · → TrackingEvent[]GET/track/{tracking_number}deprecated200 404Unversioned tracking; use /v1/trackField devices3 endpointsPOST /v1/scans · Upload a batch of scans taken while offline · auth: mtls · → ScanBatchResultPOST/v1/scans202 207 401🔒 mtlsUpload a batch of scans taken while offlinePOST /v1/attempts · Record a failed delivery attempt with a reason and a photo · auth: mtls · → TrackingEventPOST/v1/attempts201 401 422🔒 mtlsRecord a failed delivery attempt with a reason and a photoGET /v1/routes/{id}/manifest · Today's sequenced stops for a driver, cacheable offline · auth: mtls · → Stop[]GET/v1/routes/{id}/manifest200 404🔒 mtlsToday's sequenced stops for a driver, cacheable offlineNetwork operations2 endpointsGET /v1/depots · Every depot and the postcodes it serves · auth: bearer · → Depot[]GET/v1/depots200🔒 bearerEvery depot and the postcodes it servesPOST /v1/routes/{id}/sequence · Ask the routing engine to order the stops · auth: bearer · → RoutePOST/v1/routes/{id}/sequence200 409 503🔒 bearerAsk the routing engine to order the stopsPublished events3 endpointsEVENT parcel.delivered · Published when a delivery scan lands · → ParcelDeliveredEventEVENTparcel.deliveredPublished when a delivery scan landsEVENT parcel.attempt-failed · Published when a courier records a failed attempt · → ParcelAttemptEventEVENTparcel.attempt-failedPublished when a courier records a failed attemptEVENT parcel.exception · Published when a parcel is marked lost or begins returning · → ParcelExceptionEventEVENTparcel.exceptionPublished when a parcel is marked lost or begins returningTypes (8)CreateShipmentInputCreateShipmentInputinputreference · stringreferencestringservice_level · ServiceLevel!service_levelServiceLevel!recipient · RecipientInput!recipientRecipientInput!destination · AddressInput!destinationAddressInput!parcels · ParcelInput[]!parcelsParcelInput[]!ShipmentShipmentobjectid · uuid!iduuid!reference · stringreferencestringservice_level · ServiceLevel!service_levelServiceLevel!parcels · Parcel[]!parcelsParcel[]!booked_at · datetime!booked_atdatetime!ParcelParcelobjectid · uuid!iduuid!tracking_number · string!tracking_numberstring!status · ParcelStatus!statusParcelStatus!attempts · int!attemptsint!weight_grams · int!weight_gramsint!TrackingEventTrackingEventobjecttype · ScanType!typeScanType!at · datetime!atdatetime!depot · stringdepotstringmessage · string!messagestring!ScanBatchScanBatchinputdevice_id · string!device_idstring!scans · ScanInput[]!scansScanInput[]!RescheduleInputRescheduleInputinputservice_date · date!service_datedate!otp · string!otpstring!ParcelStatusParcelStatusenum(no fields)ServiceLevelServiceLevelenum(no fields)
drag to pan · wheel to zoom · click a node · Esc clears

Auth is per audience

  • Merchants: a long-lived API key scoped to one merchant
  • Recipients: no account — a one-time code sent to the phone on the shipment
  • Handhelds: client certificates, rotated per device