← 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

Census standardization, geocoding and address extraction are free within limits. Paid provider operations need a funded account, and USPS verification takes 10 purchased credits ($0.01) per address on top of a paid plan. BYOK does not bypass access controls.

Free tier: Census address standardization and extraction
Street-level geocoding and the ACS demographics demo
Free operations use Census and local reference data only
No paid USPS or AI provider calls

USPS verification needs a paid plan and purchased credits. A Census answer is not a USPS DPV confirmation.
Paid plan and funding: Package tracking
Batch validation and the checkout widget
Dashboard and webhooks
Pickup scheduling

Paid workflows need a current payment. USPS verification also takes 10 purchased credits ($0.01) per address, and credits never top up automatically.
Higher volume: Increased throughput
Enterprise onboarding
Custom integrations

Talk to us when volume or licensing needs go past the published plans.

Download OpenAPI YAML Create a key

Census address standardization, geocoding, address extract, and the intelligence demo work free, with no API key or USPS license. USPS operations require paid access and funding; platform DPV additionally uses 10 purchased credits ($0.01) per address. An API key alone does not grant paid access. Labels remain disabled.

Authentication

Free tier

Free Census standardization, geocoding and local address extraction are IP-rate-limited. USPS shipping tools require a scoped API key and an active paid software plan; BYOK does not bypass paid access.

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 here, with no API key or signup. Keyless calls return Census standardization with coordinates; USPS DPV requires a paid plan and purchased funding. A keyless Census response must not be interpreted as a USPS delivery-point verdict.

Smart mode by default

Street address

Apartment, suite or unit (optional)

City

State

ZIP Code

Response

← Enter an address and click Validate

Quickstart 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

Starter+

curl -s "https://api.revaddress.com/api/rates" \
  -H "X-API-Key: rv_live_YOUR_KEY" \
  -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",
    headers={"X-API-Key": "rv_live_YOUR_KEY"},
    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", "X-API-Key": "rv_live_YOUR_KEY" },
  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, with no API key or license. USPS operations require current paid access and funding; platform DPV uses 10 purchased credits ($0.01) per address.

Validate and standardize a US address using USPS CASS-certified data. Returns ZIP+4, DPV confirmation, Censusial/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."
  }
}

Same validation but accepts the address as a JSON request body. Useful in workflows where building query strings is inconvenient.

Request body

{
  "streetAddress": "1600 Pennsylvania Ave NW",
  "city": "Washington",
  "state": "DC",
  "ZIPCode": "20500"
}

Response

{
  "address": {
    "streetAddress": "1600 PENNSYLVANIA AVE NW",
    "city": "WASHINGTON",
    "state": "DC",
    "ZIPCode": "20500",
    "ZIPPlus4": "0005"
  },
  "additionalInfo": {
    "DPVConfirmation": "Y",
    "vacant": "N",
    "deliveryPoint": "00",
    "business": "Y"
  },
  "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"
}

Validate up to 50 addresses in a single request. Individual failures never kill the batch (Promise.allSettled). Each address sent for USPS verification needs purchased funding in addition to the software allowance. Requires Growth tier or above.

Request body

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

Response

{
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "status": "success",
      "address": { "streetAddress": "228 PARK AVE S PMB 101842", "city": "NEW YORK", "state": "NY", "ZIPCode": "10003", "ZIPPlus4": "1502" },
      "additionalInfo": { "DPVConfirmation": "Y", "business": "Y", "vacant": "N" },
      "cached": true
    },
    {
      "index": 1,
      "status": "success",
      "address": { "streetAddress": "1600 PENNSYLVANIA AVE NW", "city": "WASHINGTON", "state": "DC", "ZIPCode": "20500", "ZIPPlus4": "0005" },
      "additionalInfo": { "DPVConfirmation": "Y", "business": "Y", "vacant": "N" },
      "cached": false
    }
  ],
  "usage": { "cached_hits": 1, "fresh_lookups": 1 }
}

Rates

Domestic and international shipping rate quotes. Paid, funded account required; BYOK uses your USPS license where enabled.

Returns USPS rate quotes for all domestic mail classes. Enriched with delivery time estimates from the Service Standards API. Dimensions default to 6×4×1 if not provided.

Request body

{
  "originZIPCode": "10003",
  "destinationZIPCode": "90210",
  "weight": 2.5,
  "length": 12,
  "width": 9,
  "height": 2
}

Response

{
  "rates": {
    "rateOptions": [
      { "mailClass": "PRIORITY_MAIL", "totalBasePrice": 8.55, "zone": "5" },
      { "mailClass": "USPS_GROUND_ADVANTAGE", "totalBasePrice": 5.25, "zone": "5" },
      { "mailClass": "PRIORITY_MAIL_EXPRESS", "totalBasePrice": 26.60, "zone": "5" }
    ]
  },
  "serviceStandards": {
    "estimates": [
      { "mailClass": "PRIORITY_MAIL", "days": 2 },
      { "mailClass": "USPS_GROUND_ADVANTAGE", "days": 5 }
    ]
  },
  "input": { "origin": "10003", "destination": "90210", "weight": 2.5 }
}

