---
title: "Health Insurance Claim Packets: API schema and JSON request"
description: Collect the patient, payer, claim, sender, deadline, and attachment details needed to prepare a mailed claim submission, requested-document response, or informal reprocessing packet. Require the user to verify the plan's current procedure, destination, and deadline, and do not represent this workflow as a formal appeal.
seotitle: Health Insurance Claim Packets API schema | PostalForm
seo-description: "Automate Health Insurance Claim Packets with PostalForm: field identifiers, recipient routing, attachments, a JSON request template and the guided browser workflow."
group: resources
indexable: true
llms: true
nav: false
schema: webpage
published: 2026-04-24
updated: 2026-07-11
path: /developers/forms/health-insurance-claim-packets
---
# Health Insurance Claim Packets: API schema and JSON request

Collect the patient, payer, claim, sender, deadline, and attachment details needed to prepare a mailed claim submission, requested-document response, or informal reprocessing packet. Require the user to verify the plan's current procedure, destination, and deadline, and do not represent this workflow as a formal appeal.

## How does an agent prepare this form?
PostalForm uses the same workflow definition for this API reference and its guided browser form. Fetch the live schema, collect the active required fields and attachments, and validate the completed request. Review the generated PDF, resolved recipient, mailing service and price with the owner before authorizing payment.

## Submission and recipient rules
| Setting | Current workflow value |
| --- | --- |
| Form slug | `health-insurance-claim-packets` |
| Recipient mode | `user` |
| Certified Mail | optional |
| Base U.S. mail service | USPS First-Class Mail (`mail_class="standard"` in the API); not USPS Marketing Mail |
| Attachment total limit | 12 MB |
| Validate without payment | `POST /api/machine/orders/validate` or `POST /api/machine/mpp/orders/validate` |
| Machine order | `POST /api/machine/orders` (x402) or `POST /api/machine/mpp/orders` (MPP) |

Send a top-level `form` instead of `pdf` or `letter`; those three document sources are mutually exclusive. Workflow forms are letters, not postcards. The machine envelope requires buyer, sender and recipient fields. For predefined or computed recipients, the server binds the final recipient to the workflow rules. Inspect the resolved recipient returned by validation; do not substitute a convenient office address.

The template below is structural, not ready to submit: replace every placeholder, complete the active fields, omit unused optional attachments, and use the field options and visibility rules in the schema. Empty strings and unchecked checkboxes are not user answers. Never infer a signature, legal eligibility, factual declaration or consent from a default value.

## JSON request template
```json
{
  "request_id": "<new UUID; preserve on retry>",
  "buyer_name": "<buyer name>",
  "buyer_email": "<buyer email>",
  "sender_name": "<sender name>",
  "sender_address_type": "Manual",
  "sender_address_manual": {
    "line1": "<street address>",
    "city": "<city>",
    "state": "<state or region>",
    "zip": "<postal code>",
    "countryCode": "US"
  },
  "recipient_name": "<confirmed recipient name>",
  "recipient_address_type": "Manual",
  "recipient_address_manual": {
    "line1": "<street address>",
    "city": "<city>",
    "state": "<state or region>",
    "zip": "<postal code>",
    "countryCode": "US"
  },
  "mail_class": "standard",
  "double_sided": true,
  "color": false,
  "certified": false,
  "form": {
    "slug": "health-insurance-claim-packets",
    "fields": {
      "lane_initial_claim": false,
      "lane_supporting_documents": false,
      "lane_reprocessing_request": false,
      "lane_accident_or_cob_follow_up": false,
      "patient_name": "",
      "member_id": "",
      "patient_date_of_birth": "",
      "plan_name": "",
      "claim_number": "",
      "request_reference": "",
      "provider_name": "",
      "amount_claimed": "",
      "service_from_date": "",
      "service_to_date": "",
      "submission_deadline": "",
      "request_summary": "",
      "requested_action": "",
      "requested_by_date": "",
      "previous_submission_details": "",
      "reprocessing_context": "",
      "accident_or_other_insurance_details": "",
      "sender_name": "",
      "sender_role": "",
      "sender_email": "",
      "sender_phone": "",
      "sender_address": "",
      "payer_name": "",
      "recipient_name": "",
      "recipient_address": "",
      "payer_instructions_acknowledged": false,
      "appeal_process_acknowledged": false,
      "acceptance_acknowledged": false
    },
    "attachments": [
      {
        "id": "claim_forms",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "itemized_bills",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "eobs_or_denial_letters",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "medical_records",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "payer_correspondence",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "other_supporting_documents",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      }
    ]
  }
}
```

