Tross
Demo dataBook a demo
UNITEDHEALTHCARE

Fetch claims

Search claims and retrieve matching details.

POSThttps://preview.ontross.com/api/integrations/uhc/fetch-claims
Request Fields
input.date_of_service
string
required
Service date, sent as both the first and last service date.
Example
"02/09/2026"
input.payer_id
string
required
UnitedHealthcare family payer ID, such as 39026 for UMR.
Example
"87726"
input.subscriber_id
string
required
Member number printed on the UnitedHealthcare card.
Example
"673018922"
input.date_of_birth
string
required
Subscriber's date of birth, paired with subscriber_id for member-ID search.
Example
"05/22/1984"
input.provider_id
string
required
Corporate MPIN matched against corpMpin in portal user permissions, not an NPI.
Example
"331879402"
input.tax_id_number
string
required
Billing practice's federal employer identification number, no dashes.
Example
"900741852"
auth_id
string
required
Saved connection to run this operation through, from the Authentication page. It decides which practice and login the call uses.
Example
"00000000-0000-4000-8000-000000000000"
Output Fields
claim_responses
array
One entry per claim matched by your search.
claim_responses[].claim_id
string
Portal claim number used to open claim details.
Example
"260400000001"
claim_responses[].claim_number
string
Payer's actual control number for this claim.
Example
"260400000001"
claim_responses[].claim_type
string
Claim form family, for example professional or institutional.
Example
"Professional"
claim_responses[].date_of_service
object
Service date, sent as both the first and last service date.
claim_responses[].date_of_service.year
integer
Four digit year, part of a split date value.
Example
2026
claim_responses[].date_of_service.month
integer
Month number, part of a split date value.
Example
2
claim_responses[].date_of_service.day
integer
Day of month, part of a split date value.
Example
9
claim_responses[].patient
object
Who received the service, name and birth date only.
claim_responses[].patient.name
object
Given and family designations for the person receiving services.
claim_responses[].patient.name.first_name
string
Given name as the payer spells it.
Example
"Avery"
claim_responses[].patient.name.last_name
string
Family name as the payer spells it.
Example
"Example"
claim_responses[].patient.name.middle_initial
string
Middle initial, never populated by UHC claims.
Example
"J"
claim_responses[].patient.name.suffix
string
Name suffix such as Junior, never populated by UHC claims.
Example
"Jr."
claim_responses[].patient.dob
object
Birth date parsed from patient details or the search result.
claim_responses[].patient.dob.year
integer
Four digit year, part of a split date value.
Example
2026
claim_responses[].patient.dob.month
integer
Month number, part of a split date value.
Example
2
claim_responses[].patient.dob.day
integer
Day of month, part of a split date value.
Example
9
claim_responses[].patient.gender
string
Sex on file with the payer, never populated by UHC.
Example
"F"
claim_responses[].patient.phone_number
string
Contact number, never populated by UHC claims.
Example
"202-555-0146"
claim_responses[].patient.other_phone_number
string
Alternate contact number, never populated by UHC claims.
Example
"202-555-0182"
claim_responses[].patient.address
string
Mailing location, never populated by this handler.
Example
"123 Example Lane, Springfield, IL 62704"
claim_responses[].patient.email_id
string
Patient or subscriber email, never populated by UHC claims.
Example
"avery.example@example.com"
claim_responses[].primary_insurance
object
Coverage the claim was billed under, subscriber and policy.
claim_responses[].primary_insurance.uuid
string
Internal coverage record id, never populated by UHC claims.
Example
"7c68d924-ef35-4b12-a936-28f1d084c5e7"
claim_responses[].primary_insurance.subscriber_id
string
Member number printed on the UnitedHealthcare card.
Example
"999000123"
claim_responses[].primary_insurance.subscriber
object
Policyholder for the coverage, name and member id.
claim_responses[].primary_insurance.subscriber.name
object
Policyholder's given and family designations from patient details.
claim_responses[].primary_insurance.subscriber.name.first_name
string
Given name as the payer spells it.
Example
"Avery"
claim_responses[].primary_insurance.subscriber.name.last_name
string
Family name as the payer spells it.
Example
"Example"
claim_responses[].primary_insurance.subscriber.name.middle_initial
string
Middle initial, never populated by UHC claims.
Example
"J"
claim_responses[].primary_insurance.subscriber.name.suffix
string
Name suffix such as Junior, never populated by UHC claims.
Example
"Jr."
claim_responses[].primary_insurance.subscriber.dob
object
Policyholder's birth date, never populated by this handler.
claim_responses[].primary_insurance.subscriber.dob.year
integer
Four digit year, part of a split date value.
Example
2026
claim_responses[].primary_insurance.subscriber.dob.month
integer
Month number, part of a split date value.
Example
2
claim_responses[].primary_insurance.subscriber.dob.day
integer
Day of month, part of a split date value.
Example
9
claim_responses[].primary_insurance.subscriber.gender
string
Sex on file with the payer, never populated by UHC.
Example
"F"
claim_responses[].primary_insurance.subscriber.phone_number
string
Contact number, never populated by UHC claims.
Example
"202-555-0146"
claim_responses[].primary_insurance.subscriber.other_phone_number
string
Alternate contact number, never populated by UHC claims.
Example
"202-555-0182"
claim_responses[].primary_insurance.subscriber.address
string
Mailing location, never populated despite available portal contact details.
Example
"123 Example Lane, Springfield, IL 62704"
claim_responses[].primary_insurance.subscriber.email_id
string
Patient or subscriber email, never populated by UHC claims.
Example
"avery.example@example.com"
claim_responses[].primary_insurance.subscriber.relationship_to_patient
string
How the subscriber relates to the patient, never populated.
Example
"Self"
claim_responses[].primary_insurance.subscriber.ehr_id
string
Subscriber's member id despite the name, not an EHR identifier.
Example
"999000123"
claim_responses[].primary_insurance.payor_name
string
Payer brand resolved from payer id, defaults to UnitedHealthcare.
Example
"UnitedHealthcare"
claim_responses[].primary_insurance.plan_name
string
Benefit plan name, never populated by UHC claims.
Example
"Choice Plus"
claim_responses[].primary_insurance.group_number
string
Policy number the member is covered under.
Example
"999001"
claim_responses[].primary_insurance.auth_number
string
Prior authorization number on the policy, never populated here.
Example
"A999000123"
claim_responses[].primary_insurance.name_for_portal_check
string
Internal portal matching name, never populated by UHC.
Example
"UnitedHealthcare Choice Plus"
claim_responses[].primary_insurance.portal_checks
string
Internal portal verification notes, never populated by UHC.
Example
"Coverage verified for 02/09/2026"
claim_responses[].primary_insurance.source
string
Where the coverage record came from, never populated by UHC.
Example
"Provider portal"
claim_responses[].primary_insurance.payor_ehr_id
string
Payer's id in your EHR, never populated by UHC.
Example
"PAY-999001"
claim_responses[].primary_insurance.metadata
object
Extra insurance record fields, never populated by UHC.
claim_responses[].primary_insurance.attachments
array
Insurance document attachments, never populated by UHC claim fetches.
claim_responses[].secondary_insurance
object
Other coverage, present only when the payer coordinates benefits.
claim_responses[].provider
object
Billing provider on the claim, name and tax id.
claim_responses[].provider.name
string
Corporate billing organization label returned in provider details.
Example
"Example Family Medicine"
claim_responses[].provider.npi
string
Billing provider's national provider identifier, never populated by UHC.
Example
"1999999984"
claim_responses[].provider.tax_id
string
Billing provider's tax identification number.
Example
"990001234"
claim_responses[].provider.type
string
Provider role on the claim, never populated by UHC.
Example
"Billing"
claim_responses[].line_items
array
One entry per service line on the claim.
claim_responses[].line_items[].date_of_service
object
Service date, sent as both the first and last service date.
claim_responses[].line_items[].date_of_service.year
integer
Four digit year, part of a split date value.
Example
2026
claim_responses[].line_items[].date_of_service.month
integer
Month number, part of a split date value.
Example
2
claim_responses[].line_items[].date_of_service.day
integer
Day of month, part of a split date value.
Example
9
claim_responses[].line_items[].line_number
integer
Position of this service line on the claim.
claim_responses[].line_items[].procedure_code
string
CPT or HCPCS code billed on this line.
Example
"99213"
claim_responses[].line_items[].modifiers
array
CPT modifiers on the service line, split from one string.
claim_responses[].line_items[].description
string
Billed service explanation, never populated by this handler.
Example
"Office or other outpatient visit for an established patient"
claim_responses[].line_items[].diagnosis_codes
array
Line diagnosis codes, always empty because UHC returns them in additional_properties.
claim_responses[].line_items[].diagnosis_descriptions
array
Diagnosis wording per line, never populated by UHC.
claim_responses[].line_items[].units
integer
How many units of the procedure were billed.
claim_responses[].line_items[].status
object
Service line adjudication details, never populated by this handler.
claim_responses[].line_items[].status.status
string
Current adjudication state returned in the claim search result.
Example
"Paid"
claim_responses[].line_items[].status.code
string
Claim adjudication identifier from the search result's claimStatus507 value.
Example
"1"
claim_responses[].line_items[].status.code_description
string
Payer wording for the claim status code.
Example
"For more detailed information, see remittance advice."
claim_responses[].line_items[].status.category_code
string
Payer status category code from the X12 claim status set.
Example
"F1"
claim_responses[].line_items[].status.category_description
string
Wording for the category code, never populated by UHC.
Example
"Finalized/Payment"
claim_responses[].line_items[].status.finalized_date
object
Date the payer finished adjudicating, split into parts.
claim_responses[].line_items[].status.finalized_date.year
integer
Four digit year, part of a split date value.
Example
2026
claim_responses[].line_items[].status.finalized_date.month
integer
Month number, part of a split date value.
Example
2
claim_responses[].line_items[].status.finalized_date.day
integer
Day of month, part of a split date value.
Example
9
claim_responses[].line_items[].status.comments
string
Portal actions available on this claim, not free text.
Example
"View claim details"
claim_responses[].line_items[].status.submission
object
Adjudication summary the payer returned for the claim.
claim_responses[].line_items[].status.remittance
object
Payment details from the payer, check and issue dates.
claim_responses[].line_items[].status.status_history
array
Each status the payer recorded, oldest first.
claim_responses[].line_items[].status.status_history[].status
string
Adjudication state recorded in a returned history entry.
Example
"Paid"
claim_responses[].line_items[].status.status_history[].date
string
Date the payer recorded this status change.
Example
"02/20/2026"
claim_responses[].line_items[].status.status_history[].description
string
Payer's explanatory wording for a recorded adjudication event.
Example
"Claim processed"
claim_responses[].line_items[].remarks
array
Adjustment and remark codes explaining the line's payment.
claim_responses[].line_items[].remarks[].code
string
Payer-returned adjustment or explanation identifier for a service line.
Example
"45"
claim_responses[].line_items[].remarks[].codeType
string
Which code set the remark came from, CARC or RARC.
Example
"CARC"
claim_responses[].line_items[].remarks[].description
string
Payer's explanatory wording for an adjustment or payment remark.
claim_responses[].line_items[].financial
object
Line level money: billed, allowed, paid, and member share.
claim_responses[].line_items[].financial.unit_charge
number
Charge per unit of service, never populated by UHC.
Example
125
claim_responses[].line_items[].financial.billed_amount
number
Charge the provider submitted, before plan discounts.
Example
250
claim_responses[].line_items[].financial.allowed_amount
number
Amount the plan allows for this line after contract discounts.
Example
180
claim_responses[].line_items[].financial.paid
number
Amount the plan actually paid on this line.
Example
124
claim_responses[].line_items[].financial.copay
number
Flat copay the member owes on this line.
Example
20
claim_responses[].line_items[].financial.deductible
number
Allowed amount applied to the member's deductible.
Example
0
claim_responses[].line_items[].financial.coinsurance
number
Member's percentage share of the allowed amount.
Example
36
claim_responses[].line_items[].financial.balance
number
Unpaid remainder on the line, never populated by UHC.
Example
56
claim_responses[].line_items[].financial.patient_responsibility
number
Total the member owes after benefits were applied.
Example
56
claim_responses[].status
object
Claim adjudication details, available actions, payments, and recorded history.
claim_responses[].status.status
string
Current adjudication state returned in the claim search result.
Example
"Paid"
claim_responses[].status.code
string
Claim adjudication identifier from the search result's claimStatus507 value.
Example
"1"
claim_responses[].status.code_description
string
Payer wording for the claim status code.
Example
"For more detailed information, see remittance advice."
claim_responses[].status.category_code
string
Payer status category code from the X12 claim status set.
Example
"F1"
claim_responses[].status.category_description
string
Wording for the category code, never populated by UHC.
Example
"Finalized/Payment"
claim_responses[].status.finalized_date
object
Date the payer finished adjudicating, split into parts.
claim_responses[].status.finalized_date.year
integer
Four digit year, part of a split date value.
Example
2026
claim_responses[].status.finalized_date.month
integer
Month number, part of a split date value.
Example
2
claim_responses[].status.finalized_date.day
integer
Day of month, part of a split date value.
Example
9
claim_responses[].status.comments
string
Portal actions available on this claim, not free text.
Example
"View claim details"
claim_responses[].status.submission
object
Adjudication summary the payer returned for the claim.
claim_responses[].status.remittance
object
Payment details from the payer, check and issue dates.
claim_responses[].status.status_history
array
Each status the payer recorded, oldest first.
claim_responses[].status.status_history[].status
string
Adjudication state recorded in a returned history entry.
Example
"Paid"
claim_responses[].status.status_history[].date
string
Date the payer recorded this status change.
Example
"02/20/2026"
claim_responses[].status.status_history[].description
string
Payer's explanatory wording for a recorded adjudication event.
Example
"Claim processed"
claim_responses[].financial_summary
object
Claim level totals: billed, paid, and patient responsibility.
claim_responses[].financial_summary.unit_charge
number
Charge per unit of service, never populated by UHC.
Example
125
claim_responses[].financial_summary.billed_amount
number
Charge the provider submitted, before plan discounts.
Example
250
claim_responses[].financial_summary.allowed_amount
number
Amount the plan allows for this line after contract discounts.
Example
180
claim_responses[].financial_summary.paid
number
Amount the plan actually paid on this line.
Example
124
claim_responses[].financial_summary.copay
number
Flat copay the member owes on this line.
Example
20
claim_responses[].financial_summary.deductible
number
Allowed amount applied to the member's deductible.
Example
0
claim_responses[].financial_summary.coinsurance
number
Member's percentage share of the allowed amount.
Example
36
claim_responses[].financial_summary.balance
number
Unpaid remainder on the line, never populated by UHC.
Example
56
claim_responses[].financial_summary.patient_responsibility
number
Total the member owes after benefits were applied.
Example
56
claim_responses[].raw_eob
object
Raw payer search row, not an explanation of benefits.
claim_responses[].additional_properties
object
Extra portal values like payer id, platform, and EOB links.
Code
curl --request POST \
  --url https://preview.ontross.com/api/integrations/uhc/fetch-claims \
  --header 'X-API-Key: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"input":{"date_of_service":"02/09/2026","payer_id":"87726","subscriber_id":"673018922","date_of_birth":"05/22/1984","provider_id":"331879402","tax_id_number":"900741852"},"auth_id":"auth_uuid_here"}'
