← Docs / API Reference

API Reference

Static reference for the USPS workflows RevAddress supports today: addresses, rates, service standards, locations, tracking, label workflows, BYOK, and admin diagnostics. Base URL: https://api.revaddress.com

How to evaluate and expand

Use the free tier to validate and extract real addresses, resolve ZIP+4, compare rates, and test service-standard or location lookups. Add an API key when you are ready for tracking routes, label workflows, batch operations, BYOK, and pickup request access.

Free now

Address validation + extract
ZIP+4 + city/state lookup
Domestic + international rate shopping
Service standards, shipping options, and locations

Use the free tier to prove the integration with live USPS-backed responses before you commit to protected workflow access. No API key required.

API key required

Tracking route access
Labels + batch validation
Dashboard + BYOK
Pickup request access

Protected workflows unlock after signup and plan/account setup, with public claim depth still gated by route-specific proof.

Higher-volume access

Managed throughput
Enterprise onboarding
Licensing-dependent workflows

Use account setup and support when label volume, routing depth, or licensing needs exceed the default path.

Download OpenAPI YAML Get Free API Key

Address validation, ZIP+4 city/state lookup, and rate shopping work free — no API key needed. Add an API key when you move into tracking, labels, request-access pickup, batch validation, or BYOK.

Authentication

Free Tier

No API key required. IP-rate-limited: 30 req/10s. Address validation, rates, locations, service standards.

Protected

X-API-Key: rv_live_...
Labels, tracking, pickup, batch validation.

Rate Limits

Starter 120/min · Growth 300/min · Pro 600/min. Headers: X-RateLimit-Limit, -Remaining, -Reset.

Try it live

Hit the real USPS API right now. No API key, no signup — free tier, live data, ZIP+4 precision, and guided missing-unit recovery.

Smart mode by default

Street Address

Unit / Apt / Suite (optional)

City

State

ZIP

Response

← Enter an address and click Validate

Quick Start Examples

The four most common first requests. Hit the live API immediately.

POST /api/address/validate

Address validation — free tier, no key needed

FREE

curl -s "https://api.revaddress.com/api/address/validate" \
  -H "Content-Type: application/json" \
  -d '{"streetAddress":"228 Park Ave S PMB 101842","city":"New York","state":"NY","ZIPCode":"10003"}'

import requests

resp = requests.post(
    "https://api.revaddress.com/api/address/validate",
    json={
        "streetAddress": "228 Park Ave S PMB 101842",
        "city": "New York",
        "state": "NY",
        "ZIPCode": "10003"
    }
)
data = resp.json()
print(data["address"]["ZIPPlus4"])  # 1502

const resp = await fetch("https://api.revaddress.com/api/address/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    streetAddress: "228 Park Ave S PMB 101842",
    city: "New York",
    state: "NY",
    ZIPCode: "10003"
  })
});
const { address, additionalInfo } = await resp.json();
console.log(address.ZIPPlus4);       // "1502"
console.log(additionalInfo.DPVConfirmation); // "Y"

POST /api/rates

Rate shopping across all USPS mail classes

FREE

curl -s "https://api.revaddress.com/api/rates" \
  -H "Content-Type: application/json" \
  -d '{"originZIPCode":"10003","destinationZIPCode":"90210","weight":2.5,"length":12,"width":9,"height":2}'

import requests

resp = requests.post(
    "https://api.revaddress.com/api/rates",
    json={
        "originZIPCode": "10003",
        "destinationZIPCode": "90210",
        "weight": 2.5,
        "length": 12,
        "width": 9,
        "height": 2
    }
)
data = resp.json()
for opt in data["rates"]["rateOptions"]:
    print(f"{opt['mailClass']}: ${opt['totalBasePrice']:.2f} (zone {opt['zone']})")

const resp = await fetch("https://api.revaddress.com/api/rates", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    originZIPCode: "10003",
    destinationZIPCode: "90210",
    weight: 2.5,
    length: 12, width: 9, height: 2
  })
});
const { rates, serviceStandards } = await resp.json();
for (const opt of rates.rateOptions) {
  console.log(`${opt.mailClass}: $${opt.totalBasePrice}`);
}

