Create, list and read the shipments of the authenticated carrier.
List shipments
Newest first, cursor paginated: pass next_cursor back as cursor to get the next page. Filters combine with AND; the values of one filter combine with OR. Allowed to carrier admins, dispatchers and shippers; a shipper user only sees the shipments of its own shipper account.
query Parameters
limitMaximum number of items in the page.
cursorThe next_cursor of the previous page, passed back as is. Omit it to get the first page.
statusComma-separated statuses to keep.
zoneComma-separated destination zones to keep.
serviceComma-separated services to keep.
shipper_accountComma-separated shipper account ids to keep. A shipper always gets the shipments of its own account.
created_fromCreated at or after this instant, or from the start of this Noumea day.
created_toCreated before this instant, or up to the end of this Noumea day.
qTracking number, recipient name or recipient phone.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List shipments › Responses
One page of shipments.
next_cursorPass it as cursor to get the next page. null on the last page.
Create a shipment
Allocates a tracking number, prices the shipment from the carrier rate card in whole XPF with the TGC, and records its first tracking event (created). Allowed to carrier admins, dispatchers and shippers.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Create a shipment › Request Body
service_kinddelivery_confirmationWhat the driver must collect to complete the delivery.
shipper_account_id^([0-9a-fA-F]{8}-[0-…The shipper account billed for this shipment.
shipper_referenceThe shipper's own reference, such as its order number.
declared_value_xpfDeclared value of the content, in whole XPF.
relay_point_id^([0-9a-fA-F]{8}-[0-…Required with service_kind pickup_point, refused otherwise: the pickup point the parcel goes to, from GET /v1/relay/points. The shipment is delivered to the address and position of the point, and its zone is the zone of the point commune; recipient.address_lines, location and zone are replaced.
Create a shipment › Responses
The created shipment.
idtracking_numberstatusservice_kinddelivery_confirmationshipper_account_iddeclared_value_xpfWhole XPF amounts from the carrier rate card. total_xpf includes the TGC.
created_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredshipper_referenceThe shipper's own reference; null when it gave none.
Get the figures of a day
Shipments created on a Noumea day, how many are delivered, out for delivery, failed or held by an open incident. Allowed to carrier admins, dispatchers and shippers; a shipper only counts the shipments of its own shipper account.
query Parameters
day^(?:(?:\d\d[2468][04…The Noumea day to describe, today when omitted.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get the figures of a day › Responses
The figures of the day.
day^(?:(?:\d\d[2468][04… · requiredShipments created on the day.
Shipments of the day now delivered or collected.
Shipments currently out for delivery, whatever their creation day.
Failed delivery attempts.
Incidents not resolved yet, whatever their day.
List the shipments to handle
Live shipments a dispatcher should act on, most pressing first: an open incident, a failed attempt to reschedule, a recipient placed only roughly or not at all, a parcel on no tour, a label never printed. Each one carries every reason that holds; the counts cover every shipment, listed or not. Allowed to carrier admins, dispatchers and shippers; a shipper only sees its own shipments.
query Parameters
limitHow many shipments to list; the counts cover them all.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List the shipments to handle › Responses
The shipments to handle and the counts per reason.
Shipments per reason; a shipment with two reasons counts in both.
totalShipments with at least one reason.
List the locked pickup point handovers
Parcels of the carrier waiting at a pickup point whose handover the counter locked after five wrong codes, longest locked first, with the recipient to call. Issuing a new code (issueNewPickupCode) unlocks one and takes it off the list. Allowed to carrier admins and dispatchers.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List the locked pickup point handovers › Responses
The locked handovers.
Get the notifications of the signed-in user
New incidents and recipient requests of the last 7 days, newest first, with how many came after the user last opened them. Reading them also marks the user active now, which the team list shows as their last activity. Allowed to carrier admins, dispatchers and shippers; a shipper only hears of its own shipments.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get the notifications of the signed-in user › Responses
The notifications and the unread count.
unread_countNotifications since the user last opened the list.
seen_at^(?:(?:\d\d[2468][04… · requiredWhen the user last opened the list; null if never.
The latest notifications of the last 7 days, newest first.
Mark the notifications as read
Marks every notification up to now as read for the signed-in user; sending it twice changes nothing more.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Mark the notifications as read › Responses
The notifications are read.
Quote a shipment
Prices a shipment from the carrier rate card exactly as createShipment would, without storing anything. Allowed to carrier admins, dispatchers and shippers.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Quote a shipment › Request Body
service_kinddelivery_confirmationWhat the driver must collect to complete the delivery.
shipper_account_id^([0-9a-fA-F]{8}-[0-…The shipper account billed for this shipment.
Quote a shipment › Responses
The price and the bracket it comes from.
zoneservice_kindweight_gramsTotal weight of the parcels.
The rate card bracket the weight falls in.
excluding_tax_xpftgc_xpftgc_rate_basis_pointstotal_xpfList the offered services
The services the carrier has turned on, with the proof each one asks of the recipient at the door. createShipment and quoteShipment refuse any other service with service_not_offered. Allowed to carrier admins, dispatchers and shippers.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List the offered services › Responses
The services a new shipment may use.
In the order of the catalog.
Search shipments and shipper accounts
Matches shipments on their tracking number, the digits of the recipient phone (spaces ignored, without the +687 prefix) or the recipient name, and shipper accounts on their name, contact phone or contact email. Allowed to carrier admins, dispatchers and shippers; a shipper only finds the shipments of its own shipper account.
query Parameters
qTracking number, phone digits, recipient name or shipper account name.
limitMaximum number of hits per group.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Search shipments and shipper accounts › Responses
The best hits per group.
Always empty for a shipper, who only sees their own account.
Suggest recipients already shipped to
The address book of the new-shipment form: the recipients of earlier shipments whose name or phone digits match, one per phone with the details of the last shipment to it. Allowed to carrier admins, dispatchers and shippers; a shipper only finds the recipients of its own shipper account.
query Parameters
qPart of the recipient name, or at least four digits of the recipient phone.
shipper_account_id^([0-9a-fA-F]{8}-[0-…Only the recipients of this shipper account. Ignored for a shipper, who only sees their own.
limitMaximum number of hits per group.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Suggest recipients already shipped to › Responses
The matching recipients, the most recent first.
Read the recipient out of a pasted address
Reads the recipient name, phone, email, address, commune and landmark out of a pasted address or order, for the new-shipment form to fill. Nothing is stored. A field the text does not tell, or tells wrongly (an invalid phone, an unknown commune), comes back null. Allowed to carrier admins, dispatchers and shippers.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Read the recipient out of a pasted address › Request Body
textThe address or order the person pasted, as is.
Read the recipient out of a pasted address › Responses
The recipient fields read from the text.
namephoneE.164 format, only when the text holds a valid phone.
emailaddress_linesThe street, the neighbourhood, then the commune.
communeOnly a commune of New Caledonia.
landmarkis_po_boxLocate an address before creating its shipment
Places an address with the geocoder the shipments use: its street within its commune, else the commune itself, so the new-shipment form can start its map pin there. Nothing is stored. The location is null when the geocoder cannot place the address now; send recipient.location on creation only for a point a person chose. Allowed to carrier admins, dispatchers and shippers.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Locate an address before creating its shipment › Request Body
address_linesThe street, the neighbourhood, then the commune, as a shipment stores them.
Locate an address before creating its shipment › Responses
Where the address lies.
Where the geocoder places the address: the house, the street, or the commune as a last resort. Null when it cannot place it now.
List the proofs of a shipment
The signatures, photos and ID checks drivers recorded with its tracking events, oldest first. Each file is behind a private link valid 5 minutes. Allowed to carrier admins and dispatchers, never to shippers.
path Parameters
idThe shipment id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
List the proofs of a shipment › Responses
The proofs and when their links expire.
Oldest first.
links_expire_at^(?:(?:\d\d[2468][04… · requiredAsk again for new links after this time.
Get a shipment
The shipment with its full tracking history, oldest event first. Allowed to carrier admins, dispatchers and shippers.
path Parameters
idThe shipment id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Get a shipment › Responses
The shipment and its tracking events.
idtracking_numberstatusservice_kinddelivery_confirmationshipper_account_iddeclared_value_xpfWhole XPF amounts from the carrier rate card. total_xpf includes the TGC.
created_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredTracking history, oldest first.
Every print of a label, newest first.
Delivery attempts, as the tracking history tells them.
The tours the shipment is or was on, newest first.
Who corrected the recipient and which fields, oldest first; never the old values.
recipient_editableWhether the recipient can still be corrected: not once out for delivery or done.
The handover at the pickup point the parcel was sent to; null for a parcel sent to none.
shipper_referenceThe shipper's own reference; null when it gave none.
Correct the recipient
Changes the recipient name, phone, email, address, landmark or PO box flag; only the fields sent change. Refused with a 409 once the shipment is out for delivery, delivered, collected, returned or cancelled. Records who changed which fields, never the old values. A new address drops the position and is geocoded again. Allowed to carrier admins, dispatchers and shippers; a shipper only corrects its own shipments.
path Parameters
idThe shipment id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Correct the recipient › Request Body
namephoneA phone number. Six digits without a prefix are read as a New Caledonia number (+687).
email^(?:[A-Za-z0-9_'+\-]…null removes the email.
address_linesA new address drops the position, and the address is geocoded again.
landmarknull removes the directions.
is_po_boxCorrect the recipient › Responses
The shipment, with the corrected recipient.
idtracking_numberstatusservice_kinddelivery_confirmationshipper_account_iddeclared_value_xpfWhole XPF amounts from the carrier rate card. total_xpf includes the TGC.
created_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredshipper_referenceThe shipper's own reference; null when it gave none.
Place a pickup or delivery point
Moves the position of the sender or the recipient to this point, as a dispatcher drops a pin on the map. The position becomes dispatcher and exact, and the geocoder never moves it again. Allowed to carrier admins and dispatchers.
path Parameters
idThe shipment id.
endsender (where the parcels are picked up) or recipient (where they go).
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Place a pickup or delivery point › Request Body
latlngPlace a pickup or delivery point › Responses
The shipment, with the new position.
idtracking_numberstatusservice_kinddelivery_confirmationshipper_account_iddeclared_value_xpfWhole XPF amounts from the carrier rate card. total_xpf includes the TGC.
created_at^(?:(?:\d\d[2468][04… · requiredupdated_at^(?:(?:\d\d[2468][04… · requiredshipper_referenceThe shipper's own reference; null when it gave none.
Issue a new pickup code
Gives the recipient of a parcel waiting at a pickup point a new six-digit code. The old code stops working, the recipient reads the new one on the page of the link they were texted, and the counter may type five codes again: this is how a handover locked after five wrong codes is unlocked. Refused with a 409 once the parcel left the point. Allowed to carrier admins and dispatchers.
path Parameters
idThe shipment id.
Headers
x-correlation-idYour request identifier. Generated when absent, and always echoed in the response header.
Issue a new pickup code › Responses
The new code is issued and the handover is unlocked.