Get Eligibility History¶

Retrieve the most recent eligibility enquiry record for a patient and insurance number. Returns the latest entry from the enquiry history, including all benefit details captured during either an automated check or a manual capture.

Endpoint¶

GET /apis/eligibility/v2/insurance/eligibility/search

Query Parameters¶

Parameter	Type	Required	Description
`patient_id`	integer	Yes	The unique identifier of the patient
`insurance_number`	string	Yes	The insurance member/policy number
`channel_id`	string	No	Filter by enquiry channel. One of `CLAIM_MD`, `PVERIFY`, `SPRY`, `MANUAL_CAPTURE`, `EDI`. Omit to return the most recent across all channels.

Request¶

curl --location '{base_url}/apis/eligibility/v2/insurance/eligibility/search?patient_id=12345&insurance_number=W585965926&channel_id=MANUAL_CAPTURE' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "code": 2000,
  "data": {
    "content": [
      {
        "eligibility_enquiry_id": "elig-abc123xyz",
        "insurance_number": "W585965926",
        "payer_id": "00010",
        "payer_name": "Blue Cross Blue Shield",
        "patient_first_name": "Jane",
        "patient_last_name": "Doe",
        "patient_dob": "1985-04-15",
        "patient_relation": "SELF",
        "provider_npi": "1234567890",
        "provider_first_name": "John",
        "provider_last_name": "Smith",
        "date_of_service": "2025-05-19",
        "service_code": "PT",
        "place_of_service": "11",
        "patient_id": 12345,
        "clinic_id": 89,
        "organisation_id": 67,
        "timestamp": "2025-05-19T10:30:00",
        "channel_id": "MANUAL_CAPTURE",
        "status": "ACTIVE",
        "response": {
          "enquiry_id": "elig-abc123xyz",
          "channel_id": "MANUAL_CAPTURE",
          "date_of_service": "2025-05-19",
          "service_code": "PT",
          "place_of_service": "11",
          "prior_authorization_required": "N",
          "service_eligibility_coverage": true,
          "non_covered_services_flag": false,
          "in_plan_network": true,
          "plan_details": {
            "payer_id": "00010",
            "payer_name": "Blue Cross Blue Shield",
            "insurance_number": "W585965926",
            "plan_start_date": "2025-01-01",
            "plan_end_date": "2025-12-31",
            "plan_name": "PPO Gold",
            "plan_type": "PPO",
            "active": true
          },
          "subscriber_details": {
            "first_name": "Jane",
            "last_name": "Doe",
            "date_of_birth": "1985-04-15",
            "sex": "FEMALE",
            "city": "Chicago",
            "state": "IL",
            "zip_code": "60601",
            "address_line": "123 Main St"
          },
          "in_network": {
            "individual_deductible_year": 1500.00,
            "individual_deductible_remaining": 800.00,
            "family_deductible_year": 3000.00,
            "family_deductible_remaining": 2000.00,
            "individual_out_of_pocket_year": 5000.00,
            "individual_out_of_pocket_remaining": 4200.00,
            "family_out_of_pocket_year": 10000.00,
            "family_out_of_pocket_remaining": 9000.00,
            "co_insurance": 20.0,
            "co_pay": 30.00,
            "limitation": {
              "no_of_total_visits": 30,
              "no_of_visits_remaining": 28,
              "amount_remaining": 20.0
            }
          },
          "out_of_network": {
            "individual_deductible_year": 3000.00,
            "individual_deductible_remaining": 2500.00,
            "family_deductible_year": 6000.00,
            "family_deductible_remaining": 5500.00,
            "individual_out_of_pocket_year": 8000.00,
            "individual_out_of_pocket_remaining": 7500.00,
            "family_out_of_pocket_year": 16000.00,
            "family_out_of_pocket_remaining": 15000.00,
            "co_insurance": 40.0,
            "co_pay": 60.00,
            "limitation": {
              "no_of_total_visits": 20,
              "no_of_visits_remaining": 18,
              "amount_remaining": 40.0
            }
          },
          "in_plan_network_confidence_score": 0.95
        },
        "errors": []
      }
    ],
    "total_elements": 1,
    "total_pages": 1,
    "page": 0,
    "size": 10
  },
  "message": "Success"
}

Response Fields¶

Root Level¶

Field	Type	Description
`code`	integer	Response code. `2000` indicates success.
`data`	object	Paginated result container
`message`	string	Human-readable status message

Paged Data¶

Field	Type	Description
`content`	array	List of eligibility enquiry records
`total_elements`	integer	Total number of matching records
`total_pages`	integer	Total number of pages
`page`	integer	Current page index (0-based)
`size`	integer	Page size

Eligibility Enquiry Record (`content[]`)¶