Returns USPS rate quotes for international shipments. Supply a 2-letter ISO 3166-1 alpha-2 destination country code.

Request body

{
  "destinationCountryCode": "CA",
  "originZIPCode": "10003",
  "weight": 2.5
}

Response

{
  "rates": {
    "rateOptions": [
      { "mailClass": "PRIORITY_MAIL_INTERNATIONAL", "totalBasePrice": 49.50 },
      { "mailClass": "PRIORITY_MAIL_EXPRESS_INTERNATIONAL", "totalBasePrice": 89.75 },
      { "mailClass": "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE", "totalBasePrice": 15.25 }
    ]
  },
  "input": { "origin": "10003", "destination": "CA", "weight": 2.5 }
}

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.

Creates a USPS shipping label. In workflow mode (default), returns a workflowId; send POST /api/workflows/{id}/approve to authorize the charge. In direct mode, creates the label synchronously and returns the PDF URL. Supports idempotencyKey to prevent duplicate charges on retries.

Request body

{
  "fromAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "streetAddress": "228 Park Ave S PMB 101842",
    "city": "New York",
    "state": "NY",
    "ZIPCode": "10003"
  },
  "toAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "streetAddress": "1600 Pennsylvania Ave NW",
    "city": "Washington",
    "state": "DC",
    "ZIPCode": "20500"
  },
  "mailClass": "PRIORITY_MAIL",
  "weight": 2.5,
  "length": 12,
  "width": 9,
  "height": 2,
  "idempotencyKey": "order-12345-label-1"
}

Response

// Workflow mode — 202 Accepted
{
  "workflowId": "wf_abc123def456",
  "status": "pending_approval",
  "message": "Workflow created. Send POST /api/workflows/{id}/approve to authorize charge."
}

// Direct mode — 201 Created
{
  "labelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "9400111899223456789012",
  "postage": 8.55,
  "zone": "5",
  "commitment": { "name": "2 Days", "scheduleDeliveryDate": "2026-03-12" },
  "labelUrl": "/api/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download",
  "environment": "production"
}

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. Request access; rolling out account by account.

Check whether the pickup surface is enabled for a given address and account setup. Requires streetAddress, city, state, and ZIPCode in the request body.

Request body

{
  "streetAddress": "228 Park Ave S",
  "city": "New York",
  "state": "NY",
  "ZIPCode": "10003"
}

Response

{
  "pickupAvailability": {
    "available": true,
    "nextPickupDate": "2026-03-11"
  }
}

Request a USPS pickup where pickup access is enabled for your account and a prepared, prepaid package is ready for carrier handoff. See USPS Carrier Pickup v3 documentation for the full request body schema.

Request body

{
  "streetAddress": "228 Park Ave S",
  "city": "New York",
  "state": "NY",
  "ZIPCode": "10003",
  "pickupDate": "2026-03-11",
  "packageCount": 2,
  "estimatedWeight": 5
}

Response

{
  "confirmationNumber": "WTC123456789",
  "pickupDate": "2026-03-11"
}

Cancel an existing carrier pickup where pickup access is enabled.

Request body

{ "confirmationNumber": "WTC123456789" }

Response

{
  "cancelled": true,
  "confirmationNumber": "WTC123456789"
}

Locations & Standards

USPS drop-off locations and delivery time standards. Paid, funded account required; BYOK uses your USPS license where enabled.

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.

Returns current OAuth and payment token validity plus the latest payment-auth attempt metadata, including upstream status, message, failure class, and blocked reason.

Response

{
  "environment": "production",
  "oauth": { "valid": true, "ttl_seconds": 25120 },
  "payment": {
    "valid": true,
    "ttl_seconds": 23980,
    "lastAttemptAt": "2026-03-15T15:24:11.112Z",
    "lastUpstreamStatus": 200,
    "lastUpstreamMessage": "Payment authorization token obtained",
    "failureClass": null,
    "blockedReason": null
  }
}

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

Refreshes OAuth and payment tokens and returns structured success/failure metadata instead of a single coarse result.

Response

{
  "oauth": { "success": true, "ttl_seconds": 25200 },
  "payment": {
    "success": true,
    "ttl_seconds": 24000,
    "lastUpstreamStatus": 200,
    "lastUpstreamMessage": "Payment authorization token obtained",
    "failureClass": null,
    "blockedReason": null
  }
}

Attempts payment authorization without buying postage. Internal operator diagnostic only.

Response

{
  "success": true,
  "message": "Payment authorization token obtained",
  "failureClass": null,
  "blockedReason": null
}

BYOK

Supported paid accounts can connect their own USPS app credentials for enabled integrations. Charges on that USPS license remain the account holder's responsibility. Connecting credentials does not bypass RevAddress paid access, request limits or funding controls. Guided form: /dashboard/#byok. Credentials are AES-GCM encrypted at rest; the account token manager handles OAuth refresh, retries and caching.