POST /api/batch/validate

Up to 50 addresses in one request

Growth+

curl -s "https://api.revaddress.com/api/batch/validate" \
  -H "X-API-Key: rv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"addresses":[{"streetAddress":"228 Park Ave S","city":"New York","state":"NY","ZIPCode":"10003"},{"streetAddress":"1600 Pennsylvania Ave NW","city":"Washington","state":"DC","ZIPCode":"20500"}]}'

import requests

addresses = [
    {"streetAddress": "228 Park Ave S", "city": "New York", "state": "NY", "ZIPCode": "10003"},
    {"streetAddress": "1600 Pennsylvania Ave NW", "city": "Washington", "state": "DC", "ZIPCode": "20500"},
]

resp = requests.post(
    "https://api.revaddress.com/api/batch/validate",
    headers={"X-API-Key": "rv_live_your_key_here"},
    json={"addresses": addresses}
)
data = resp.json()
print(f"Validated: {data['successful']}/{data['total']}")
print(f"Cache hits: {data['usage']['cached_hits']}")

const resp = await fetch("https://api.revaddress.com/api/batch/validate", {
  method: "POST",
  headers: {
    "X-API-Key": "rv_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    addresses: [
      { streetAddress: "228 Park Ave S", city: "New York", state: "NY", ZIPCode: "10003" },
      { streetAddress: "1600 Pennsylvania Ave NW", city: "Washington", state: "DC" }
    ]
  })
});
const { total, successful, results, usage } = await resp.json();
console.log(`Validated ${successful}/${total}, ${usage.cached_hits} from cache`);

GET /api/tracking/:number

Tracking status with normalized categories when USPS provides events

Starter+

curl -s "https://api.revaddress.com/api/tracking/9400111899223456789012" \
  -H "X-API-Key: rv_live_your_key_here"

import requests

resp = requests.get(
    "https://api.revaddress.com/api/tracking/9400111899223456789012",
    headers={"X-API-Key": "rv_live_your_key_here"}
)
data = resp.json()
print(data["statusCategory"])  # "Pre-Shipment"
for event in data["trackingEvents"]:
    print(event["eventTimestamp"], event["eventType"])

const resp = await fetch(
  "https://api.revaddress.com/api/tracking/9400111899223456789012",
  { headers: { "X-API-Key": "rv_live_your_key_here" } }
);
const { statusCategory, trackingEvents } = await resp.json();
console.log(statusCategory); // "Pre-Shipment"

Addresses

Free Tier

US address validation and ZIP lookup. Free tier — no API key needed.

Validate and standardize a US address using USPS CASS-certified data. Returns ZIP+4, DPV confirmation, residential/business classification, and vacancy status. Results are cached in KV for 24 hours.

Parameters

Name	In	Required	Example
`streetAddress`	query	required	228 Park Ave S PMB 101842
`secondaryAddress`	query	optional	Suite 100
`city`	query	optional	New York
`state`	query	optional	NY
`ZIPCode`	query	optional	10003

Response

{
  "address": {
    "streetAddress": "228 PARK AVE S PMB 101842",
    "city": "NEW YORK",
    "state": "NY",
    "ZIPCode": "10003",
    "ZIPPlus4": "1502"
  },
  "additionalInfo": {
    "deliveryPoint": "42",
    "DPVConfirmation": "Y",
    "business": "Y",
    "vacant": "N"
  },
  "matches": [{ "code": "31", "text": "Single Response - exact match" }],
  "cached": false,
  "resolution": {
    "classification": "deliverable_exact",
    "nextAction": "done",
    "userMessage": "USPS confirmed this address."
  }
}

Returns city and state for a 5-digit ZIP code.

Parameters

Name	In	Required	Example
`ZIPCode`	query	required	10003

Response