Field	Type	Description
`eligibility_enquiry_id`	string	Unique identifier for this enquiry
`insurance_number`	string	Insurance member/policy number
`payer_id`	string	Payer identifier
`payer_name`	string	Insurance payer name
`patient_first_name`	string	Patient first name
`patient_last_name`	string	Patient last name
`patient_dob`	string (date)	Patient date of birth (`YYYY-MM-DD`)
`patient_relation`	string	Subscriber relationship (`SELF`, `SPOUSE`, `CHILD`, etc.)
`provider_npi`	string	Rendering provider NPI
`provider_first_name`	string	Provider first name
`provider_last_name`	string	Provider last name
`date_of_service`	string (date)	Date of service used for the check
`service_code`	string	Service type code (e.g. `PT`, `30`, `AD`)
`place_of_service`	string	Place of service code (e.g. `11` for office)
`patient_id`	integer	Patient identifier
`clinic_id`	integer	Clinic identifier
`organisation_id`	integer	Organisation identifier
`timestamp`	string	Datetime the enquiry was recorded
`channel_id`	string	Channel used for the check (see Channel IDs)
`status`	string	Enquiry status
`response`	object	Full eligibility benefit details (see Eligibility Response)
`errors`	array	List of errors if the check failed; empty on success

Eligibility Response¶

Field	Type	Description
`enquiry_id`	string	Enquiry identifier (matches parent record)
`channel_id`	string	Channel used for the check
`date_of_service`	string (date)	Date of service
`service_code`	string	Service type code
`place_of_service`	string	Place of service code
`prior_authorization_required`	string	Whether prior auth is required (`Y`, `N`, `U` = unknown)
`service_eligibility_coverage`	boolean	Whether the service is covered
`non_covered_services_flag`	boolean	Whether non-covered services were found
`in_plan_network`	boolean	Whether the provider is in-network
`plan_details`	object	Plan and payer information (see Plan Details)
`subscriber_details`	object	Subscriber demographic information (see Subscriber Details)
`in_network`	object	In-network benefit amounts (see Network Benefits)
`out_of_network`	object	Out-of-network benefit amounts (same structure as `in_network`)
`in_plan_network_confidence_score`	number	Confidence score for in-network determination (0.0–1.0)

Plan Details¶

Field	Type	Description
`payer_id`	string	Payer identifier
`payer_name`	string	Insurance payer name
`insurance_number`	string	Member/policy number
`plan_name`	string	Plan name
`plan_type`	string	Plan type (e.g. `PPO`, `HMO`)
`plan_start_date`	string (date)	Plan coverage start date
`plan_end_date`	string (date)	Plan coverage end date
`group_name`	string	Group plan name
`group_number`	string	Group plan number
`active`	boolean	Whether the plan is currently active

Subscriber Details¶

Field	Type	Description
`first_name`	string	Subscriber first name
`last_name`	string	Subscriber last name
`middle_name`	string	Subscriber middle name
`sex`	string	Subscriber sex
`date_of_birth`	string (date)	Subscriber date of birth
`address_line`	string	Street address
`city`	string	City
`state`	string	State code
`zip_code`	string	ZIP/postal code

Network Benefits¶

Applies to both in_network and out_of_network.

Field	Type	Description
`individual_deductible_year`	number	Annual individual deductible amount
`individual_deductible_remaining`	number	Remaining individual deductible
`family_deductible_year`	number	Annual family deductible amount
`family_deductible_remaining`	number	Remaining family deductible
`individual_out_of_pocket_year`	number	Annual individual out-of-pocket maximum
`individual_out_of_pocket_remaining`	number	Remaining individual out-of-pocket
`family_out_of_pocket_year`	number	Annual family out-of-pocket maximum
`family_out_of_pocket_remaining`	number	Remaining family out-of-pocket
`co_insurance`	number	Co-insurance percentage
`co_pay`	number	Copay amount in dollars
`limitation`	object	Visit/amount limits (see Limitation)

Limitation¶

Field	Type	Description
`no_of_total_visits`	integer	Total authorized visits for the benefit period
`no_of_visits_remaining`	integer	Remaining visits in the benefit period
`amount_remaining`	number	Remaining benefit amount

Error Response¶

Code: 400 Bad Request

{
  "code": 4000,
  "message": "Invalid patient_id or insurance_number",
  "data": null
}

Notes¶

Channel IDs¶

Value	Description
`CLAIM_MD`	Automated check via ClaimMD clearinghouse
`PVERIFY`	Automated check via pVerify
`SPRY`	Automated check via Spry's internal service
`MANUAL_CAPTURE`	Manually entered eligibility by staff
`EDI`	Check via EDI 270/271 transaction

When channel_id=MANUAL_CAPTURE is passed, the endpoint returns the most recent manually entered eligibility record for the patient and insurance number.
The response content array is ordered by timestamp descending; content[0] is always the most recent record.
Returns null (empty content) if no eligibility record exists for the given parameters.