← 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

Standardization, geocoding, and address extract run free with no signup. Connect your own USPS Developer Portal license — any key, Free included — and DPV, rates, service standards, city/state, and tracking run on your license through our infrastructure. Add an API key for batch operations, checkout validation, webhooks, and pickup scheduling.

Free tier

Address standardization + extract (US Census)
Street-level geocode + ACS demographics demo
Sandbox DPV / CMRA demo
DPV, rates, service standards, and city/state on your USPS license (BYOK)

Standardize and geocode live with no key. Connect your own USPS Developer Portal app — Free keys can — and the USPS suite runs on our infrastructure.

API key required

Package tracking
Batch validation + checkout widget
Dashboard + webhooks
Pickup scheduling

Paid endpoints unlock after signup. Flat monthly pricing.

Higher volume

Increased throughput
Enterprise onboarding
Custom integrations

Download OpenAPI YAML Get Free API Key

Census address standardization, geocoding, address extract, and the intelligence demo work free — no API key, no USPS license. DPV, ZIP+4 city/state lookup, rates, service standards, and locations run on your USPS license (BYOK). 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. Census standardization, geocoding, address extract. Rates, locations, and service standards on your USPS license (BYOK).

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

Try the validate endpoint right now — no API key, no signup. Today the anonymous lane returns Census standardization with coordinates; full USPS DPV and ZIP+4 run on your own USPS license (BYOK, free key included) or when the platform lane is live. Guided missing-unit recovery works on both.

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. Census standardization + geocode free — no API key, no license. DPV and city/state run on your USPS license (BYOK).

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."
  }
}

Name	In	Required	Example
`ZIPCode`	query	required	10003

Rates

Free Tier

Domestic and international shipping rate quotes. Free tier — runs on your USPS license (BYOK).

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 — runs on your USPS license (BYOK).

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 and every USPS call from your keys — DPV, rates, service standards, shipping options, city/state, tracking, pickups, international prices — runs on your license through our infrastructure. Any API key can connect, Free included (guided form: /dashboard/#byok). AES-GCM encrypted at rest; per-merchant token manager handles OAuth refresh, retries, caching.

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

Pythonv1.0.0

pip install usps-v3

PyPI GitHub Tutorial

Node.jsv1.0.0

npm install usps-v3

npm GitHub Tutorial

PHPv1.0.0

composer require revaddress/usps-v3-php

Packagist GitHub Magento Guide