https://develop.withsilver.app/assets/js/bfc06bf0.fef6cc48.js

1"use strict";(globalThis.webpackChunksilver_developer_docs=globalThis.webpackChunksilver_developer_docs||[]).push([[4396],{46234(e,i,n){n.r(i),n.d(i,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>r,metadata:()=>d,toc:()=>a});const d=JSON.parse('{"id":"administrator/claims/workflow","title":"Claims Workflow","description":"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.","source":"@site/docs/administrator/claims/workflow.md","sourceDirName":"administrator/claims","slug":"/administrator/claims/workflow","permalink":"/docs/administrator/claims/workflow","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"sidebar_position":1,"title":"Claims Workflow"},"sidebar":"administrator","next":{"title":"Introduction","permalink":"/docs/api/claims/fastapi"}}');var s=n(74848),t=n(28453);const r={sidebar_position:1,title:"Claims Workflow"},l="Claims Workflow",c={},a=[{value:"Submitting a Claim",id:"submitting-a-claim",level:2},{value:"Required Fields",id:"required-fields",level:3},{value:"Duplicate Detection",id:"duplicate-detection",level:3},{value:"Retrieving Claim Results",id:"retrieving-claim-results",level:2},{value:"Adjudication Results",id:"adjudication-results",level:3},{value:"Recommendation Values",id:"recommendation-values",level:3},{value:"Parsed Evidence",id:"parsed-evidence",level:3},{value:"Polling vs. Webhooks",id:"polling-vs-webhooks",level:2}];function o(e){const i={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,t.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(i.header,{children:(0,s.jsx)(i.h1,{id:"claims-workflow",children:"Claims Workflow"})}),"\n",(0,s.jsx)(i.p,{children:"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."}),"\n",(0,s.jsx)(i.h2,{id:"submitting-a-claim",children:"Submitting a Claim"}),"\n",(0,s.jsx)(i.p,{children:"Submit a claim with base64-encoded evidence attached:"}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:'curl -X POST https://claim-api.withsilver.app/v1/claims \\\n  -H "apiKey: your-admin-api-key" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "claim_number": "CLM-2025-00042",\n    "claim_amount": 15000,\n    "service_start_date": "2025-03-10",\n    "service_end_date": "2025-03-10",\n    "submission_date": "2025-03-15",\n    "provider": "Lakewood Family Dentistry",\n    "employer": "Acme Corp",\n    "description": "Routine dental cleaning and X-rays",\n    "expense_category": "Dental",\n    "expense_type": "Preventive Care",\n    "method_filed": "online",\n    "plan_name": "Acme 2025 Medical FSA",\n    "plan_type": "medical_fsa",\n    "plan_year_start": "2025-01-01",\n    "plan_year_end": "2025-12-31",\n    "final_submission_date": "2026-03-31",\n    "final_service_date": "2025-12-31",\n    "evidence": [\n      {\n        "mime_type": "application/pdf",\n        "content": "JVBERi0xLjQKJeLjz9MK..."\n      }\n    ]\n  }\'\n'})}),"\n",(0,s.jsx)(i.admonition,{title:"Amounts are in cents",type:"info",children:(0,s.jsxs)(i.p,{children:["All monetary values in the Claims API are integers representing ",(0,s.jsx)(i.strong,{children:"cents"}),". For example, ",(0,s.jsx)(i.code,{children:"15000"})," represents $150.00."]})}),"\n",(0,s.jsx)(i.p,{children:(0,s.jsx)(i.strong,{children:"Response:"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-json",children:'{\n  "claim_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"\n}\n'})}),"\n",(0,s.jsx)(i.h3,{id:"required-fields",children:"Required Fields"}),"\n",(0,s.jsxs)(i.table,{children:[(0,s.jsx)(i.thead,{children:(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.th,{children:"Field"}),(0,s.jsx)(i.th,{children:"Type"}),(0,s.jsx)(i.th,{children:"Description"})]})}),(0,s.jsxs)(i.tbody,{children:[(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.co

1de,{children:"claim_number"})}),(0,s.jsx)(i.td,{children:"string"}),(0,s.jsx)(i.td,{children:"Your unique claim number"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"claim_amount"})}),(0,s.jsx)(i.td,{children:"integer"}),(0,s.jsx)(i.td,{children:"Claimed amount in cents"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"service_start_date"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"Start date of the service"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"service_end_date"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"End date of the service"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"submission_date"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"Date the claim was submitted"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"plan_name"})}),(0,s.jsx)(i.td,{children:"string"}),(0,s.jsx)(i.td,{children:"Benefit plan name"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"plan_type"})}),(0,s.jsx)(i.td,{children:"string"}),(0,s.jsxs)(i.td,{children:["Plan type: ",(0,s.jsx)(i.code,{children:"medical_fsa"}),", ",(0,s.jsx)(i.code,{children:"dcfsa"}),", ",(0,s.jsx)(i.code,{children:"hra"}),", ",(0,s.jsx)(i.code,{children:"lpfsa"}),", or ",(0,s.jsx)(i.code,{children:"lsa"})]})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"plan_year_start"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"Plan year start date"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"plan_year_end"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"Plan year end date"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"final_submission_date"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"Last submission date (including run-out)"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"final_service_date"})}),(0,s.jsx)(i.td,{children:"date"}),(0,s.jsx)(i.td,{children:"Last eligible service date"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"evidence"})}),(0,s.jsx)(i.td,{children:"array"}),(0,s.jsxs)(i.td,{children:["One or more base64-encoded files (",(0,s.jsx)(i.code,{children:"mime_type"})," + ",(0,s.jsx)(i.code,{children:"content"}),")"]})]})]})]}),"\n",(0,s.jsx)(i.h3,{id:"duplicate-detection",children:"Duplicate Detection"}),"\n",(0,s.jsxs)(i.p,{children:["If a claim with the same ",(0,s.jsx)(i.code,{children:"claim_number"})," already exists, the API returns a ",(0,s.jsx)(i.code,{children:"400"})," response with the existing ",(0,s.jsx)(i.code,{children:"claim_id"}),":"]}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-json",children:'{\n  "error": "A claim with this claim_number already exists",\n  "claim_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"\n}\n'})}),"\n",(0,s.jsx)(i.h2,{id:"retrieving-claim-results",children:"Retrieving Claim Results"}),"\n",(0,s.jsx)(i.p,{children:"Once submitted, retrieve the full claim details including parsed evidence and adjudication results:"}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:'curl -X GET "https://claim-api.withsilver.app/v1/claims?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \\\n  -H "apiKey: your-admin-api-key"\n'})}),"\n",(0,s.jsx)(i.p,{children:"The response includes:"}),"\n",(0,s.jsxs)(i.ul,{children:["\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.strong,{children:"Original claim data"})," \u2014 All fields submitted with the claim"]}),"\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.strong,{children:"Parsed evidence"})," \u2014 Receipts, medical invoices, dependent care invoices, and statements of account extracted from the evidence documents"]}),"\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.strong,{children:"Adjudication results"})," \u2014 Silver's recommendation and detailed validation"]}),"\n"]}),"\n",(0,s.jsx)(i.h3,{id:"adjudication-results",children:"Adjudication Results"}

1),"\n",(0,s.jsxs)(i.p,{children:["The ",(0,s.jsx)(i.code,{children:"adjudication_results"})," object is ",(0,s.jsx)(i.code,{children:"null"})," until adjudication completes. Once available, it contains:"]}),"\n",(0,s.jsxs)(i.table,{children:[(0,s.jsx)(i.thead,{children:(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.th,{children:"Field"}),(0,s.jsx)(i.th,{children:"Type"}),(0,s.jsx)(i.th,{children:"Description"})]})}),(0,s.jsxs)(i.tbody,{children:[(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"silver_recommendation"})}),(0,s.jsx)(i.td,{children:"string"}),(0,s.jsx)(i.td,{children:"Silver's recommendation (see below)"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"valid_service_date"})}),(0,s.jsx)(i.td,{children:"boolean"}),(0,s.jsx)(i.td,{children:"Whether the service dates are within the plan year"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"valid_total_amount"})}),(0,s.jsx)(i.td,{children:"boolean"}),(0,s.jsx)(i.td,{children:"Whether the claimed amount matches the evidence"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"out_of_pocket_total"})}),(0,s.jsx)(i.td,{children:"integer"}),(0,s.jsx)(i.td,{children:"Total out-of-pocket amount found in evidence (in cents)"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"deny_code"})}),(0,s.jsx)(i.td,{children:"string"}),(0,s.jsx)(i.td,{children:"Machine-readable denial reason (null if not denied)"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"deny_text"})}),(0,s.jsx)(i.td,{children:"string"}),(0,s.jsx)(i.td,{children:"Human-readable denial explanation (null if not denied)"})]})]})]}),"\n",(0,s.jsx)(i.h3,{id:"recommendation-values",children:"Recommendation Values"}),"\n",(0,s.jsxs)(i.table,{children:[(0,s.jsx)(i.thead,{children:(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.th,{children:"Recommendation"}),(0,s.jsx)(i.th,{children:"Meaning"})]})}),(0,s.jsxs)(i.tbody,{children:[(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"approve"})}),(0,s.jsx)(i.td,{children:"Claim is recommended for approval"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"deny"})}),(0,s.jsx)(i.td,{children:"Claim is recommended for denial"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"needs_review"})}),(0,s.jsx)(i.td,{children:"Claim requires manual review by an administrator"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"not_needed"})}),(0,s.jsx)(i.td,{children:"Adjudication is not needed for this claim"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"request_more_information"})}),(0,s.jsx)(i.td,{children:"Additional information or evidence is needed"})]})]})]}),"\n",(0,s.jsx)(i.h3,{id:"parsed-evidence",children:"Parsed Evidence"}),"\n",(0,s.jsx)(i.p,{children:"Silver automatically parses evidence documents and returns structured data in four categories:"}),"\n",(0,s.jsxs)(i.table,{children:[(0,s.jsx)(i.thead,{children:(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.th,{children:"Field"}),(0,s.jsx)(i.th,{children:"Description"})]})}),(0,s.jsxs)(i.tbody,{children:[(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"receipts"})}),(0,s.jsx)(i.td,{children:"Purchase receipts with merchant, items, and totals"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"medical_invoices"})}),(0,s.jsx)(i.td,{children:"Medical invoices/EOBs with service-level detail"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"dependent_care_invoices"})}),(0,s.jsx)(i.td,{children:"Dependent care invoices with charges and payments"})]}),(0,s.jsxs)(i.tr,{children:[(0,s.jsx)(i.td,{children:(0,s.jsx)(i.code,{children:"statement_of_accounts"})}),(0,s.jsx)(i.td,{children:"Provider statements with ledger entries"})]})]})]}),"\n",(0,s.jsx)(i.p,{children:"Each category contains line-item detail with amounts (in cents), dates, eligibility determinations, and billing codes where applicable."}),"\n",(0,s.jsx)(i.h2,{id:"polling-vs-webhooks",children:"Polling vs. Webhooks"}),"\n",(0,s.jsx)(i.p,{children:"You can track adjudication status in two ways:"}),"\n",(0,s.jsxs)(i.ul,{children:["\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.strong,{children:"Polling"}

1)," \u2014 Periodically call ",(0,s.jsx)(i.code,{children:"GET /v1/claims?id={claim_id}"})," and check whether ",(0,s.jsx)(i.code,{children:"adjudication_results"})," is non-null. Simple but introduces latency."]}),"\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.strong,{children:"Webhooks"})," \u2014 Receive a real-time notification when adjudication completes. See ",(0,s.jsx)(i.a,{href:"/docs/administrator/webhooks/overview",children:"Webhooks Overview"}),"."]}),"\n"]}),"\n",(0,s.jsx)(i.admonition,{title:"Use webhooks for production",type:"tip",children:(0,s.jsx)(i.p,{children:"For production integrations, webhooks provide real-time updates without the overhead of polling. Use polling as a fallback for missed webhook deliveries."})})]})}function h(e={}){const{wrapper:i}={...(0,t.R)(),...e.components};return i?(0,s.jsx)(i,{...e,children:(0,s.jsx)(o,{...e})}):o(e)}}}]);