PostalForm Machine Payments API

{"openapi":"3.1.0","info":{"title":"PostalForm Machine Payments API","version":"1.0.0","description":"Machine-oriented print-and-mail endpoints for x402 and MPP payment flows.\n\nUse 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.\n\nFor both machine payment families, call the validate endpoint first to verify the payload and get a quote before attempting payment.\n\nWhen 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.\n\nIf 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.\n\nFor 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.\n\nAddress 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.\n\nPrefer 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.\n\nFor 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.\n\nUnpaid single-recipient create responses may include preview_url, a signed short-lived URL for reviewing the generated or uploaded PDF before payment.\n\nFor 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.\n\nFor 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.\n\nBulk 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.\n\nFor 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.\n\nFor 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.\n\nFor 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.\n\nUse POST /api/machine/orders for x402. The server returns 402 with PAYMENT-REQUIRED and expects PAYMENT-SIGNATURE on retry.\n\nUse 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.\n\nPoll 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.","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.\n\nFor both machine payment families, call the validate endpoint first to verify the payload and get a quote before attempting payment.\n\nWhen 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.\n\nIf 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.\n\nFor 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.\n\nAddress 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.\n\nPrefer 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.\n\nFor 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.\n\nUnpaid single-recipient create responses may include preview_url, a signed short-lived URL for reviewing the generated or uploaded PDF before payment.\n\nFor 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.\n\nFor 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.\n\nBulk 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.\n\nFor 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.\n\nFor 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.\n\nFor 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.\n\nUse POST /api/machine/orders for x402. The server returns 402 with PAYMENT-REQUIRED and expects PAYMENT-SIGNATURE on retry.\n\nUse 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.\n\nPoll 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."},"security":[],"servers":[{"url":"https://postalform.com"}],"paths":{"/api/machine/forms":{"get":{"operationId":"listMachineForms","summary":"List workflow forms available to machine order flows","description":"Search published single-mailpiece PostalForm workflow forms that agents can fill and submit through the x402 or MPP machine order endpoints. Coordinated statutory multi-recipient workflows are excluded.","parameters":[{"name":"q","in":"query","required":false,"description":"Optional slug/name search string.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous list response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Machine workflow form catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineWorkflowFormListResponse"}}}},"400":{"description":"Invalid form catalog query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/forms/{slug}/schema":{"get":{"operationId":"getMachineFormSchema","summary":"Get a machine-usable workflow form schema","parameters":[{"name":"slug","in":"path","required":true,"description":"Workflow form slug from GET /api/machine/forms.","schema":{"type":"string"}}],"responses":{"200":{"description":"Machine workflow form schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineWorkflowFormSchema"}}}},"404":{"description":"Form not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/orders/validate":{"post":{"operationId":"validateMachineOrder","summary":"Validate an x402 machine order and return a quote","requestBody":{"required":true,"description":"Quote and validate an x402 machine order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"return_receipt_format":"electronic","restricted_delivery":false,"err_delivery":"manual"}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/orders":{"post":{"operationId":"createMachineOrder","summary":"Create or reuse an x402 machine order","description":"Unauthenticated calls return 402 Payment Required when the order is ready to be paid. Retry the exact same body with PAYMENT-SIGNATURE after settlement. A 202 settled_pending_webhook response means Stripe is verifying the transaction; poll status and do not pay again.","requestBody":{"required":true,"description":"Create or reuse an x402 machine order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"return_receipt_format":"electronic","restricted_delivery":false,"err_delivery":"manual"}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"x-payment-info":{"protocols":["x402"],"pricingMode":"range","minPrice":"3.40","maxPrice":"200.00"},"responses":{"200":{"description":"Existing machine order is already paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrder"}}}},"202":{"description":"Payment settled and order is pending finalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrder"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequiredResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/orders/{id}":{"get":{"operationId":"getMachineOrder","summary":"Get x402 machine order status","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical order_id or any aliased request_id returned by the create or validate call.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Machine order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderStatus"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/flower-letters/validate":{"post":{"operationId":"validateMachineFlowerLetter","summary":"Validate an x402 flower-letter order and return a Florist One quote","requestBody":{"required":true,"description":"Quote and validate a dedicated flower-letter order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/flower-letters":{"post":{"operationId":"createMachineFlowerLetter","summary":"Create or reuse an x402 flower-letter order","description":"Unauthenticated calls return 402 Payment Required after PostalForm validates the Florist One product, delivery ZIP, delivery date, and final quote. A 202 settled_pending_webhook response means Stripe is verifying the transaction; poll status and do not pay again.","requestBody":{"required":true,"description":"Create or reuse a dedicated x402 flower-letter order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}}}}}},"x-payment-info":{"protocols":["x402"],"pricingMode":"dynamic","minPrice":"1.00","maxPrice":"250.00"},"responses":{"200":{"description":"Existing flower-letter order is already paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"202":{"description":"Payment settled and provider submission is queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowerLetterPaymentRequiredResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/flower-letters/{id}":{"get":{"operationId":"getMachineFlowerLetter","summary":"Get x402 flower-letter order status","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical order_id or any aliased request_id returned by the create or validate call.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Flower-letter order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/orders/validate":{"post":{"operationId":"validateMppMachineOrder","summary":"Validate an MPP machine order and return a quote","requestBody":{"required":true,"description":"Quote and validate an MPP machine order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"return_receipt_format":"electronic","restricted_delivery":false,"err_delivery":"manual"}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/orders":{"post":{"operationId":"createMppMachineOrder","summary":"Create or reuse an MPP machine order","description":"Unauthenticated calls return 402 Payment Required with WWW-Authenticate: Payment challenges. Retry the exact same body with Authorization: Payment after settlement.","requestBody":{"required":true,"description":"Create or reuse an MPP machine order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"return_receipt_format":"electronic","restricted_delivery":false,"err_delivery":"manual"}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 

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