> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healthharbor.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Medical Benefits Quickstart

<Warning>
  These endpoints require authentication. Please see
  [authentication](../authentication) for more information.
</Warning>

### 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.

<Note> 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](mailto:alan@healthharbor.co) for details. </Note>

<CodeGroup>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = 'https://healthharbor.co/api/v0/medical/inquiries'
  payload = {
    "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"
  }
  response = requests.post(
    url = url,
    data=json.dumps(payload),
    auth=([PROJECT_ID], [API_KEY])
  )
  ```
</CodeGroup>

Successful creations will return this response.

<CodeGroup>
  ```json JSON theme={null}
  {
    "success": true,
    "inquiry_id": "7d98c8a4-4b17-4e9b-b2f6-6131df874b8b",
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/medical/inquiries/722b06d8-1855-402b-9916-bfa450cc1572"
  ```

  ```python Python theme={null}
  import requests

  url = "https://healthharbor.co/api/v0/medical/inquiries/722b06d8-1855-402b-9916-bfa450cc1572"
  response = requests.get(
    url=url,
    auth=([PROJECT_ID], [API_KEY])
  )
  ```
</CodeGroup>

Here is a sample response.

```json JSON theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/medical/inquiries"
  ```

  ```python Python theme={null}
  import requests

  url = 'https://healthharbor.co/api/v0/medical/inquiries'
  response = requests.get(
    url=url,
    auth=([PROJECT_ID], [API_KEY])
  )
  ```
</CodeGroup>

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](endpoint/create-medical-inquiry).