Quickstart: cURL

Test the API from your terminal in 2 minutes.

Quickstart: cURL

No SDK needed — test every endpoint from your terminal.

Step 1: Get your API key

Create an account and generate a sandbox key from the dashboard.

export PR_KEY="pr_test_YOUR_KEY_HERE"

Step 2: Validate an address

curl -X POST https://api.packageretriever.com/v1/addresses/validate \
  -H "Authorization: Bearer $PR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "street1": "417 Montgomery St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US"
  }'

Step 3: Get rates

curl -X POST https://api.packageretriever.com/v1/rates \
  -H "Authorization: Bearer $PR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address": {
      "name": "Warehouse",
      "street1": "417 Montgomery St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "to_address": {
      "name": "Customer",
      "street1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US"
    },
    "parcel": {
      "weight_oz": 16,
      "length": 9,
      "width": 6,
      "height": 2
    }
  }'

Response (sorted cheapest first):

{
  "rates": [
    {
      "id": "rate_usps_ga_abc123",
      "carrier": "USPS",
      "service": "Ground Advantage",
      "rate_cents": 542,
      "carrier_eta": "2026-05-20",
      "carbon_grams": 142
    }
  ]
}

Step 4: Buy a label

Use the id from the cheapest rate:

curl -X POST https://api.packageretriever.com/v1/labels \
  -H "Authorization: Bearer $PR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_id": "rate_usps_ga_abc123"
  }'

Response:

{
  "id": "lbl_8k2m4n6p",
  "tracking_number": "9999000000000000042",
  "label_url": "https://api.packageretriever.com/v1/sandbox/labels/sample-4x6.pdf",
  "carrier": "USPS",
  "service": "Ground Advantage",
  "rate_cents": 542,
  "sandbox": true
}

Step 5: Check wallet balance

curl https://api.packageretriever.com/v1/wallet \
  -H "Authorization: Bearer $PR_KEY"

That’s it

Three calls: validate → rate → label. Your integration is the same pattern at any scale.