{
  "zip5": "10003",
  "city": "NEW YORK",
  "state": "NY"
}

Rates

Free Tier

Domestic and international shipping rate quotes. Free tier.

Tracking

USPS tracking route access with normalized status data. API key required; broader public claim strength still waits on deeper scan-backed proof.

Returns tracking status plus any normalized USPS events currently available from USPS Tracking v3.2. Events are stored in D1 for analytics and operator review. expand=SUMMARY returns status only; DETAIL (default) includes richer event data when USPS provides it.

Parameters

Name	In	Required	Example
`trackingNumber`	path	required	9400111899223456789012
`expand` SUMMARY or DETAIL (default)	query	optional	DETAIL

Response

{
  "trackingNumber": "9400111899223456789012",
  "statusCategory": "Pre-Shipment",
  "statusSummary": "Shipping Label Created, USPS Awaiting Item",
  "expectedDeliveryDate": null,
  "trackingEvents": [
    {
      "eventType": "Shipping Label Created, USPS Awaiting Item",
      "eventCode": "GX",
      "eventCity": "NEW YORK",
      "eventState": "NY",
      "eventZIP": "10003",
      "eventTimestamp": "2026-03-17T03:26:34Z"
    }
  ]
}

Labels

Managed label workflows with download and void support for protected accounts.

Returns your most recent labels. Scoped to your merchant ID. Use ?limit=N to control page size (1–100, default 20).

Parameters

Name	In	Required	Example
`limit` 1–100, default 20	query	optional	20

Response

{
  "labels": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tracking_number": "9400111899223456789012",
      "mail_class": "PRIORITY_MAIL",
      "postage": 8.55,
      "status": "delivered",
      "commitment": "2 Days",
      "created_at": 1741234567890
    }
  ]
}

Returns the label PDF from R2 storage. Response is application/pdf with Content-Disposition: attachment. Labels are scoped to your merchant ID.

Parameters

Name	In	Required	Example
`labelId`	path	required	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

// Returns binary PDF — application/pdf

Voids a label and requests a USPS postage refund. Cannot void delivered or already-voided labels. USPS void request is fire-and-forget — the D1 record is always updated regardless of USPS response.

Parameters

Name	In	Required	Example
`labelId`	path	required	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "labelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "9400111899223456789012",
  "status": "voided",
  "refundAmount": 8.55,
  "voidedAt": "2026-03-10T12:00:00.000Z"
}

Workflows

Durable label creation workflows with explicit charge approval and status polling.

Returns current Cloudflare Workflow status and step progress for a label creation workflow.

Parameters

Name	In	Required	Example
`workflowId`	path	required	wf_abc123def456

Response

{
  "workflowId": "wf_abc123def456",
  "status": "running",
  "output": null
}

Sends the charge-approved event to an awaiting label workflow. Unblocks step 3 (waitForEvent) and allows label creation to proceed.

Parameters

Name	In	Required	Example
`workflowId`	path	required	wf_abc123def456

Request Body

{ "approved": true }

Response

{
  "workflowId": "wf_abc123def456",
  "event": "charge-approved",
  "payload": { "approved": true }
}

Pickup

Pickup availability and scheduling routes for protected accounts. Treat this as request-access / limited rollout until its own live proof lane closes.

Locations & Standards

Free Tier

USPS drop-off locations and delivery time standards. Free tier.

Find USPS Post Offices, collection boxes, and retail locations near a ZIP code. Results cached for 24 hours.

Parameters

Name	In	Required	Example
`destinationZIPCode`	query	required	10003
`mailClass` Default: PARCEL_SELECT	query	optional	PARCEL_SELECT
`originZIPCode`	query	optional	10001
`weight`	query	optional	2.5

Response

{
  "dropOffLocations": [
    {
      "locationName": "JAMES A. FARLEY BLDG",
      "streetAddress": "421 8TH AVE",
      "city": "NEW YORK",
      "state": "NY",
      "zipCode": "10001",
      "locationType": "POST_OFFICE"
    }
  ],
  "cached": false
}

