Schedule a carrier pickup

POST/v1/pickupsSchedule a carrier pickup

Parameters

Idempotency-Keystring · uuidheaderrequired

Request body

required

application/json

objectCreatePickupRequest

addressobjectrequired

Show child attributes

citystringrequired

companynull | string

countrystringrequired

pattern ^[A-Z]{2}$

line1stringrequired

line2null | string

namestringrequired

minLength 1

phonenull | string

postal_codestringrequired

regionnull | string

notesnull | string

maxLength 500

shipment_idsarray of stringrequired

maxItems 100 · minItems 1

Show child attributes

maxItems 100 · minItems 1

windowobjectrequired

Show child attributes

ends_atstring · date-timerequired

starts_atstring · date-timerequired

Example request

{
  "address": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "notes": "string",
  "shipment_ids": [
    "string"
  ],
  "window": {
    "ends_at": "2026-09-06T12:00:00Z",
    "starts_at": "2026-09-06T09:00:00Z"
  }
}

Responses

objectPickup

addressobjectrequiredAddress ↑

created_atstring · date-timerequired

idstringrequired

objectvaluerequired

const "pickup"

shipment_idsarray of stringrequired

Show child attributes

statusstringrequired

one of "scheduled", "completed", "canceled", "missed"

windowobjectrequiredPickupWindow ↑

Example response

{
  "address": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "created_at": "2026-06-09T00:00:00Z",
  "id": "pku_00000000000000000001",
  "object": "pickup",
  "shipment_ids": [
    "string"
  ],
  "status": "canceled",
  "window": {
    "ends_at": "2026-09-06T12:00:00Z",
    "starts_at": "2026-09-06T09:00:00Z"
  }
}

objectProblem

detailstring

errorsarray of object

Show child attributes

Show array items

messagestringrequired

pathstringrequired

request_idstringrequired

statusintegerrequired

maximum 599 · minimum 400

titlestringrequired

typestring · urirequired

Example response

{
  "errors": [
    {
      "message": "must be a synthetic postal code",
      "path": "recipient.postal_code"
    }
  ],
  "request_id": "req_00000000000000000006",
  "status": 422,
  "title": "Synthetic request validation failed",
  "type": "https://parcel-events.example/problems/validation"
}

Examples

Idempotency-Keyrequiredheader parameter

curl -X POST 'https://api.parcel-events.example/v1/pickups' \
  -H 'Content-Type: application/json' \
  -d '{"address":{"city":"Exampleton","company":"Northstar Supplies","country":"ZZ","line1":"14 Fictional Quay","line2":"Unit 7","name":"Rowan Example","phone":"+00000000000","postal_code":"EX4 2PL","region":"Test Province"},"notes":"string","shipment_ids":["string"],"window":{"ends_at":"2026-09-06T12:00:00Z","starts_at":"2026-09-06T09:00:00Z"}}'

const response = await fetch('https://api.parcel-events.example/v1/pickups', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"address":{"city":"Exampleton","company":"Northstar Supplies","country":"ZZ","line1":"14 Fictional Quay","line2":"Unit 7","name":"Rowan Example","phone":"+00000000000","postal_code":"EX4 2PL","region":"Test Province"},"notes":"string","shipment_ids":["string"],"window":{"ends_at":"2026-09-06T12:00:00Z","starts_at":"2026-09-06T09:00:00Z"}}),
});
const data = await response.json();

