Skip to main content

Claim Submission Workflow

The Claim Submission API uses a multi-step flow to submit reimbursement claims. Each step builds on the previous one.

Submission Flow​

┌─────────────────┐     ┌──────────────────┐     ┌───────────────────┐     ┌──────────────┐
│  1. List         │────▶│  2. Get Provider  │────▶│  3. Upload        │────▶│  4. Submit   │
│  Providers       │     │  Form Reqs        │     │  Documents        │     │  Claim       │
└─────────────────┘     └──────────────────┘     └───────────────────┘     └──────────────┘

Step 1: List Providers​

Retrieve available providers for claim submission.

curl -X GET https://claim-submission.withsilver.app/v1/providers \
  -H "apiKey: your-partner-api-key"

Response:

[
  {
    "id": "prv_abc123",
    "name": "Wellness Center",
    "logo": "https://cdn.withsilver.app/logos/wellness-center.png",
    "type": "service"
  },
  {
    "id": "prv_def456",
    "name": "PharmaCo",
    "logo": "https://cdn.withsilver.app/logos/pharmaco.png",
    "type": "product"
  }
]

Step 2: Get Provider Form Requirements​

Fetch the provider's details including form requirements. These describe the fields that must be populated in user_form_fields when submitting a claim.

curl -X GET https://claim-submission.withsilver.app/v1/providers/prv_abc123 \
  -H "apiKey: your-partner-api-key"

Response:

{
  "id": "prv_abc123",
  "name": "Wellness Center",
  "logo": "https://cdn.withsilver.app/logos/wellness-center.png",
  "type": "service",
  "form_requirements": [
    {
      "field_name": "employee_id",
      "label": "Employee ID",
      "type": "text",
      "required": true
    },
    {
      "field_name": "relationship",
      "label": "Relationship to Plan Holder",
      "type": "select",
      "required": true,
      "options": ["self", "spouse", "dependent"]
    }
  ]
}

Use the form_requirements to build your claim submission form dynamically. Pay attention to:

  • Required fields — Must be included in user_form_fields when submitting
  • Field types — Determines input validation (text, number, date, select)
  • Options — For select fields, use the provided options list

Step 3: Upload Claimable Documents​

Upload supporting documents (receipts, invoices, EOBs) along with their line-item services. Documents are submitted as base64-encoded files. Each upload returns a document ID to reference when submitting the claim.

curl -X POST https://claim-submission.withsilver.app/v1/claimable_documents \
  -H "apiKey: your-partner-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_m3mb3r01",
    "document_type": "receipt",
    "file": {
      "base64": "JVBERi0xLjQKJcfs...",
      "mime_type": "application/pdf"
    },
    "claimable_services": [
      {
        "service_date_start": "2026-01-10",
        "service_date_end": "2026-01-10",
        "service_provider": "Downtown Physical Therapy",
        "service_description": "Physical therapy session — 60 min",
        "claimable_amount": 150.00
      }
    ],
    "supporting_documents": [
      {
        "base64": "iVBORw0KGgoAAAANS...",
        "mime_type": "image/png"
      }
    ]
  }'

Response: Returns the claimable document ID as a string (e.g., "cdoc_a1b2c3d4").

You can also retrieve and manage the services on a document after creation:

  • List services: GET /v1/claimable_documents/{id}/claimable_services
  • Remove a service: DELETE /v1/claimable_documents/{document_id}/claimable_services/{service_id}

Step 4: Submit the Claim​

Submit the claim referencing the uploaded documents, the chosen provider, the required form fields, and the member's signature (base64-encoded PNG).

curl -X POST https://claim-submission.withsilver.app/v1/claims \
  -H "apiKey: your-partner-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_m3mb3r01",
    "provider_id": "prv_abc123",
    "plan_period_start": "2026-01-01",
    "plan_period_end": "2026-12-31",
    "user_form_fields": {
      "employee_id": "EMP-9876",
      "relationship": "self"
    },
    "signature": "iVBORw0KGgoAAAANSUhEUgAA...",
    "claimable_documents": ["cdoc_a1b2c3d4"]
  }'

Response:

{
  "claim_id": "clm_x7y8z9",
  "user_provider_id": "uprv_11223344"
}

Best Practices​

  1. Check eligibility first — Use the Eligibility API before starting the submission flow to reduce rejections.
  2. Respect the form requirements — Always fetch the provider's form_requirements dynamically rather than hardcoding fields. Requirements may change as plan configurations are updated.
  3. Upload documents before submitting — All document uploads must complete before the claim is submitted.
  4. Store the claim ID — Save the returned claim_id for tracking and customer support purposes.
  5. Include all line-item services — When uploading documents, include the claimable_services array with accurate service dates, amounts, and descriptions.