--- title: "Insurance Discovery" method: POST path: "/eligibility-checks/v1/insurance-discovery" tags: ["v1"] --- # Insurance Discovery `POST /eligibility-checks/v1/insurance-discovery` ## Request - Base URL: `https://pre-api.joincandidhealth.com` - URL: `https://pre-api.joincandidhealth.com/eligibility-checks/v1/insurance-discovery` - Auth: HTTP bearer Sends an insurance discovery check to find potential coverage matches for a patient through Stedi. Given patient demographics, this endpoint discovers what insurance coverages exist for the patient. We recommend using the coverages check_insurance_discovery_passthrough API, as it allows long-running discovery requests to complete. ## Request body - PreEncounterEligibilityChecksV1InsuranceDiscoveryRequest: An object representing the data for an insurance discovery request. - `provider` PreEncounterEligibilityChecksV1InsuranceDiscoveryProvider, required: Information about the provider requesting the insurance discovery check. - `npi` string, required: The provider's National Provider Identifier (NPI). - `subscriber` PreEncounterEligibilityChecksV1InsuranceDiscoverySubscriber, required: Demographic information for the patient when they are the health plan subscriber. Providing as much information as possible improves the probability of finding matching coverage. SSN and address (especially zip code) are strongly recommended. - `first_name` string, required: The subscriber's first name. - `last_name` string, required: The subscriber's last name. - `middle_name` string: The subscriber's middle name or initial. - `date_of_birth` string: The subscriber's date of birth, formatted as YYYYMMDD. - `ssn` string: The subscriber's Social Security Number (SSN). Full SSN is preferred, but even the last 4 digits can help. - `gender` 'M' | 'F' - `address` PreEncounterEligibilityChecksV1InsuranceDiscoveryAddress: The patient's address. Providing a zip code improves the probability of finding matching coverage. - `address_1` string - `address_2` string - `city` string - `state` string - `postal_code` string - `country_code` string - `dependent` PreEncounterEligibilityChecksV1InsuranceDiscoveryDependent: Demographic information for the patient when they are a dependent on a health plan. If you only have the dependent's information, identify them in the subscriber object instead and leave this empty. - `first_name` string, required: The dependent's first name. - `last_name` string, required: The dependent's last name. - `middle_name` string: The dependent's middle name or initial. - `date_of_birth` string: The dependent's date of birth, formatted as YYYYMMDD. - `ssn` string: The dependent's Social Security Number (SSN). - `gender` 'M' | 'F' - `address` PreEncounterEligibilityChecksV1InsuranceDiscoveryAddress: The patient's address. Providing a zip code improves the probability of finding matching coverage. - `address_1` string - `address_2` string - `city` string - `state` string - `postal_code` string - `country_code` string - `encounter` PreEncounterEligibilityChecksV1InsuranceDiscoveryEncounter: The date range for the service. If not specified, Stedi defaults to the current date. You can specify either a single date_of_service or a beginning_date_of_service and end_date_of_service. - `date_of_service` string: A single date of service, formatted as YYYYMMDD. - `beginning_date_of_service` string: The beginning date of service, formatted as YYYYMMDD. - `end_date_of_service` string: The end date of service, formatted as YYYYMMDD. ## Response `200` Response with status 200 - PreEncounterEligibilityChecksV1InsuranceDiscoveryResponse: An object representing the data for an insurance discovery response. - `discovery_id` string: A unique ID for this insurance discovery check. - `status` 'PENDING' | 'COMPLETE' | 'ERROR' | 'UNKNOWN': The status of the insurance discovery check. - `items` unknown[]: An array of potential coverage matches for the patient. Only populated when status is COMPLETE. Each item is a raw passthrough of Stedi's deeply nested coverage-match object (provider, subscriber, payer, plan, and benefits details). - unknown - `parsed_items` PreEncounterEligibilityChecksV1ParsedDiscoveryItem[] - `eligibility_status` 'ACTIVE' | 'INACTIVE' | 'UNKNOWN', required: enum to represent the status of a patient's coverage - `plan_metadata` PreEncounterCoveragesV1PlanMetadata - `payer_name` string - `insurance_type` string - `insurance_type_code` string - `plan_name` string - `member_id` string - `group_number` string - `start_date` string, date - `end_date` string, date - `plan_dates` PreEncounterCoveragesV1PlanDate[] - `start_date` string, date, required - `end_date` string, date - `field_name` string, required - `subscriber` PreEncounterCoveragesV1ExpandedMemberInfo - `member_id` string - `group_number` string - `first_name` string - `middle_name` string - `last_name` string - `date_of_birth` string - `gender` string - `address` PreEncounterCoveragesV1Address - `address1` string - `address2` string - `city` string - `state` string - `postal_code` string - `country_code` string - `country_sub_division_code` string - `dependent` PreEncounterCoveragesV1ExpandedMemberInfo - `member_id` string - `group_number` string - `first_name` string - `middle_name` string - `last_name` string - `date_of_birth` string - `gender` string - `address` PreEncounterCoveragesV1Address - `address1` string - `address2` string - `city` string - `state` string - `postal_code` string - `country_code` string - `country_sub_division_code` string - `trading_partner` string: The payer's own identifier as returned on the Stedi eligibility response (271) `tradingPartnerServiceId`. Reflects the payer's internal concept of their ID, which may differ from the ID Stedi routes on. - `benefits` PreEncounterCoveragesV1CoverageBenefits - `plan_coverage` PreEncounterCoveragesV1PlanCoverage - `in_network` PreEncounterCoveragesV1PlanCoverageDetails - `deductible` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `deductible_contract` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `deductible_remaining` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `deductible_year_to_date` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max_contract` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max_remaining` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max_year_to_date` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `additional_notes` string - `in_network_flat` PreEncounterCoveragesV1CoverageDetails[] - `type` 'DEDUCTIBLE' | 'DEDUCTIBLE_CONTRACT' | 'DEDUCTIBLE_REMAINING' | 'DEDUCTIBLE_YEAR_TO_DATE' | 'OOP_MAX' | 'OOP_MAX_CONTRACT' | 'OOP_MAX_REMAINING' | 'OOP_MAX_YEAR_TO_DATE' | 'COPAY' | 'COINSURANCE' | 'NON_COVERED' | 'LIMITATION', required - `coverageLevel` 'EMPLOYEE_AND_CHILDREN' | 'EMPLOYEE_ONLY' | 'EMPLOYEE_AND_SPOUSE' | 'FAMILY' | 'INDIVIDUAL', required - `unit` 'PERCENT' | 'CURRENCY' | 'COUNT', required - `value` number, double, required - `additional_notes` string - `out_of_network` PreEncounterCoveragesV1PlanCoverageDetails - `deductible` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `deductible_contract` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `deductible_remaining` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `deductible_year_to_date` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max_contract` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max_remaining` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `oop_max_year_to_date` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `additional_notes` string - `out_of_network_flat` PreEncounterCoveragesV1CoverageDetails[] - `type` 'DEDUCTIBLE' | 'DEDUCTIBLE_CONTRACT' | 'DEDUCTIBLE_REMAINING' | 'DEDUCTIBLE_YEAR_TO_DATE' | 'OOP_MAX' | 'OOP_MAX_CONTRACT' | 'OOP_MAX_REMAINING' | 'OOP_MAX_YEAR_TO_DATE' | 'COPAY' | 'COINSURANCE' | 'NON_COVERED' | 'LIMITATION', required - `coverageLevel` 'EMPLOYEE_AND_CHILDREN' | 'EMPLOYEE_ONLY' | 'EMPLOYEE_AND_SPOUSE' | 'FAMILY' | 'INDIVIDUAL', required - `unit` 'PERCENT' | 'CURRENCY' | 'COUNT', required - `value` number, double, required - `additional_notes` string - `service_specific_coverage` PreEncounterCoveragesV1ServiceCoverage[] - `service_code` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | '14' | '15' | '16' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '25' | '26' | '27' | '28' | '30' | '32' | '33' | '34' | '35' | '36' | '37' | '38' | '39' | '40' | '41' | '42' | '43' | '44' | '45' | '46' | '47' | '48' | '49' | '50' | '51' | '52' | '53' | '54' | '55' | '56' | '57' | '58' | '59' | '60' | '61' | '62' | '63' | '64' | '65' | '66' | '67' | '68' | '69' | '70' | '71' | '72' | '73' | '74' | '75' | '76' | '77' | '78' | '79' | '80' | '81' | '82' | '83' | '84' | '85' | '86' | '87' | '88' | '89' | '90' | '91' | '92' | '93' | '94' | '95' | '96' | '97' | '98' | '99' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'A9' | 'AA' | 'AB' | 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AH' | 'AI' | 'AJ' | 'AK' | 'AL' | 'AM' | 'AN' | 'AO' | 'AQ' | 'AR' | 'B1' | 'B2' | 'B3' | 'BA' | 'BB' | 'BC' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BK' | 'BL' | 'BM' | 'BN' | 'BP' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BU' | 'BV' | 'BW' | 'BX' | 'BY' | 'BZ' | 'C1' | 'CA' | 'CB' | 'CC' | 'CD' | 'CE' | 'CF' | 'CG' | 'CH' | 'CI' | 'CJ' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CP' | 'CQ' | 'DG' | 'DM' | 'DS' | 'GF' | 'GN' | 'GY' | 'IC' | 'MH' | 'NI' | 'ON' | 'PT' | 'PU' | 'RN' | 'RT' | 'TC' | 'TN' | 'UC', required: Code identifying the type of service or benefit within a specific insurance policy (X12 008010 Element 1365) - `in_network` PreEncounterCoveragesV1ServiceCoverageDetails - `copay` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `coinsurance` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `visits` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `visits_remaining` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `additional_notes` string - `in_network_flat` PreEncounterCoveragesV1CoverageDetails[] - `type` 'DEDUCTIBLE' | 'DEDUCTIBLE_CONTRACT' | 'DEDUCTIBLE_REMAINING' | 'DEDUCTIBLE_YEAR_TO_DATE' | 'OOP_MAX' | 'OOP_MAX_CONTRACT' | 'OOP_MAX_REMAINING' | 'OOP_MAX_YEAR_TO_DATE' | 'COPAY' | 'COINSURANCE' | 'NON_COVERED' | 'LIMITATION', required - `coverageLevel` 'EMPLOYEE_AND_CHILDREN' | 'EMPLOYEE_ONLY' | 'EMPLOYEE_AND_SPOUSE' | 'FAMILY' | 'INDIVIDUAL', required - `unit` 'PERCENT' | 'CURRENCY' | 'COUNT', required - `value` number, double, required - `additional_notes` string - `out_of_network` PreEncounterCoveragesV1ServiceCoverageDetails - `copay` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `coinsurance` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `visits` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `visits_remaining` PreEncounterCoveragesV1CoverageValue - `family` number, double - `individual` number, double - `employeeAndSpouse` number, double - `employeeAndChildren` number, double - `additional_notes` string - `out_of_network_flat` PreEncounterCoveragesV1CoverageDetails[] - `type` 'DEDUCTIBLE' | 'DEDUCTIBLE_CONTRACT' | 'DEDUCTIBLE_REMAINING' | 'DEDUCTIBLE_YEAR_TO_DATE' | 'OOP_MAX' | 'OOP_MAX_CONTRACT' | 'OOP_MAX_REMAINING' | 'OOP_MAX_YEAR_TO_DATE' | 'COPAY' | 'COINSURANCE' | 'NON_COVERED' | 'LIMITATION', required - `coverageLevel` 'EMPLOYEE_AND_CHILDREN' | 'EMPLOYEE_ONLY' | 'EMPLOYEE_AND_SPOUSE' | 'FAMILY' | 'INDIVIDUAL', required - `unit` 'PERCENT' | 'CURRENCY' | 'COUNT', required - `value` number, double, required - `additional_notes` string - `benefits_related_entities` PreEncounterCoveragesV1BenefitsRelatedEntity[] - `entityIdentifier` string - `entityType` string - `entityName` string - `contactInformation` PreEncounterCoveragesV1RelatedEntityContact[] - `mode` string - `value` string - `serviceTypeCodes` PreEncounterCoveragesV1ServiceTypeCode[] - `non_covered_details` PreEncounterCoveragesV1NonCoveredDetail[] - `type` 'DEDUCTIBLE' | 'DEDUCTIBLE_CONTRACT' | 'DEDUCTIBLE_REMAINING' | 'DEDUCTIBLE_YEAR_TO_DATE' | 'OOP_MAX' | 'OOP_MAX_CONTRACT' | 'OOP_MAX_REMAINING' | 'OOP_MAX_YEAR_TO_DATE' | 'COPAY' | 'COINSURANCE' | 'NON_COVERED' | 'LIMITATION', required - `coverageLevel` 'EMPLOYEE_AND_CHILDREN' | 'EMPLOYEE_ONLY' | 'EMPLOYEE_AND_SPOUSE' | 'FAMILY' | 'INDIVIDUAL', required - `unit` 'PERCENT' | 'CURRENCY' | 'COUNT', required - `value` number, double, required - `additional_notes` string - `service_type_codes` PreEncounterCoveragesV1ServiceTypeCode[] - `notes` string - `autoUpdatedEligibilityCheckId` string - `confidence` PreEncounterEligibilityChecksV1Confidence - `level` 'REVIEW_NEEDED' | 'HIGH' - `reason` string - `coverages_found` integer: The number of potential coverage matches found. 0 if no matching coverage was found. - `errors` PreEncounterEligibilityChecksV1EligibilityCheckErrorDetails[] - `field?` string - `description?` string - `location?` string - `possibleResolutions?` string - `code?` string - `followupAction?` string ## Changes - **2026-10-02** `7fd881bab7b6`: 1 info - added the optional property `parsed_items` to the response with the `200` status - **2026-09-24** `4074901c170f`: 2 warning - added the new `ERROR` enum value to the `status` response property for the response status `200` - added the new `UNKNOWN` enum value to the `status` response property for the response status `200` - **2026-09-17** `24b2d80d577a`: 4 breaking, 1 warning, 8 info - added the new required request property `provider` - added the new required request property `subscriber` - the request's body type changed from no type to `object` - the response's body type changed from no type to `object` for status `200` - …9 more - **2026-09-12** `3a81ee81d4ed`: 1 info - api operation id `insurance-discovery` removed and replaced with `v1_insurance-discovery` [Operation history](https://skmtc.dev/joincandidhealth/apis/api-reference/changes/eligibility-checks/v1/insurance-discovery/post.md) --- [API](https://skmtc.dev/joincandidhealth/apis/api-reference.md) - [All operations](https://skmtc.dev/joincandidhealth/apis/api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/joincandidhealth/apis/api-reference/revisions/d8b0a61873e2?raw)