Supported paid accounts can store USPS app credentials for enabled integrations. Credentials are encrypted with AES-GCM using an HKDF-derived account key, with an isolated token manager. OAuth verification returns verified (201) or pending_verification (200). Verified credentials do not bypass paid entitlement or provider funding checks. Label purchase and payment authorization remain disabled.

Request body

{
  "client_id": "your-usps-consumer-key",
  "client_secret": "your-usps-consumer-secret",
  "crid": "12345678",
  "master_mid": "900000001",
  "label_mid": "900000002",
  "epa_account": "1000000001"
}

Response

// Verified (201)
{
  "merchant_id": "stripe_cus_abc123",
  "status": "verified",
  "has_payment_fields": true,
  "verification": { "success": true, "message": "OAuth token obtained successfully" },
  "message": "Credentials verified — your USPS tokens are now managed separately."
}

// Stored but not verified (200)
{
  "merchant_id": "stripe_cus_abc123",
  "status": "pending_verification",
  "verification": { "success": false, "error": "token_exchange_failed" },
  "message": "Credentials stored but verification failed. Check your USPS client_id/secret."
}

Returns BYOK credential status and live token health for the authenticated merchant.

Response

{
  "merchant_id": "stripe_cus_abc123",
  "byok_enabled": true,
  "status": "verified",
  "has_payment_fields": true,
  "last_verified_at": "2026-03-09 17:00:00",
  "tokens": {
    "oauth": { "valid": true, "ttl_seconds": 25200 },
    "payment": { "valid": true, "ttl_seconds": 24000 }
  }
}

Attempt OAuth token exchange with stored credentials. Updates status and last_verified_at.

Response

{
  "merchant_id": "stripe_cus_abc123",
  "status": "verified",
  "last_verified_at": "2026-03-10 08:00:00"
}

Deletes stored BYOK credentials. Subsequent platform USPS requests still require current paid access and applicable purchased funding; Census standardization remains the free path.

Response

{ "deleted": true, "merchant_id": "stripe_cus_abc123" }

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

Returns all API keys for your merchant account. Key hashes are masked (first 8 + last 4 chars). Use key_hash_full for revocation.

Response

{
  "keys": [
    {
      "key_hash": "a1b2c3d4...ef12",
      "key_hash_full": "a1b2c3d4e5f6...",
      "label": "production",
      "tier": "starter",
      "rate_limit_per_min": 120,
      "created_at": 1741234567890,
      "last_used_at": 1741234599000,
      "revoked_at": null
    }
  ],
  "merchant_id": "stripe_cus_abc123"
}

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 }

Creates a Stripe billing portal session when self-serve billing is configured for the account. Returns a redirect URL for plan, payment-method, and invoice management, or falls back to direct support workflows if self-serve billing is unavailable.

Response

{ "portal_url": "https://billing.stripe.com/session/..." }

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 refreshes automatically; retry once
payment_token_unavailable	503	Yes	Retry after a few seconds
batch_too_large	400	No	Split into batches of ≤50
credits_exhausted	402	After top-up	Buy credits: the response carries required, balance and a top-up link

Prepaid credits

Software credits and provider funding are separate. One purchased credit is $0.001. Platform USPS verification requires a current paid plan and 10 purchased credits ($0.01) per address, additional to the software allowance. Signup and bonus credits cannot fund it. The live table lives at GET /api/credits/pricing, which is the same map the meter charges from, so it can never quote a price you aren't billed.

Order of spend

1Eligible software operations use your plan allowance first. The allowance does not pay for a new platform USPS verification.
2Purchased credits fund platform USPS verification before every upstream call. Other eligible software operations use credits after their allowance is exhausted.
3When paid entitlement or purchased funding is unavailable, the provider call stops. At zero a funded call returns 402 credits_exhausted before any work runs, so an exhausted balance costs you a millisecond, not a partial result.

Reading your balance

# Every metered response carries the balance in headers
X-Credits-Charged: 15
X-Credits-Remaining: 48210

# Full balance, expiry and burn
curl -s https://api.revaddress.com/api/my/credits \
  -H "X-API-Key: rv_live_..."

# Buy a block (returns a Stripe Checkout URL)
curl -s -X POST https://api.revaddress.com/api/my/credits/checkout \
  -H "X-API-Key: rv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"block":"block_200","terms_accepted":true,"terms_version":"2026-10-01"}'

Free on signup

1,000 promotional credits, good for 30 days, for eligible Census and Census data operations only. They cannot fund paid provider calls.

Expiry

Credits you paid for last 12 months. Bonus credits last 90 days and apply only to eligible software operations; they cannot fund USPS or another paid provider.

Bring your own USPS license

BYOK uses your own provider account where enabled. It does not bypass current paid access or funding checks. Charges on your USPS license remain your responsibility.

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