## Field reference
| Field ID | Label | Type | Required when active | Choices |
| --- | --- | --- | --- | --- |
| `lane_initial_claim` | New claim or reimbursement packet | checkbox | Yes | See schema |
| `lane_supporting_documents` | Requested supporting documents | checkbox | Yes | See schema |
| `lane_reprocessing_request` | Claim reprocessing or follow-up | checkbox | Yes | See schema |
| `lane_accident_or_cob_follow_up` | Accident or coordination-of-benefits follow-up | checkbox | Yes | See schema |
| `patient_name` | Patient or member full name | text | Yes | See schema |
| `member_id` | Member ID or subscriber number | text | Yes | See schema |
| `patient_date_of_birth` | Patient date of birth (optional) | date | No | See schema |
| `plan_name` | Plan or insurer name (optional) | text | No | See schema |
| `claim_number` | Claim number (if you have one) | text | No | See schema |
| `request_reference` | Payer letter date or request reference (optional) | text | No | See schema |
| `provider_name` | Provider or facility name | text | Yes | See schema |
| `amount_claimed` | Claim amount or reimbursement amount (optional) | text | No | See schema |
| `service_from_date` | Service from date (optional) | date | No | See schema |
| `service_to_date` | Service to date (optional) | date | No | See schema |
| `submission_deadline` | Payer filing or response deadline (optional) | date | No | See schema |
| `request_summary` | In 1-2 sentences, what should the payer know first? | textarea | Yes | See schema |
| `requested_action` | What do you want the payer to do? (optional) | textarea | No | See schema |
| `requested_by_date` | Requested response or review date (optional) | date | No | See schema |
| `previous_submission_details` | What was previously submitted or requested? (optional) | textarea | No | See schema |
| `reprocessing_context` | Why does the claim need review or reprocessing? (optional) | textarea | No | See schema |
| `accident_or_other_insurance_details` | Accident, COB, or other insurance details (optional) | textarea | No | See schema |
| `sender_name` | Sender name | text | Yes | See schema |
| `sender_role` | Sender role (optional) | select | No | Patient or member, Parent or guardian, Authorized representative, Provider billing office, Attorney or advocate |
| `sender_email` | Reply email | text | Yes | See schema |
| `sender_phone` | Reply phone (optional) | text | No | See schema |
| `sender_address` | Your mailing address | address | Yes | See schema |
| `payer_name` | Payer or insurer name | text | Yes | See schema |
| `recipient_name` | Claims department or attention line | text | Yes | See schema |
| `recipient_address` | Payer mailing address | address | Yes | See schema |
| `payer_instructions_acknowledged` | I verified the payer's current claim form, required documents, exact mailing destination, and filing or response deadline. | checkbox | Yes | See schema |
| `appeal_process_acknowledged` | I understand this packet is not a substitute for a formal internal appeal or external review, and I will follow the appeal instructions in any denial notice or plan document. | checkbox | Yes | See schema |
| `acceptance_acknowledged` | I understand proof of mailing or delivery does not prove that the payer accepted, processed, or timely received the claim under its rules. | checkbox | Yes | See schema |

Compound fields use nested objects keyed by subfield ID. Evaluate group and field visibility before deciding which fields are active. Conditional requirements, validation rules, recipient rules, attachment formats and compliance policies are preserved in the complete schema below.

