PostalForm Machine API

openapi: 3.2.0
info:
  title: PostalForm Payments Machine API
  version: 1.0.0
  description: Machine-oriented print-and-mail endpoints for x402 and MPP payment flows.
  license:
    name: Proprietary
    url: https://postalform.com/terms
  x-agent-guidance: 'Use OpenAPI as the canonical discovery source for this origin. The /.well-known/x402 manifest is a lightweight compatibility layer for crawlers and agent runtimes that do not yet ingest the full OpenAPI document.


    For both machine payment families, call the validate endpoint first to verify the payload and get a quote before attempting payment.


    When retrying a create call after a 402 challenge, reuse the same request_id and the exact same JSON body. PostalForm treats request_id as the strict idempotency key and rejects payload drift for that request_id.


    If you intend to send the same document to the same addresses again after a prior order is paid or settled, generate a fresh request_id. PostalForm only collapses recent unpaid duplicate drafts.


    For each address party, choose exactly one strategy: Address with *_address_id and *_address_text, or Manual with *_address_manual. Do not send both strategies for the same party.


    Address countries default to US when omitted. For international manual addresses, include countryCode; for Loqate addresses, the id prefix carries the country. Both modes accept exactly the same mailing countries offered by PostalForm''s checkout address picker: US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL.


    Prefer pdf as { "upload_token": "..." } when you already have a finished PDF. The create endpoint also accepts { download_url, file_id }, a data:application/pdf;base64 URL, or an allowlisted HTTPS URL.


    For server-rendered letters, send a top-level letter value instead of pdf. letter may be a string or an object with body, title, signature, render options, and format. signature may be a string or { mode: "typed" | "drawn", text?, dataUrl?, printDataUrl? }. format can be text, html, markdown, or rtf; default is text.


    Unpaid single-recipient create responses may include preview_url, a signed short-lived URL for reviewing the generated or uploaded PDF before payment.


    For supported single-mailpiece workflow forms, discover forms with GET /api/machine/forms, fetch GET /api/machine/forms/{slug}/schema, then send a top-level form object instead of pdf or letter to the same create/validate endpoints. Statutory multi-recipient workflows are intentionally excluded.


    For bulk mailing campaigns, send a bulk object instead of recipient_name and recipient address fields. bulk.csv_content holds the recipient CSV, bulk.content_mode selects text, html, or pdf rendering, and validation returns bulk.recipient_count plus bulk.content_mode.


    Bulk machine create and poll responses may include campaign_url. Use that route to inspect row-level mailed-item status, delivery events, and tracking for each CSV recipient.


    For flower letters, use the dedicated /api/machine/flower-letters or /api/machine/mpp/flower-letters endpoints. They require a Florist One product code, recipient ZIP, delivery date, full delivery address, and a 200-character card note.


    For MPP-only shipping labels, use /api/machine/mpp/shipping-labels. Include exact packed weight in ounces and all three parcel dimensions in inches. Validate first, then reuse the identical request_id and body after the 402 challenge. A successful immediate payment returns a signed PDF download URL; delayed settlements expose it from the status endpoint and order completion page once fulfillment finishes.


    For postcards, keep using the same endpoints and payment flow. Set mailpiece_type to postcard, provide postcard_size, and supply pdf as the fully composed postcard PDF. Lob-routed international postcards require postcard_size="4x6" and a U.S. sender/return address; larger international postcards or international postcards with non-U.S. return addresses route to PostGrid before provider submission. See https://postalform.com/postcard-pdf-guidelines for the required 2-page bleed templates and mailing-side layout.


    Use POST /api/machine/orders for x402. The server returns 402 with PAYMENT-REQUIRED and expects PAYMENT-SIGNATURE on retry.


    Use POST /api/machine/mpp/orders for MPP. The server returns 402 with one or more WWW-Authenticate: Payment challenges and expects Authorization: Payment on retry.


    Poll GET /api/machine/orders/{id} or GET /api/machine/mpp/orders/{id} until payment_status becomes paid or the order reaches its terminal status. Those status endpoints accept either the canonical order_id or any aliased request_id returned during create/validate.'
servers:
- url: https://postalform.com
security: []
tags:


# --- truncated at 32 KB (151 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postalform-com/refs/heads/main/openapi/postalform-com-machine-api-openapi.yml