Returns USPS delivery time estimates between two ZIP codes by mail class. Results cached for 24 hours (standards change quarterly).

Parameters

Name	In	Required	Example
`originZIPCode`	query	required	10003
`destinationZIPCode`	query	required	90210
`mailClass`	query	optional	PRIORITY_MAIL

Response

{
  "estimates": [
    { "mailClass": "PRIORITY_MAIL", "days": 2, "scheduleDeliveryDate": "2026-03-12" },
    { "mailClass": "USPS_GROUND_ADVANTAGE", "days": 5, "scheduleDeliveryDate": "2026-03-15" }
  ],
  "cached": false
}

Returns available USPS shipping products for a given origin/destination pair.

Parameters

Name	In	Required	Example
`originZIPCode`	query	required	10003
`destinationZIPCode`	query	required	90210
`mailClass`	query	optional	PRIORITY_MAIL
`weight`	query	optional	1
`priceType`	query	optional	RETAIL

Response

{
  "shipmentOptions": [
    {
      "mailClass": "PRIORITY_MAIL",
      "serviceId": "PM",
      "commitment": "2 Days",
      "priceType": "RETAIL"
    }
  ]
}

Admin Diagnostics

Admin-only diagnostics for protected operator use.

Clears cached OAuth and payment tokens for the selected USPS environment (`prod` by default, `tem` optional) and returns the post-clear token snapshot.

Parameters

Name	In	Required	Example
`env` prod (default) or tem	query	optional	prod

Response

{
  "environment": "production",
  "cleared": true,
  "oauth": { "valid": false, "ttl_seconds": 0 },
  "payment": {
    "valid": false,
    "ttl_seconds": 0,
    "failureClass": null
  }
}

BYOK

Bring your own USPS Developer Portal credentials. AES-GCM encrypted at rest.

Account

Self-service usage and key management. Scoped to your API key.

Returns API call breakdown by endpoint for the authenticated merchant. Scoped to your API key. Optionally filter by month (YYYY-MM).

Parameters

Name	In	Required	Example
`month` YYYY-MM format	query	optional	2026-03

Response

{
  "usage": [
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/address/validate", "call_count": 892 },
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/tracking/:number", "call_count": 231 },
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/rates", "call_count": 124 }
  ],
  "filters": { "merchant_id": "stripe_cus_abc123", "month": "2026-03" }
}

Revoke an API key that belongs to your merchant account. Only keys that belong to your own merchant ID can be revoked.

Parameters

Name	In	Required	Example
`keyHash`	path	required	a1b2c3d4e5f6...

Response

{ "key_hash": "a1b2c3d4e5f6...", "revoked": true }

Error Reference

All errors return a consistent JSON shape with machine-readable codes.

{
  "error": "usps_auth_failed",
  "message": "OAuth token expired or invalid",
  "status": 401,
  "code": "AUTH_EXPIRED",
  "retryable": true
}

Error Code	HTTP Status	Retryable	Action
api_key_required	401	—	Add X-API-Key header
invalid_api_key	401	—	Check that you're using the right live or free-evaluation key for this environment
api_key_revoked	401	—	Generate a new key
rate_limit_exceeded	429	Yes	Check retryAfter in response, back off
monthly_limit_exceeded	429	Next month	Upgrade plan at /pricing
free_tier_rate_limit	429	Yes	Slow down or get a free API key
tier_required	403	—	Upgrade plan (batch requires Growth+)
usps_validation_error	422	No	Fix input address data
usps_auth_failed	401	Yes	Token auto-refreshes — retry once
payment_token_unavailable	503	Yes	Retry after a few seconds
batch_too_large	400	No	Split into batches of ≤50

SDKs

Python v1.0.0

pip install usps-v3

PyPI GitHub Tutorial

Node.js v1.0.0

npm install usps-v3

npm GitHub Tutorial

PHP v1.0.0

composer require revaddress/usps-v3-php

Packagist GitHub Magento Guide