## Complete workflow schema
```json
{
  "schema_version": 1,
  "workflow_version": 1,
  "slug": "health-insurance-claim-packets",
  "name": "Health Insurance Claim Packets",
  "description": "Build a health insurance claim packet online, review the generated PDF, and mail it to the payer or claims department with tracking.",
  "agent_summary": "Collect the patient, payer, claim, sender, deadline, and attachment details needed to prepare a mailed claim submission, requested-document response, or informal reprocessing packet. Require the user to verify the plan's current procedure, destination, and deadline, and do not represent this workflow as a formal appeal.",
  "form_summary": "Use this workflow to organize a mailed health insurance claim, requested-document response, or informal reprocessing packet with a cover page, claim letter, summary, exhibit index, and supporting documents. It is not a substitute for the plan's formal appeal or external-review process.",
  "data_collected": [
    "Patient or member details, plan details, and service dates",
    "Health insurer, claims department, and mailing destination",
    "Claim or reimbursement summary, claim number, and requested action",
    "Claim forms, bills, EOBs or denial letters, medical records, and supporting correspondence"
  ],
  "topics": [
    "health insurance",
    "insurance",
    "claims",
    "medical"
  ],
  "category": "health_insurance_claim_packets",
  "publish_state": "published",
  "aliases": [
    "health-insurance-claim-packet",
    "medical-claim-packets"
  ],
  "llms": true,
  "indexable": true,
  "certified_mail": "optional",
  "recipient": {
    "mode": "user"
  },
  "checkout_flow": "forms_order",
  "published_at": "2026-04-24",
  "updated_at": "2026-07-11",
  "groups": [
    {
      "id": "packet_type",
      "label": "Claim packet type",
      "description": "What are you mailing? Pick the option that matches the letter or claim you have — we'll tailor the packet to it.",
      "depends_on": []
    },
    {
      "id": "patient",
      "label": "Patient and member details",
      "description": "Identify the patient, member, and plan details that should appear in the packet.",
      "depends_on": []
    },
    {
      "id": "claim",
      "label": "Claim details",
      "description": "Explain the services, claim context, and the action you want the payer to take.",
      "depends_on": []
    },
    {
      "id": "sender",
      "label": "Your details",
      "description": "Provide the sender information that should appear in the packet and return address.",
      "depends_on": []
    },
    {
      "id": "recipient",
      "label": "Payer mailing address",
      "description": "Enter the claims department or payer mailing address you want the packet mailed to.",
      "depends_on": []
    },
    {
      "id": "review",
      "label": "Submission review",
      "description": "Confirm the payer's current claim procedure, destination, documents, and deadline before building the packet.",
      "depends_on": []
    }
  ],
  "fields": [
    {
      "id": "lane_initial_claim",
      "label": "New claim or reimbursement packet",
      "type": "checkbox",
      "required": true,
      "meta_class": "radio",
      "ui_width": null,
      "group_id": "packet_type",
      "choice_group": "packet_type_selection",
      "choice_label": "Which packet type best matches what you need?",
      "depends_on": [],
      "compound": null
    },
    {
      "id": "lane_supporting_documents",
      "label": "Requested supporting documents",
      "type": "checkbox",
      "required": true,
      "meta_class": "radio",
      "ui_width": null,
      "group_id": "packet_type",
      "choice_group": "packet_type_selection",
      "choice_label": "Which packet type best matches what you need?",
      "depends_on": [],
      "compound": null
    },
    {
      "id": "lane_reprocessing_request",
      "label": "Claim reprocessing or follow-up",
      "type": "checkbox",
      "required": true,
      "meta_class": "radio",
      "ui_width": null,
      "group_id": "packet_type",
      "choice_group": "packet_type_selection",
      "choice_label": "Which packet type best matches what you need?",
      "depends_on": [],
      "compound": null
    },
    {
      "id": "lane_accident_or_cob_follow_up",
      "label": "Accident or coordination-of-benefits follow-up",
      "type": "checkbox",
      "required": true,
      "meta_class": "radio",
      "ui_width": null,
      "group_id": "packet_type",
      "choice_group": "packet_type_selection",
      "choice_label": "Which packet type best matches what you need?",
      "depends_on": [],
      "compound": null
    },
    {
      "id": "patient_name",
      "label": "Patient or member full name",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "patient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "member_id",
      "label": "Member ID or subscriber number",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "patient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "patient_date_of_birth",
      "label": "Patient date of birth (optional)",
      "type": "date",
      "required": false,
      "meta_class": "date",
      "ui_width": "half",
      "group_id": "patient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "plan_name",
      "label": "Plan or insurer name (optional)",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "patient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "claim_number",
      "label": "Claim number (if you have one)",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "request_reference",
      "label": "Payer letter date or request reference (optional)",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "lane_initial_claim",
        "operator": "falsy"
      },
      "depends_on": [
        "lane_initial_claim"
      ],
      "compound": null
    },
    {
      "id": "provider_name",
      "label": "Provider or facility name",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "amount_claimed",
      "label": "Claim amount or reimbursement amount (optional)",
      "type": "text",
      "required": false,
      "meta_class": "currency",
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "service_from_date",
      "label": "Service from date (optional)",
      "type": "date",
      "required": false,
      "meta_class": "date",
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "service_to_date",
      "label": "Service to date (optional)",
      "type": "date",
      "required": false,
      "meta_class": "date",
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "submission_deadline",
      "label": "Payer filing or response deadline (optional)",
      "type": "date",
      "required": false,
      "meta_class": "date",
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "request_summary",
      "label": "In 1-2 sentences, what should the payer know first?",
      "type": "textarea",
      "required": true,
      "placeholder": "e.g., Requesting reimbursement for out-of-network visits on 3/2 and 3/9; claim form and itemized bills enclosed.",
      "meta_class": null,
      "ui_width": null,
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "requested_action",
      "label": "What do you want the payer to do? (optional)",
      "type": "textarea",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "requested_by_date",
      "label": "Requested response or review date (optional)",
      "type": "date",
      "required": false,
      "meta_class": "date",
      "ui_width": "half",
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "previous_submission_details",
      "label": "What was previously submitted or requested? (optional)",
      "type": "textarea",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "lane_supporting_documents",
        "operator": "truthy"
      },
      "depends_on": [
        "lane_supporting_documents"
      ],
      "compound": null
    },
    {
      "id": "reprocessing_context",
      "label": "Why does the claim need review or reprocessing? (optional)",
      "type": "textarea",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "lane_reprocessing_request",
        "operator": "truthy"
      },
      "depends_on": [
        "lane_reprocessing_request"
      ],
      "compound": null
    },
    {
      "id": "accident_or_other_insurance_details",
      "label": "Accident, COB, or other insurance details (optional)",
      "type": "textarea",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "claim",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "lane_accident_or_cob_follow_up",
        "operator": "truthy"
      },
      "depends_on": [
        "lane_accident_or_cob_follow_up"
      ],
      "compound": null
    },
    {
      "id": "sender_name",
      "label": "Sender name",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_role",
      "label": "Sender role (optional)",
      "type": "select",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "options": [
        "Patient or member",
        "Parent or guardian",
        "Authorized representative",
        "Provider billing office",
        "Attorney or advocate"
      ],
      "compound": null
    },
    {
      "id": "sender_email",
      "label": "Reply email",
      "type": "text",
      "required": true,
      "meta_class": "email",
      "ui_width": null,
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_phone",
      "label": "Reply phone (optional)",
      "type": "text",
      "required": false,
      "meta_class": "phone",
      "ui_width": null,
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_address",
      "label": "Your mailing address",
      "type": "address",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "payer_name",
      "label": "Payer or insurer name",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "recipient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "recipient_name",
      "label": "Claims department or attention line",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "recipient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "recipient_address",
      "label": "Payer mailing address",
      "type": "address",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "recipient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "payer_instructions_acknowledged",
      "label": "I verified the payer's current claim form, required documents, exact mailing destination, and filing or response deadline.",
      "type": "checkbox",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "review",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "appeal_process_acknowledged",
      "label": "I understand this packet is not a substitute for a formal internal appeal or external review, and I will follow the appeal instructions in any denial notice or plan document.",
      "type": "checkbox",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "review",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "acceptance_acknowledged",
      "label": "I understand proof of mailing or delivery does not prove that the payer accepted, processed, or timely received the claim under its rules.",
      "type": "checkbox",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "review",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    }
  ],
  "attachments": [
    {
      "id": "claim_forms",
      "label": "Claim form or insurer packet",
      "required": true,
      "instructions": "Attach the payer's current completed claim or reimbursement form, signed anywhere the payer requires a signature.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 6,
      "max_size_mb": 12
    },
    {
      "id": "itemized_bills",
      "label": "Itemized bills or receipts",
      "required": false,
      "instructions": "Attach itemized provider bills, receipts, or statements that support the claim amount.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 10,
      "max_size_mb": 12
    },
    {
      "id": "eobs_or_denial_letters",
      "label": "EOBs or denial letters",
      "required": false,
      "instructions": "Attach any explanation of benefits, denial notice, or request-for-information letter that explains the follow-up.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 10,
      "max_size_mb": 12
    },
    {
      "id": "medical_records",
      "label": "Medical records or referrals",
      "required": false,
      "instructions": "Attach chart notes, referrals, prescriptions, or other records the payer asked you to provide.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 12,
      "max_size_mb": 12
    },
    {
      "id": "payer_correspondence",
      "label": "Payer instructions or correspondence",
      "required": false,
      "instructions": "Attach letters, portal printouts, or instructions showing where the claim packet should go and what it should include.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 10,
      "max_size_mb": 12
    },
    {
      "id": "other_supporting_documents",
      "label": "Other supporting documents",
      "required": false,
      "instructions": "Any other record you want appended behind the packet.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 10,
      "max_size_mb": 12
    }
  ],
  "attachments_max_total_size_mb": 12,
  "machine_submission": {
    "payload_property": "form",
    "create_paths": {
      "x402": "/api/machine/orders",
      "mpp": "/api/machine/mpp/orders"
    }
  }
}
```

## Preview, payment and retries
Validation does not mail the document. For a human checkout, use MCP `postalform.create_form_order_draft` and present the returned preview, total and checkout URL. Machine API clients must handle the returned MPP or x402 challenge only within owner-approved spending authority. Preserve `request_id` and the exact payload for retries; changing the content requires a new request ID. After an uncertain payment, retrieve order status before creating another order. Provider handoff is not USPS delivery.


## Resources
- [All machine form schemas](/developers/forms)
- [Guided form](/forms/health-insurance-claim-packets)
- [Current JSON schema](/api/machine/forms/health-insurance-claim-packets/schema)
- [Machine order guide](/agents)
- [Pricing](/pricing)


## Ready to send it?
[Open guided form](/forms/health-insurance-claim-packets)