PS 01

Overview

POST Request verifies access to a deliverable mailbox by sending it a single-use QR code. When the card is completed, your signed webhook fires. Standard delivery is scheduled for 5–7 business days.

All endpoints live under /api/v1, speak JSON, and return errors that say what to do next. Nothing here apologizes for the latency: the latency is the credential.

PS 02

Authentication

Pass your API key as a Bearer token. Keys come in two modes — pr_test_… and pr_live_… — and the key you use decides which mode the verification is created in. There is no mode parameter; there is only the key.

curl https://postrequest.dev/api/v1/verifications \
  -H "Authorization: Bearer pr_live_..."

PS 03

Test mode

Test mode is the whole product with the clock compressed: mail “prints” in ~10 seconds, “delivers” in ~60, costs nothing, and never touches your credit balance. The QR is shown in the dashboard so you can scan it with your own phone and be your own end user — same verification page, same webhook, same green stamp.

Everything below behaves identically in both modes except the clock and the ledger.

PS 04

Create a verification

POST /api/v1/verifications

Validates the address, debits your balance, prints a card, and mails it. Validation runs before the debit — a bad address is a 422, not a $1.25 lesson. No recipient name is accepted anywhere: mailpieces are addressed to CURRENT RESIDENT, by design.

// 201 Created
{
  "id": "01JZ3NVJ4M8Q...",
  "class": "standard",
  "status": "created",
  "price_cents": 125,
  "balance_cents": 9875,
  "expires_at": "2026-08-18T00:00:00Z",
  "signals": {
    "address_reuse_count": 0,
    "cluster_count": 0,
    "po_box": false,
    "cmra": null
  }
}

// 402 — insufficient credits. Nothing printed. See "Recommended patterns".
{ "error": "insufficient_credits", "balance_cents": 50, "required_cents": 125 }

// 422 — the address failed validation. Nothing debited.
{ "error": "invalid_address", "field": "address.zip", "detail": "..." }

// 429 — this address hit the global limit: 3 mailpieces per 7 days,
// across ALL senders. Harassment protection; not negotiable.
{ "error": "address_rate_limited" }

PS 05

Retrieve & list

GET /api/v1/verifications/:id

Returns the full record, the signals block, and the events timeline — CREATED → PRINTED → IN TRANSIT → DELIVERED → VERIFIED, with timestamps. It is USPS tracking, because that is what it is.

GET /api/v1/verifications?status=&external_id=&limit=

The manifest listing. Filter by status or your external_id.

PS 06

Resend

POST /api/v1/verifications/:id/resend

Voids the old QR token, prints a new card, mails it, and debits full price — new mailpiece, new postage. Returns 409 if the verification already succeeded or its address has been purged.

PS 07

Erase PII

DELETE /api/v1/verifications/:id/pii

Erasure passthrough for your users’ deletion requests: the plaintext address and any bound email are destroyed immediately instead of at terminal + 90 days. Keyed fingerprints, the events timeline, and a redacted display form are retained.

PS 08

Credits

GET /api/v1/credits

Balance and the append-only ledger. Credits are dollars, held in cents. They never expire.

POST /api/v1/credits/checkout

Returns a Stripe Checkout URL for a top-up. amount_cents minimum is 2500 — we sell books of stamps, not single stamps. Your card is saved in the same Checkout for auto-recharge.

PS 09

Webhooks

Four events: verification.delivered / .verified / .expired / .undeliverable. Delivered is your cue to nudge your user — “your card arrived, go check the mail” — and it is the cheapest conversion lever in the whole loop. Five delivery attempts with exponential backoff; every attempt is logged in the dashboard and can be redelivered.

{
  "type": "verification.verified",
  "id": "01JZ3NVJ4M8Q...",
  "external_id": "user_8123",
  "class": "standard",
  "mode": "live",
  "status": "verified",
  "delivered_at": "2026-07-16T19:41:00Z",
  "verified_at": "2026-07-17T15:02:11Z",
  "binding": "email_otp",
  "address_fingerprint": "fp_9c44..."
}

Payloads carry the keyed address fingerprint, never the address.

PS 10

Verifying signatures

Every delivery is signed in X-Post-Request-Signature using the Stripe scheme: t=timestamp,v1=hex, where v1 is HMAC-SHA256 of `${timestamp}.${body}` under your signing secret.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(header, body, secret) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");
  const expectedBytes = Buffer.from(expected, "hex");
  const receivedBytes = Buffer.from(v1, "hex");
  return expectedBytes.length === receivedBytes.length &&
    timingSafeEqual(expectedBytes, receivedBytes);
}

PS 11 · Verbatim

What verification attests

binding: none

a party with physical access to mail at this address completed the loop.

binding: email_otp

the party controlling this email address also completed a credential delivered to this address. A stolen or photographed mailpiece cannot complete the loop without the email code, and the code cannot complete it without the mailpiece.

Neither mode attests legal identity or one-human uniqueness. Abuse resistance comes from address economics, reuse counts, building-level clusters, PO-box detection, and customer policy.

PS 12 · Form PS-110

What we store

The encrypted mailing address remains on the verification through terminal state + 90 days. It then moves to a separate encrypted vault without customer or verification IDs. Redacted address text and keyed fingerprints remain on the verification. Do not place personal data in external_id or metadata; those fields remain on the verification.

PS 13

Recommended patterns

The 402. Treat verification creation as queueable: on 402, enqueue, alert yourself, retry after top-up. Your user was going to wait five days anyway; thirty minutes of queue delay is invisible. Our latency makes insufficient-balance errors uniquely survivable, and we are telling you so in writing.

User-pays. For human-only communities, pass the fee through. Each additional account now needs another deliverable-address allocation and a card payment. Nothing in our API changes — charge your user, then call us.

The delivered nudge. On verification.delivered, email your user. The delivered event exists so you can prompt them to check the mail while the card is current.

PS 14 · Effective July 2026

Rates & conversion math

Pricing is per mailpiece, not per success. Effective cost per verified user equals the mailpiece rate divided by your observed completion rate. We do not yet publish a production completion benchmark; measure your own cohort. Postage is non-refundable, with one exception: undeliverable Certified mail refunds 50%. Expired cards refund nothing — delivery happened; the human didn’t act. Credits never expire.