shipping.nc API

Pickups

Server

Ask the carrier to pick up parcels at a shipper, put the request on a tour and read its outcome.


List pickup requests

GET
https://api.shipping.nc
/v1/dispatch/pickup-requests

Newest first, cursor paginated. A shipper only sees its own. Allowed to shippers for their own account, carrier admins and dispatchers.

List pickup requests › query Parameters

limit
​integer · min: 1 · max: 100

Maximum number of items in the page.

Example: 25
Default: 25
cursor
​string

The next_cursor of the previous page, passed back as is. Omit it to get the first page.

Example: WyIyMDI2LTExLTExVDA4OjQyOjEwLjAwMFoiLCIwYjZmOWMxZS01ZDJhLTRjM2UtOWYxYS03ZTJkOGM0YjZhMTAiXQ
day
​string · date · pattern: ^(?:(?:\d\d[2468][04…

A Noumea day.

Example: 2026-11-12
status
​string

Comma-separated statuses to keep.

Example: requested,scheduled
shipper_account_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Keep the requests of this shipper account.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67
q
​string · minLength: 1 · maxLength: 100

Held anywhere in the account name, the commune or the tour code, ignoring case.

Example: Dumbéa

List pickup requests › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

List pickup requests › Responses

One page of pickup requests.

​object[] · required
next_cursor
​string | null · required

Pass it as cursor to get the next page. null on the last page.


Request a pickup

POST
https://api.shipping.nc
/v1/dispatch/pickup-requests

Asks the carrier to collect parcels at the pickup address of the account, or at address. The slot must come after the pickup cutoff of the zone: pickup_too_early names the earliest one. Allowed to shippers for their own account, carrier admins and dispatchers.

Request a pickup › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Request a pickup › Request Body

day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
slot
​string · enum · required

When the driver comes by, Noumea time: 08-10 is from 8 to 10 am.

Enum values:
08-10
10-12
14-16
parcel_count
​integer · min: 1 · max: 999 · required

How many parcels the driver takes.

Example: 3
shipper_account_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

The account to collect from. Required for carrier staff, ignored for a shipper.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67
shipment_ids
​string[] · maxItems: 100

The shipments to collect. Leave it empty to collect every shipment of the account still at the sender when dispatch schedules the pickup.

Example: ["0b6f9c1e-5d2a-4c3e-9f1a-7e2d8c4b6a10"]
Default: []
notes
​string · maxLength: 500
​object

Where to collect, when it is not the pickup address of the shipper account.

Request a pickup › Responses

The pickup request.

id
​string · required
​object · required
day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
slot
​string · enum · required

When the driver comes by, Noumea time: 08-10 is from 8 to 10 am.

Enum values:
08-10
10-12
14-16
status
​string · enum · required

requested: waiting for dispatch. scheduled: on a tour as a pickup stop. picked_up: the driver took the parcels. missed: the driver came by and took none. cancelled: withdrawn before it was scheduled.

Enum values:
requested
scheduled
picked_up
missed
cancelled
address_lines
​string[] · required
commune
​string · required
zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
parcel_count
​integer · min: -9007199254740991 · max: 9007199254740991 · required
shipment_ids
​string[] · required

The shipments the pickup collects; filled in when dispatch schedules it.

notes
​string | null · required
​object | null · required

The tour the pickup is a stop of, once scheduled.

missed_reason
​string | null · enum · required

What the driver reported, when the pickup is missed.

Enum values:
damaged
lost
address_not_found
recipient_absent
refused
other
scheduled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
settled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the parcels were picked up, or the pickup was missed or cancelled.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Get the earliest pickup slot

GET
https://api.shipping.nc
/v1/dispatch/pickup-requests/availability

The earliest day and slot a driver can come to the pickup address of the account, after the pickup cutoff of its zone. Allowed to shippers for their own account, carrier admins and dispatchers.

Get the earliest pickup slot › query Parameters

shipper_account_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

The account to collect from. Required for carrier staff, ignored for a shipper.

Example: 5c1d7e2a-8b3f-4a6e-b2d9-1f0e3c4a5b67

Get the earliest pickup slot › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get the earliest pickup slot › Responses

The earliest slot and the cutoff it comes from.

zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
earliest_day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
earliest_slot
​string · enum · required

When the driver comes by, Noumea time: 08-10 is from 8 to 10 am.

Enum values:
08-10
10-12
14-16
cutoff
​string | null · required

Noumea time after which the day is too late; null when the zone has none.

Example: 11:00
cutoff_previous_day
​boolean · required

The cutoff applies the day before the pickup instead of the same day.


Get a pickup request

GET
https://api.shipping.nc
/v1/dispatch/pickup-requests/{id}

With its tour once scheduled, and its outcome once the driver came by. Allowed to shippers for their own account, carrier admins and dispatchers.

Get a pickup request › path Parameters

id
​string · uuid · required

The pickup request id.

Get a pickup request › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Get a pickup request › Responses

The pickup request.

id
​string · required
​object · required
day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
slot
​string · enum · required

When the driver comes by, Noumea time: 08-10 is from 8 to 10 am.

Enum values:
08-10
10-12
14-16
status
​string · enum · required

requested: waiting for dispatch. scheduled: on a tour as a pickup stop. picked_up: the driver took the parcels. missed: the driver came by and took none. cancelled: withdrawn before it was scheduled.

Enum values:
requested
scheduled
picked_up
missed
cancelled
address_lines
​string[] · required
commune
​string · required
zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
parcel_count
​integer · min: -9007199254740991 · max: 9007199254740991 · required
shipment_ids
​string[] · required

The shipments the pickup collects; filled in when dispatch schedules it.

notes
​string | null · required
​object | null · required

The tour the pickup is a stop of, once scheduled.

missed_reason
​string | null · enum · required

What the driver reported, when the pickup is missed.

Enum values:
damaged
lost
address_not_found
recipient_absent
refused
other
scheduled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
settled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the parcels were picked up, or the pickup was missed or cancelled.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Cancel a pickup request

POST
https://api.shipping.nc
/v1/dispatch/pickup-requests/{id}/cancel

Withdraws a request that is not on a tour yet; cancelling it again changes nothing. Once scheduled, ask dispatch instead. Allowed to shippers for their own account, carrier admins and dispatchers.

Cancel a pickup request › path Parameters

id
​string · uuid · required

The pickup request id.

Cancel a pickup request › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Cancel a pickup request › Responses

The cancelled pickup request.

id
​string · required
​object · required
day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
slot
​string · enum · required

When the driver comes by, Noumea time: 08-10 is from 8 to 10 am.

Enum values:
08-10
10-12
14-16
status
​string · enum · required

requested: waiting for dispatch. scheduled: on a tour as a pickup stop. picked_up: the driver took the parcels. missed: the driver came by and took none. cancelled: withdrawn before it was scheduled.

Enum values:
requested
scheduled
picked_up
missed
cancelled
address_lines
​string[] · required
commune
​string · required
zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
parcel_count
​integer · min: -9007199254740991 · max: 9007199254740991 · required
shipment_ids
​string[] · required

The shipments the pickup collects; filled in when dispatch schedules it.

notes
​string | null · required
​object | null · required

The tour the pickup is a stop of, once scheduled.

missed_reason
​string | null · enum · required

What the driver reported, when the pickup is missed.

Enum values:
damaged
lost
address_not_found
recipient_absent
refused
other
scheduled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
settled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the parcels were picked up, or the pickup was missed or cancelled.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Schedule a pickup on a tour

POST
https://api.shipping.nc
/v1/dispatch/pickup-requests/{id}/schedule

Adds a pickup stop to a tour of the pickup day for each shipment the request collects: the ones it names, or else every shipment of the account still at the sender. The request becomes picked_up or missed from the events the driver records on those stops. Scheduling it again on the same tour changes nothing. Allowed to carrier admins and dispatchers.

Schedule a pickup on a tour › path Parameters

id
​string · uuid · required

The pickup request id.

Schedule a pickup on a tour › Headers

x-correlation-id
​string · maxLength: 128

Your request identifier. Generated when absent, and always echoed in the response header.

Schedule a pickup on a tour › Request Body

tour_id
​string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

A tour of the pickup day that is not completed.

Example: 4b7e9d23-1a6c-4f58-9e02-8c3d5a7f1b94

Schedule a pickup on a tour › Responses

The scheduled pickup request.

id
​string · required
​object · required
day
​string · date · pattern: ^(?:(?:\d\d[2468][04… · required

A Noumea day.

Example: 2026-11-12
slot
​string · enum · required

When the driver comes by, Noumea time: 08-10 is from 8 to 10 am.

Enum values:
08-10
10-12
14-16
status
​string · enum · required

requested: waiting for dispatch. scheduled: on a tour as a pickup stop. picked_up: the driver took the parcels. missed: the driver came by and took none. cancelled: withdrawn before it was scheduled.

Enum values:
requested
scheduled
picked_up
missed
cancelled
address_lines
​string[] · required
commune
​string · required
zone
​string · enum · required
Enum values:
grand_noumea
brousse_west
brousse_east
loyalty_islands
isle_of_pines
parcel_count
​integer · min: -9007199254740991 · max: 9007199254740991 · required
shipment_ids
​string[] · required

The shipments the pickup collects; filled in when dispatch schedules it.

notes
​string | null · required
​object | null · required

The tour the pickup is a stop of, once scheduled.

missed_reason
​string | null · enum · required

What the driver reported, when the pickup is missed.

Enum values:
damaged
lost
address_not_found
recipient_absent
refused
other
scheduled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required
settled_at
​string | null · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

When the parcels were picked up, or the pickup was missed or cancelled.

created_at
​string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required