These endpoints require authentication. Please see authentication for more information.

​
Overview

In this 5 minute quickstart, we will walk through how to submit benefits requests. Each of these requests will trigger a call to the specified insurance payor, and when completed, you’ll receive the results at any webhooks you’ve set up.

​
Create an Inquiry

Let’s walk through an example of how to create an inquiry using a POST request. You will need to provide the necessary information to verify the patient’s benefits on behalf of the provider including the procedure codes you are interested in checking. Make sure to also include one or more benefits_query to specify the type of information that’s needed. For instance, in addition to CODE_LOOKUP_BENEFITS which retrieves just the copay and coinsurance for the procedure codes, you can also include CODE_LOOKUP_PRIOR_AUTH to check if a prior authorization is required for the procedure codes and/or CODE_LOOKUP_FREQUENCIES to check the frequency limitations for the procedure codes. Some basic plan information (e.g. plan type, effective date, termination date, etc.) will also be included in the response by default, but you’ll need to include DEDUCTIBLES_AND_MAXIMUMS to get the deductibles and maximums.
In addition to procedure codes, we can also include custom bundles or follow up questions for your procedure as part of our white-glove API onboarding. Contact us for details. 
curl -u [PROJECT_ID]:[API_KEY] --request POST "https://healthharbor.co/api/v0/medical/inquiries" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "BENEFITS",
    "desired_completion_date": "08-25-2024",
    "patient_name": "Alex Martin",
    "dob": "01-31-2023",
    "member_id": "567891234",
    "group_id": "678123",
    "insurance": "UNITED_HEALTHCARE",
    "insurance_in_network": true,
    "npi": "1245319599",
    "practice_billing_address": "123 Main St, New York, NY 10001",
    "tax_id": "123456789",
    "external_id": "provider_123",
    "benefits_codes": [
      "94625",
      "94626"
    ],
    "benefits_query": [
      "CODE_LOOKUP_BENEFITS"
    ],
    "is_specialist": true,
    "place_of_service": "telehealth"
}'
Successful creations will return this response. 
{
  "success": true,
  "inquiry_id": "7d98c8a4-4b17-4e9b-b2f6-6131df874b8b",
}

​
Retrieve an Inquiry

Now that you’ve made a medical inquiry, you can check the results with a GET request and the inquiry_id returned when you created an inquiry. This is an alternative to receiving the results at your webhook which will be sent automatically once the results are complete. 
curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/medical/inquiries/722b06d8-1855-402b-9916-bfa450cc1572"
Here is a sample response.
JSON
{
  "id": "722b06d8-1855-402b-9916-bfa450cc1572",
  "status": "SUCCESS",
  "creation_ts": "2020-01-01T00:00:00.000000Z",
  "summary": "Benefits retrieved successfully.",
  "results": {
    "call_details": {
      "call_end_time": "2024-03-01T06:00:00.0000Z",
      "representative_name": "Deborah M",
      "reference_number": "2812129",
      "call_recording_url": "https://www.google.com/voice_recording.wav"
    },
    "plan_information": {
      "is_active": true,
      "plan_type": "PPO",
      "effective_date": "10-01-2020",
      "termination_date": "10-31-2021",
      "is_calendar_year_plan": true,
      "is_provider_in_network": true,
      "is_primary_insurance": true
    },
    "maximums": {
      "individual_deductible": "100",
      "individual_deductible_used": "80",
      "individual_out_of_pocket_maximum": "1000",
      "individual_out_of_pocket_maximum_used": "800",
      "family_deductible": "200",
      "family_deductible_used": "100",
      "family_out_of_pocket_maximum": "2000",
      "family_out_of_pocket_maximum_used": "1000"
    },
    "procedure_codes": [
      [
        {
          "procedure_code": "94625",
          "procedure_name": "Pulmonary Rehabilitation Coverage"
        },
        {
          "is_covered": true,
          "is_deductible_waived": true,
          "copay_amount": "0.00",
          "coinsurance_percentage": "20",
          "more_info": "Diagnosis of medium to severe COPD is required for coverage."
        }
      ],
      [
        {
          "procedure_code": "94626",
          "procedure_name": "Pulmonary Rehabilitation Coverage"
        },
        {
          "is_covered": true,
          "is_deductible_waived": false,
          "copay_amount": "20.00",
          "coinsurance_percentage": "0",
          "more_info": "Diagnosis of medium to severe COPD is required for coverage."
        }
      ]
    ]
  },
  "request": {
    "type": "BENEFITS",
    "desired_completion_date": "08-25-2024",
    "patient_name": "Alex Martin",
    "dob": "01-31-2023",
    "member_id": "567891234",
    "group_id": "678123",
    "insurance": "UNITED_HEALTHCARE",
    "insurance_in_network": true,
    "npi": "1245319599",
    "practice_billing_address": "123 Main St, New York, NY 10001",
    "tax_id": "123456789",
    "external_id": "provider_123",
    "benefits_codes": [
      "94625",
      "94626"
    ],
    "benefits_query": [
      "CODE_LOOKUP_BENEFITS"
    ],
    "is_specialist": true,
    "place_of_service": "telehealth"
  }
}
Alternatively, you can instead retrieve information on all the inquiries you’ve submitted. This can be filtered by the external_id you provided when you created the inquiry. Each inquiry will be returned in the array. 
curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/medical/inquiries"
You have successfully created a medical inquiry and retrieved the results! For further details on the parameters and fields in the requests and the responses, please refer to our Detailed API Reference.