Claims Workflow

The Claims API allows administrators and TPAs to submit claims with evidence for automated adjudication. Silver's engine validates service dates, verifies amounts, extracts line-item detail from evidence documents, and returns a recommendation.

Submitting a Claim

Submit a claim with base64-encoded evidence attached:

curl -X POST https://claim-api.withsilver.app/v1/claims \
  -H "apiKey: your-admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "claim_number": "CLM-2025-00042",
    "claim_amount": 15000,
    "service_start_date": "2025-03-10",
    "service_end_date": "2025-03-10",
    "submission_date": "2025-03-15",
    "provider": "Lakewood Family Dentistry",
    "employer": "Acme Corp",
    "description": "Routine dental cleaning and X-rays",
    "expense_category": "Dental",
    "expense_type": "Preventive Care",
    "method_filed": "online",
    "plan_name": "Acme 2025 Medical FSA",
    "plan_type": "medical_fsa",
    "plan_year_start": "2025-01-01",
    "plan_year_end": "2025-12-31",
    "final_submission_date": "2026-03-31",
    "final_service_date": "2025-12-31",
    "evidence": [
      {
        "mime_type": "application/pdf",
        "content": "JVBERi0xLjQKJeLjz9MK..."
      }
    ]
  }'

Amounts are in cents

All monetary values in the Claims API are integers representing cents. For example, 15000 represents $150.00.

Response:

{
  "claim_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Required Fields

Field	Type	Description
claim_number	string	Your unique claim number
claim_amount	integer	Claimed amount in cents
service_start_date	date	Start date of the service
service_end_date	date	End date of the service
submission_date	date	Date the claim was submitted
plan_name	string	Benefit plan name
plan_type	string	Plan type: medical_fsa, dcfsa, hra, lpfsa, or lsa
plan_year_start	date	Plan year start date
plan_year_end	date	Plan year end date
final_submission_date	date	Last submission date (including run-out)
final_service_date	date	Last eligible service date
evidence	array	One or more base64-encoded files (mime_type + content)

Duplicate Detection

If a claim with the same claim_number already exists, the API returns a 400 response with the existing claim_id:

{
  "error": "A claim with this claim_number already exists",
  "claim_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Retrieving Claim Results

Once submitted, retrieve the full claim details including parsed evidence and adjudication results:

curl -X GET "https://claim-api.withsilver.app/v1/claims?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "apiKey: your-admin-api-key"

The response includes:

• Original claim data — All fields submitted with the claim
• Parsed evidence — Receipts, medical invoices, dependent care invoices, and statements of account extracted from the evidence documents
• Adjudication results — Silver's recommendation and detailed validation

Adjudication Results

The adjudication_results object is null until adjudication completes. Once available, it contains:

Field	Type	Description
silver_recommendation	string	Silver's recommendation (see below)
valid_service_date	boolean	Whether the service dates are within the plan year
valid_total_amount	boolean	Whether the claimed amount matches the evidence
out_of_pocket_total	integer	Total out-of-pocket amount found in evidence (in cents)
deny_code	string	Machine-readable denial reason (null if not denied)
deny_text	string	Human-readable denial explanation (null if not denied)

Recommendation Values

Recommendation	Meaning
approve	Claim is recommended for approval
deny	Claim is recommended for denial
needs_review	Claim requires manual review by an administrator
not_needed	Adjudication is not needed for this claim
request_more_information	Additional information or evidence is needed

Parsed Evidence

Silver automatically parses evidence documents and returns structured data in four categories:

Field	Description
receipts	Purchase receipts with merchant, items, and totals
medical_invoices	Medical invoices/EOBs with service-level detail
dependent_care_invoices	Dependent care invoices with charges and payments
statement_of_accounts	Provider statements with ledger entries

Each category contains line-item detail with amounts (in cents), dates, eligibility determinations, and billing codes where applicable.

Polling vs. Webhooks

You can track adjudication status in two ways:

• Polling — Periodically call GET /v1/claims?id={claim_id} and check whether adjudication_results is non-null. Simple but introduces latency.
• Webhooks — Receive a real-time notification when adjudication completes. See Webhooks Overview.

Use webhooks for production

For production integrations, webhooks provide real-time updates without the overhead of polling. Use polling as a fallback for missed webhook deliveries.