const response = await fetch('https://api.parcel-events.example/v1/pickups', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"address\":{\"city\":\"Exampleton\",\"company\":\"Northstar Supplies\",\"country\":\"ZZ\",\"line1\":\"14 Fictional Quay\",\"line2\":\"Unit 7\",\"name\":\"Rowan Example\",\"phone\":\"+00000000000\",\"postal_code\":\"EX4 2PL\",\"region\":\"Test Province\"},\"notes\":\"string\",\"shipment_ids\":[\"string\"],\"window\":{\"ends_at\":\"2026-09-06T12:00:00Z\",\"starts_at\":\"2026-09-06T09:00:00Z\"}}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.parcel-events.example/v1/pickups",
    headers={"Content-Type": "application/json"},
    data='{"address":{"city":"Exampleton","company":"Northstar Supplies","country":"ZZ","line1":"14 Fictional Quay","line2":"Unit 7","name":"Rowan Example","phone":"+00000000000","postal_code":"EX4 2PL","region":"Test Province"},"notes":"string","shipment_ids":["string"],"window":{"ends_at":"2026-09-06T12:00:00Z","starts_at":"2026-09-06T09:00:00Z"}}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"address":{"city":"Exampleton","company":"Northstar Supplies","country":"ZZ","line1":"14 Fictional Quay","line2":"Unit 7","name":"Rowan Example","phone":"+00000000000","postal_code":"EX4 2PL","region":"Test Province"},"notes":"string","shipment_ids":["string"],"window":{"ends_at":"2026-09-06T12:00:00Z","starts_at":"2026-09-06T09:00:00Z"}}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.parcel-events.example/v1/pickups", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.parcel-events.example/v1/pickups");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"address\":{\"city\":\"Exampleton\",\"company\":\"Northstar Supplies\",\"country\":\"ZZ\",\"line1\":\"14 Fictional Quay\",\"line2\":\"Unit 7\",\"name\":\"Rowan Example\",\"phone\":\"+00000000000\",\"postal_code\":\"EX4 2PL\",\"region\":\"Test Province\"},\"notes\":\"string\",\"shipment_ids\":[\"string\"],\"window\":{\"ends_at\":\"2026-09-06T12:00:00Z\",\"starts_at\":\"2026-09-06T09:00:00Z\"}}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.parcel-events.example/v1/pickups"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"address\":{\"city\":\"Exampleton\",\"company\":\"Northstar Supplies\",\"country\":\"ZZ\",\"line1\":\"14 Fictional Quay\",\"line2\":\"Unit 7\",\"name\":\"Rowan Example\",\"phone\":\"+00000000000\",\"postal_code\":\"EX4 2PL\",\"region\":\"Test Province\"},\"notes\":\"string\",\"shipment_ids\":[\"string\"],\"window\":{\"ends_at\":\"2026-09-06T12:00:00Z\",\"starts_at\":\"2026-09-06T09:00:00Z\"}}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.parcel-events.example/v1/pickups")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"address\":{\"city\":\"Exampleton\",\"company\":\"Northstar Supplies\",\"country\":\"ZZ\",\"line1\":\"14 Fictional Quay\",\"line2\":\"Unit 7\",\"name\":\"Rowan Example\",\"phone\":\"+00000000000\",\"postal_code\":\"EX4 2PL\",\"region\":\"Test Province\"},\"notes\":\"string\",\"shipment_ids\":[\"string\"],\"window\":{\"ends_at\":\"2026-09-06T12:00:00Z\",\"starts_at\":\"2026-09-06T09:00:00Z\"}}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.parcel-events.example/v1/pickups");
request.Content = new StringContent("{\"address\":{\"city\":\"Exampleton\",\"company\":\"Northstar Supplies\",\"country\":\"ZZ\",\"line1\":\"14 Fictional Quay\",\"line2\":\"Unit 7\",\"name\":\"Rowan Example\",\"phone\":\"+00000000000\",\"postal_code\":\"EX4 2PL\",\"region\":\"Test Province\"},\"notes\":\"string\",\"shipment_ids\":[\"string\"],\"window\":{\"ends_at\":\"2026-09-06T12:00:00Z\",\"starts_at\":\"2026-09-06T09:00:00Z\"}}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "address": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "created_at": "2026-06-09T00:00:00Z",
  "id": "pku_00000000000000000001",
  "object": "pickup",
  "shipment_ids": [
    "string"
  ],
  "status": "canceled",
  "window": {
    "ends_at": "2026-09-06T12:00:00Z",
    "starts_at": "2026-09-06T09:00:00Z"
  }
}

{
  "errors": [
    {
      "message": "must be a synthetic postal code",
      "path": "recipient.postal_code"
    }
  ],
  "request_id": "req_00000000000000000006",
  "status": 422,
  "title": "Synthetic request validation failed",
  "type": "https://parcel-events.example/problems/validation"
}

Search documentation

Parameters

Request body

Responses

Documentation menu