Request BODY
{
  "input": {
    "date_of_service": "02/09/2026",
    "payer_id": "87726",
    "subscriber_id": "673018922",
    "date_of_birth": "05/22/1984",
    "provider_id": "331879402",
    "tax_id_number": "900741852"
  },
  "auth_id": "auth_uuid_here"
}
Response BODY
{
  "id": "string",
  "workflow_id": "string",
  "auth_id": "string",
  "status": "string",
  "input": {},
  "output": {
    "claim_responses": [
      {
        "claim_id": "260400000001",
        "claim_number": "260400000001",
        "claim_type": "Professional",
        "date_of_service": {
          "year": 2026,
          "month": 2,
          "day": 9
        },
        "patient": {
          "name": {
            "first_name": "Avery",
            "last_name": "Example",
            "middle_initial": "J",
            "suffix": "Jr."
          },
          "dob": {
            "year": 2026,
            "month": 2,
            "day": 9
          },
          "gender": "F",
          "phone_number": "202-555-0146",
          "other_phone_number": "202-555-0182",
          "address": "123 Example Lane, Springfield, IL 62704",
          "email_id": "avery.example@example.com"
        },
        "primary_insurance": {
          "uuid": "7c68d924-ef35-4b12-a936-28f1d084c5e7",
          "subscriber_id": "999000123",
          "subscriber": {
            "name": {
              "first_name": "Avery",
              "last_name": "Example",
              "middle_initial": "J",
              "suffix": "Jr."
            },
            "dob": {
              "year": 2026,
              "month": 2,
              "day": 9
            },
            "gender": "F",
            "phone_number": "202-555-0146",
            "other_phone_number": "202-555-0182",
            "address": "123 Example Lane, Springfield, IL 62704",
            "email_id": "avery.example@example.com",
            "relationship_to_patient": "Self",
            "ehr_id": "999000123"
          },
          "payor_name": "UnitedHealthcare",
          "plan_name": "Choice Plus",
          "group_number": "999001",
          "auth_number": "A999000123",
          "name_for_portal_check": "UnitedHealthcare Choice Plus",
          "portal_checks": "Coverage verified for 02/09/2026",
          "source": "Provider portal",
          "payor_ehr_id": "PAY-999001",
          "metadata": {},
          "attachments": [
            null
          ]
        },
        "secondary_insurance": {},
        "provider": {
          "name": "Example Family Medicine",
          "npi": "1999999984",
          "tax_id": "990001234",
          "type": "Billing"
        },
        "line_items": [
          {
            "date_of_service": {
              "year": 2026,
              "month": 2,
              "day": 9
            },
            "line_number": 0,
            "procedure_code": "99213",
            "modifiers": [
              "string"
            ],
            "description": "Office or other outpatient visit for an established patient",
            "diagnosis_codes": [
              "string"
            ],
            "diagnosis_descriptions": [
              "string"
            ],
            "units": 0,
            "status": {
              "status": "Paid",
              "code": "1",
              "code_description": "For more detailed information, see remittance advice.",
              "category_code": "F1",
              "category_description": "Finalized/Payment",
              "finalized_date": {
                "year": 2026,
                "month": 2,
                "day": 9
              },
              "comments": "View claim details",
              "submission": {},
              "remittance": {},
              "status_history": [
                {
                  "status": "Paid",
                  "date": "02/20/2026",
                  "description": "Claim processed"
                }
              ]
            },
            "remarks": [
              {
                "code": "45",
                "codeType": "CARC",
                "description": "Charge exceeds fee schedule/maximum allowable or contracted/legislated fee arrangement."
              }
            ],
            "financial": {
              "unit_charge": 125,
              "billed_amount": 250,
              "allowed_amount": 180,
              "paid": 124,
              "copay": 20,
              "deductible": 0,
              "coinsurance": 36,
              "balance": 56,
              "patient_responsibility": 56
            }
          }
        ],
        "status": {
          "status": "Paid",
          "code": "1",
          "code_description": "For more detailed information, see remittance advice.",
          "category_code": "F1",
          "category_description": "Finalized/Payment",
          "finalized_date": {
            "year": 2026,
            "month": 2,
            "day": 9
          },
          "comments": "View claim details",
          "submission": {},
          "remittance": {},
          "status_history": [
            {
              "status": "Paid",
              "date": "02/20/2026",
              "description": "Claim processed"
            }
          ]
        },
        "financial_summary": {
          "unit_charge": 125,
          "billed_amount": 250,
          "allowed_amount": 180,
          "paid": 124,
          "copay": 20,
          "deductible": 0,
          "coinsurance": 36,
          "balance": 56,
          "patient_responsibility": 56
        },
        "raw_eob": {},
        "additional_properties": {}
      }
    ]
  },
  "files": null,
  "created_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}