# Additional Options
Source: https://docs.healthharbor.co/api-reference/additional-options
### Optional Settings
#### External ID
In addition to patient and practice information needed to complete an inquiry, each operation also supports an optional `external_id` parameter which you can define and pass in with your creation request. This is useful for tracking a specific subgroup of inquiries. For instance, you can assign a unique external id to all inquiries for a specific provider on your platform.
This will allow you to retrieve only the information for that provider and update that information.
#### Custom Benefits Queries
We can create customized benefits queries for you so they you can specify custom follow-up questions or specific information outside the scope of a typical benefits request. For example, we could ask if two procedures can be performed on the same date of service.
Contact [our team](mailto:alan@healthharbor.co), if you'd like to set one up.
# Dental Quickstart
Source: https://docs.healthharbor.co/api-reference/dental-quickstart
These endpoints require authentication. Please see
[authentication](../authentication) for more information.
### Overview
In this quickstart, we will retrieve benefits for a patient for a dental provider. We will walk through the requests needed to create an inquiry and retrieve the results.
### Create an Inquiry
First, we will send a POST request to create a dental inquiry. This provides the information necessary to check the patient's benefits on behalf of the dental provider.
The first character in the CDT codes (D) can be optionally omitted when passed
into `benefits_codes`.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request POST "https://healthharbor.co/api/v0/dental/inquiries" \
--header 'Content-Type: application/json' \
--data '{
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2000",
"member_id": "123456789",
"group_id": "123456",
"insurance": "UNITED_HEALTHCARE",
"insurance_in_network": true,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "provider_123",
"benefits_codes": [
"D0120",
"D4240"
],
"benefits_query": [
"CODE_LOOKUP_BENEFITS"
],
"is_specialist": true
}'
```
```python Python theme={null}
import requests
import json
url = 'https://healthharbor.co/api/v0/dental/inquiries'
payload = {
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2000",
"member_id": "123456789",
"group_id": "123456",
"insurance": "UNITED_HEALTHCARE",
"insurance_in_network": True,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "provider_123",
"benefits_codes": [
"D0120",
"D4240"
],
"benefits_query": [
"CODE_LOOKUP_BENEFITS",
],
"is_specialist": True
}
response = requests.post(
url = url,
data=json.dumps(payload),
auth=([PROJECT_ID], [API_KEY])
)
```
If the request has been successfully created, we will receive a response like this:
```json JSON theme={null}
{
"success": true,
"inquiry_id": "7d98c8a4-4b17-4e9b-b2f6-6131df874b8b",
}
```
### Retrieve an Inquiry
Now that we've made a dental inquiry, we can check on the results using the `inquiry_id` received during inquiry creation.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/dental/inquiries/722b06d8-1855-402b-9916-bfa450cc1572"
```
```python Python theme={null}
import requests
url = 'https://healthharbor.co/api/v0/dental/inquiries/722b06d8-1855-402b-9916-bfa450cc1572'
response = requests.get(
url=url,
auth=([PROJECT_ID], [API_KEY])
)
```
Here is a sample response.
```json JSON theme={null}
[
{
"id": "722b06d8-1855-402b-9916-bfa450cc1572",
"status": "SUCCESS",
"creation_ts": "2023-08-01T00:00:00.000000Z",
"summary": "Benefits retrieved successfully.",
"results": {
"call_details": [
{
"call_end_time": "2023-08-01T06:00:00.0000Z",
"representative_name": "Deborah M",
"reference_number": "2812129",
"call_recording_url": "https://www.google.com/voice_recording.wav"
}
],
"procedure_codes": [
[
{
"procedure_code": "D0120",
"procedure_name": "Exam"
},
{
"is_covered": true,
"is_prior_auth_required": false,
"coverage_percentage": 100.0,
"more_info": ""
}
],
[
{
"procedure_code": "D4240",
"procedure_name": "Gingival Flap Procedure"
},
{
"is_covered": true,
"is_prior_auth_required": true,
"prior_auth_info": "Call United Healthcare at 555-123-1234",
"coverage_percentage": 50.0,
"more_info": ""
}
]
]
},
"request": {
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2020",
"member_id": "123456789",
"group_id": "123456",
"insurance_in_network": true,
"insurance": "UNITED_HEALTHCARE",
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "provider_123",
"benefits_codes": ["D0120", "D4240"],
"benefits_query": ["CODE_LOOKUP_BENEFITS"],
"is_specialist": true
}
}
]
```
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.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/dental/inquiries"
```
```python Python theme={null}
import requests
url = 'https://healthharbor.co/api/v0/dental/inquiries'
response = requests.get(
url=url,
auth=([PROJECT_ID], [API_KEY])
)
```
***
Here is an example of a more complex benefits request that also retrieves frequencies and treatment history. Note the addition of `CODE_LOOKUP_FREQUENCIES` and `TREATMENT_HISTORY` to `benefits_query`.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request POST "https://healthharbor.co/api/v0/dental/inquiries" \
--header 'Content-Type: application/json' \
--data '{
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2000",
"member_id": "123456789",
"group_id": "123456",
"insurance": "UNITED_HEALTHCARE",
"insurance_in_network": true,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "provider_123",
"benefits_codes": [
"D0120",
"D4240"
],
"benefits_query": [
"CODE_LOOKUP_BENEFITS", "CODE_LOOKUP_FREQUENCIES", "TREATMENT_HISTORY"
],
"is_specialist": true
}'
```
```python Python theme={null}
import requests
import json
url = 'https://healthharbor.co/api/v0/dental/inquiries'
payload = {
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2000",
"member_id": "123456789",
"group_id": "123456",
"insurance": "UNITED_HEALTHCARE",
"insurance_in_network": True,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "provider_123",
"benefits_codes": [
"D0120",
"D4240"
],
"benefits_query": [
"CODE_LOOKUP_BENEFITS", "CODE_LOOKUP_FREQUENCIES", "TREATMENT_HISTORY"
],
"is_specialist": True
}
response = requests.post(
url = url,
data=json.dumps(payload),
auth=([PROJECT_ID], [API_KEY])
)
```
And the associated response:
```json JSON theme={null}
[
{
"id": "722b06d8-1855-402b-9916-bfa450cc1572",
"status": "SUCCESS",
"creation_ts": "2023-08-01T00:00:00.000000Z",
"summary": "Benefits retrieved successfully.",
"results": {
"call_details": [{
"call_end_time": "2023-08-01T06:00:00.0000Z",
"representative_name": "Deborah M",
"reference_number": "2812129",
"call_recording_url": "https://www.google.com/voice_recording.wav"
}],
"treatment_history": {
"10-01-2020": [{
"procedure_code": "D1110",
"tooth_numbers": [1, 21],
"surfaces": ["occlusal"],
"quadrant_numbers": [10]
},
{
"procedure_code": "D1120",
"tooth_numbers": [5],
"surfaces": ["distal"],
"quadrant_numbers": [20,30]
}
]
},
"procedure_codes": [
[
{
"procedure_code": "D0120",
"procedure_name": "Exam"
},
{
"is_covered": true,
"is_prior_auth_required": false,
"coverage_percentage": 100.0,
"frequency_limitations": "once per 36 floating months",
"more_info": ""
}
],
[
{
"procedure_code": "D4240",
"procedure_name": "Gingival Flap Procedure"
},
{
"is_covered": true,
"is_prior_auth_required": true,
"prior_auth_info": "Call United Healthcare at 555-123-1234",
"coverage_percentage": 50.0,
"frequency_limitations": "once per 5 years"
"more_info": ""
}
]
]
},
"request": {
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2020",
"member_id": "123456789",
"group_id": "123456",
"insurance_in_network": true,
"insurance": "UNITED_HEALTHCARE",
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "provider_123",
"benefits_codes": ["D0120", "D4240"],
"benefits_query": ["CODE_LOOKUP_BENEFITS", "CODE_LOOKUP_FREQUENCIES", "TREATMENT_HISTORY"],
"is_specialist": true
}
}
]
```
Great! Now you have successfully created a dental 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-dental-inquiry).
# Create Dental Inquiries
Source: https://docs.healthharbor.co/api-reference/endpoint/create-dental-inquiries
post /api/v0/dental/batch_inquiries
# Create Dental Inquiry
Source: https://docs.healthharbor.co/api-reference/endpoint/create-dental-inquiry
post /api/v0/dental/inquiries
# Create Medical Inquiries
Source: https://docs.healthharbor.co/api-reference/endpoint/create-medical-inquiries
post /api/v0/medical/batch_inquiries
# Create Medical Inquiry
Source: https://docs.healthharbor.co/api-reference/endpoint/create-medical-inquiry
post /api/v0/medical/inquiries
# Create Mental Health Inquiries
Source: https://docs.healthharbor.co/api-reference/endpoint/create-mental-health-inquiries
post /api/v0/mental_health/batch_inquiries
# Create Mental Health Inquiry
Source: https://docs.healthharbor.co/api-reference/endpoint/create-mental-health-inquiry
post /api/v0/mental_health/inquiries
# Get Dental Inquiries
Source: https://docs.healthharbor.co/api-reference/endpoint/get-dental-inquiries
get /api/v0/dental/inquiries
# Get Dental Inquiry
Source: https://docs.healthharbor.co/api-reference/endpoint/get-dental-inquiry
get /api/v0/dental/inquiries/{id}
# Get Medical Inquiries
Source: https://docs.healthharbor.co/api-reference/endpoint/get-medical-inquiries
get /api/v0/medical/inquiries
# Get Medical Inquiry
Source: https://docs.healthharbor.co/api-reference/endpoint/get-medical-inquiry
get /api/v0/medical/inquiries/{id}
# Get Mental Health Inquiries
Source: https://docs.healthharbor.co/api-reference/endpoint/get-mental-health-inquiries
get /api/v0/mental_health/inquiries
# Get Mental Health Inquiry
Source: https://docs.healthharbor.co/api-reference/endpoint/get-mental-health-inquiry
get /api/v0/mental_health/inquiries/{id}
# Get transcript verifications
Source: https://docs.healthharbor.co/api-reference/endpoint/get-transcript-verifications
get /api/v0/verification
Get transcript verification results for an inquiry. This endpoint retrieves all transcript verification results for a given inquiry, including verifications from all associated call logs.
# API Reference Introduction
Source: https://docs.healthharbor.co/api-reference/introduction
### Welcome
Welcome to our API Documentation. Here is all the information you'll need to programmatically submit and retrieve benefits, and claims status requests.
To begin, please select your specialty:
Dental Quickstart
Medical Quickstart
Mental Health Quickstart
# Medical Benefits Quickstart
Source: https://docs.healthharbor.co/api-reference/medical-benefits-quickstart
These endpoints require authentication. Please see
[authentication](../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](mailto:alan@healthharbor.co) for details.
```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])
)
```
Successful creations will return this response.
```json JSON theme={null}
{
"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.
```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])
)
```
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.
```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])
)
```
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).
# Medical Claim Status Quickstart
Source: https://docs.healthharbor.co/api-reference/medical-claim-status-quickstart
These endpoints require authentication. Please see
[authentication](../authentication) for more information.
### Overview
In this 5 minute quickstart, we will walk through how to submit claim status 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 check the claims status. This generally includes information about your provider, patient and the claim.
```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": "CLAIMS_STATUS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2023",
"member_id": "567891234",
"insurance": "UNITED_HEALTHCARE",
"beneficiary":"PRIMARY",
"npi": "1245319599",
"tax_id": "123456789",
"billed_amount": 100.99,
"claims_date_of_service": "08-01-2024",
"claim_number": "123456789",
}'
```
```python Python theme={null}
import requests
import json
url = 'https://healthharbor.co/api/v0/medical/inquiries'
payload = {
"type": "CLAIMS_STATUS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2023",
"member_id": "567891234",
"insurance": "UNITED_HEALTHCARE",
"beneficiary":"PRIMARY",
"npi": "1245319599",
"practice_billing_address": "123 Main St, New York, NY 10001",
"tax_id": "123456789",
"billed_amount": 100.99,
"claims_date_of_service": "08-01-2024",
"claim_number": "123456789",
}
response = requests.post(
url = url,
data=json.dumps(payload),
auth=([PROJECT_ID], [API_KEY])
)
```
Successful creations will return this response.
```json JSON theme={null}
{
"success": true,
"inquiry_id": "7d98c8a4-4b17-4e9b-b2f6-6131df874b8b",
}
```
### Retrieve an Inquiry
Now that you've made your first 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.
```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])
)
```
Here is a sample response.
```json JSON theme={null}
{
"id": "67daad83-01e3-4e35-9dee-e494a68fad2c",
"status": "SUCCESS",
"creation_ts": "2020-01-01T00:00:00.000000Z",
"summary": "Claims retrieved successfully.",
"results": {
"status": "APPROVED",
"number": "123456789",
"timeline": {
"date_received": "08-01-2024",
"date_processed": "08-05-2024",
"date_paid": "08-10-2024"
},
"unprocessed_claim_info": {
"date_processed_up_to": "08-05-2024",
"turnaround_time": null,
},
"code_details": [
{
"procedure_code": "94625",
"amound_paid": 80.99,
"patient_responsibility": 20.00,
"patient_applied_to_deductible": 20.00,
"adjustment_details": null,
"claim_denial_reason": null,
"appeal_or_correction_info": null,
}
]
},
"request":{
"type": "CLAIMS_STATUS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2023",
"member_id": "567891234",
"insurance": "UNITED_HEALTHCARE",
"beneficiary":"PRIMARY",
"npi": "1245319599",
"practice_billing_address": "123 Main St, New York, NY 10001",
"tax_id": "123456789",
"billed_amount": 100.99,
"claims_date_of_service": "08-01-2024",
"claim_number": "123456789",
}
}
```
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).
# Mental Health Quickstart
Source: https://docs.healthharbor.co/api-reference/mental-health-quickstart
As a prerequisite, you must have credentials to access our API. If you do not
have credentials, please [reach out](mailto:alan@healthharbor.co) to our team
to get set up.
### Authentication
Our API is authenticated using HTTP Basic Authentication. You'll need to pass in your credentials with every API request.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request GET https://healthharbor.co/api/v0/mental_health/inquiries
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/mental_health/inquiries'
[PROJECT_ID] = 'HEALTH_HARBOR_[PROJECT_ID]'
[API_KEY] = 'HEALTH_HARBOR_CREDENTIALS'
request = request.get(
url = url,
auth=([PROJECT_ID], [API_KEY])
)
```
### 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 use case of the [Mental Health API](endpoint/create-mental-health-inquiry). We'll be creating an inquiry to trigger a call on the Health Harbor API and retrieve the benefits information for a patient. You will need to provide information on the patient, patient's insurance, provider, and the benefits you are interested in checking.
You can choose from existing common sets of procedure codes (e.g. `PSYCHOTHERAPY`, `OFFICE_VISIT_NEW_PATIENT`) and add-on information such as network status or plan information. You can also provide your own custom procedure codes. For additional codes, please use `CODE_LOOKUP_BENEFITS` as the `benefits_query` and pass in the specific codes as `benefits_codes`.
For the full list of possible queries, please refer to the [Mental Health API documentation](endpoint/create-mental-health-inquiry).
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request POST "https://healthharbor.co/api/v0/mental_health/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_in_network": true,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "health_harbor_sf",
"diagnosis_codes": [
"F41.1",
"F42.23"
],
"benefits_query": [
"PLAN_INFO",
"MAXIMUMS",
"CODE_LOOKUP_BENEFITS"
],
"benefits_codes": [
"90832"
],
"insurance": "CIGNA",
"is_specialist": true,
"place_of_service": "office",
"practice_billing_address": "123 Main St, New York, NY 10001"
}'
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/mental_health/inquiries'
[PROJECT_ID] = 'HEALTH_HARBOR_[PROJECT_ID]'
[API_KEY] = 'HEALTH_HARBOR_CREDENTIALS'
payload = {
"type": "BENEFITS",
"desired_completion_date": "08-25-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2023",
"member_id": "567891234",
"group_id": "678123",
"insurance_in_network": true,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "health_harbor_sf",
"diagnosis_codes": [
"F41.1",
"F42.23"
],
"benefits_query": [
"PLAN_INFO",
"MAXIMUMS",
"CODE_LOOKUP_BENEFITS"
],
"benefits_codes": [
"90832"
],
"insurance": "CIGNA",
"is_specialist": true,
"place_of_service": "office",
"practice_billing_address": "123 Main St, New York, NY 10001"
}
response = request.post(
url = url,
data=json.dumps(payload),
auth=([PROJECT_ID], [API_KEY])
)
```
Successful creations will return an `inquiry_id`. You can use this `inquiry_id` to check on its status and see results.
```json JSON theme={null}
{
"success": true,
"inquiry_id": "7d98c8a4-4b17-4e9b-b2f6-6131df874b8b",
}
```
### Retrieve an Inquiry
Now that you've made a mental health inquiry, you can check on the results with a GET request using 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 if it is set up.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/mental_health/inquiries/722b06d8-1855-402b-9916-bfa450cc1572"
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/mental_health/inquiries'
[PROJECT_ID] = 'HEALTH_HARBOR_[PROJECT_ID]'
[API_KEY] = 'HEALTH_HARBOR_CREDENTIALS'
response = request.get(
url=url,
auth=([PROJECT_ID], [API_KEY])
)
```
Here is a sample response.
```json JSON theme={null}
{
"id": "string",
"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"
},
"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_classes": {},
"procedure_codes": [
[
{
"procedure_code": "90832",
"procedure_name": "Psychotherapy"
},
{
"is_covered": true,
"is_prior_auth_required": true,
"prior_auth_info": "Call Cigna at 1-800-997-1654",
"is_deductible_waived": false,
"copay_amount": "20.00",
"coinsurance_percentage": "20",
"frequency_limitations": "Two visits per week",
"limitations": "Family therapy is not covered.",
}
]
]
},
"request": {
"type": "BENEFITS",
"desired_completion_date": "08-19-2024",
"patient_name": "Alex Martin",
"dob": "01-31-2020",
"member_id": "123456789",
"group_id": "123456",
"insurance_in_network": true,
"npi": "1245319599",
"tax_id": "123456789",
"external_id": "health_harbor_sf",
"diagnosis_codes": ["F41.1", "F42.23"],
"benefits_query": [
"PLAN_INFO",
"MAXIMUMS",
"CODE_LOOKUP_BENEFITS"
],
"benefits_codes": [
"90832"
],
"claims_date_of_service": "01-31-2020",
"claim_number": "1234567890",
"insurance": "CIGNA",
"is_specialist": true,
"place_of_service": "office",
"practice_billing_address": "123 Main St, New York, NY 10001"
}
}
```
# Transcript verification quickstart
Source: https://docs.healthharbor.co/api-reference/transcript-verification-quickstart
### Overview
This endpoint retrieves all transcript verification results for a given inquiry. Transcript verifications contain AI-verified information extracted from call transcripts, including verification items that check specific criteria (e.g., patient eligibility, coverage details, etc.).
The results are returned sorted by creation time, with the most recent verification first.
### Example Request
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/verification?inquiry_id={INQUIRY_ID}
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/verification'
[PROJECT_ID] = 'HEALTH_HARBOR_[PROJECT_ID]'
[API_KEY] = 'HEALTH_HARBOR_CREDENTIALS'
request = request.get(
url = url,
params={"inquiry_id": INQUIRY_ID},
auth=([PROJECT_ID], [API_KEY])
)
```
### Response
The response includes a list of all verifications for the inquiry, sorted by creation time (newest first):
```json JSON theme={null}
{
"success": true,
"count": 2,
"verifications": [
{
"id": "verification_123",
"inquiry_id": "INQUIRY_ID",
"call_log_id": "call_log_456",
"verification_items": [
{
"name": "Patient Eligibility",
"description": "Verifies that the patient is eligible for coverage",
"status": "MET",
"evidence": "Representative confirmed patient is active",
"reasoning": "The transcript shows clear confirmation of active status"
}
],
"creation_ts": "2024-03-19T10:30:00Z"
}
]
}
```
If no verifications are found for the inquiry, the endpoint returns an empty array with `count: 0`.
# Authentication
Source: https://docs.healthharbor.co/authentication
### Authentication
All of our REST APIs require authentication for access.
There are two ways to get authenticated: OAuth2 and HTTP Basic Authentication. We recommend using OAuth2 but will discuss both supported ways here.
### OAuth2
To get authenticated with OAuth2, you must first retrieve an access token. Once you have successfully retrieved your access token, you can pass that in with your API requests to be authenticated. Our access tokens are valid for one day, please regenerate access tokens as needed.
You can generate an access token by making a POST to [https://healthharbor.co/api/v0/auth/token](https://healthharbor.co/api/v0/auth/token). This POST request requires you to pass in your username and password as multi-part form data. Your username and password should have been provided to you by the Health Harbor team. If you do not have one, please reach out to us on Slack or [email](mailto:alan@healthharbor.co).
It is important that your credentials are passed in as multi-part form data per OAuth2 specifications.
```bash cURL theme={null}
cURL --data '{"username": "yourusername", "password": "yourpassword"}' --header "Content-Type: application/x-www-form-urlencoded" --request POST https://healthharbor.co/api/v0/auth/token
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/auth/token'
payload = {
"username": "yourusername",
"password": "yourpassword"
}
headers = {
"Content-Type": "application/x-www-form-urlencoded"
}
response = request.post(
url=url,
data=payload,
headers=headers
)
```
A successful response will provide an access token and token type:
```json JSON theme={null}
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "bearer"
}
```
You can now use that access token to authenticate all your API requests!
```bash cURL theme={null}
curl --header "Authorization: Bearer youraccesstoken" --request GET https://healthharbor.co/api/v0/dental/inquiries
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/dental/inquiries'
headers = {
"Authorization": f"Bearer youraccesstoken"
}
request = request.get(
url=url,
headers=headers
)
```
### HTTP Basic Authentication
Another way to get authenticated is HTTP Basic Authentication. This requires you to send an Authorization header of your Project ID and API Key also known as your username and password respectively. This should be supported in almost all HTTP clients.
These should have been provided to you by the Health Harbor team. If you do not have one, please reach out to us on Slack or [email](mailto:alan@healthharbor.co).
```bash cURL theme={null}
curl -u "yourusername:yourpassword" --request GET https://healthharbor.co/api/v0/dental/inquiries
```
```python Python theme={null}
url = 'https://healthharbor.co/api/v0/dental/inquiries'
request = request.get(
url=url,
auth=("yourusername", "yourpassword")
)
```
# Introduction
Source: https://docs.healthharbor.co/introduction
## Overview
Health Harbor handles calls to insurance for your providers so you don't have to.
Our API allows you to submit call requests (inquiries) in bulk, and integrate them directly into your service for your providers and your patients. We handle the entire call, from navigating the IVR system to speaking with a live agent, and return results to you via our API. You'll then be able to view results directly within your own system.
We also provide a web portal for you to view results and listen to call recordings that can optionally be used in conjunction with the API.
### What we call for
Our API currently handles calls for:
* Eligibility and benefits/insurance verification checks
* Claims status checks
* Prior auth status checks
#### Eligibility and Benefits
In addition to checking if a patient's plan is active and deductibles/maximums, this also includes checking coverage levels for specific procedure codes, information typically not available via the insurance company's website.
#### Claims Status
We handle your AR follow up so you can understand why a claim shows no activity or is denied. Your team can then focus on fixing or adjusting the claim to recover payments left on the table.
#### Prior Auth Status
We can check the status of a prior authorization inquiry, including the date it was submitted, the date it was approved, how long it lasts and the number of visits approved.
### How Calls Work
Our AI voice calls insurance companies to retrieve any information you need, including eligibility, prior auth status and claims status / denial reasons. We are able to retrieve results in \~95% of all covered cases. In the remaining 5% of cases, we will provide you with the reason why we were unable to retrieve the information and you will not be charged for the call.
There are three main stages to calls, first navigating the insurance's automated system or IVR, then waiting on hold, and finally speaking directly with a live agent. We use an AI generated voice backed by generative AI technology to have a seamless conversation with the human insurance representative. We'll ask the questions you need answered and return the results to you.
The results will be sent to you directly through our subscription webhook. Alternatively, you can use a polling approach to retrieve events more often.
### Who we call
Currently, through our API we have support for the largest insurances which comprise \~50% of the plans in the US. We are actively working on expanding the number of insurances we support and expect to add more each month.
Sometimes, payors do not provide access to providers or make it particularly onorous to find or access information. In these cases, we are unable to provide results in bulk. These insurances include:
UMR, Veterans Affairs
### Completion Time
On average, requests take 24 hours to return results. Our SLA is 2 business days.
In rare cases, we may exceed this limitation due to circumstances outside our control. Payor systems are often under maintenance or overloaded and unable to handle any queries regardless of who is calling in. This happens on a surprisingly regular cadence (historically \~1-2 days a month).
### Verifying Results
We provide multiple data points for you to verify that our information is accurate.
First we provide the name of the representative or representatives that we spoke with and their reference number(s). We also provide the date and time that the call took place.
Then, we provide access to the call transcript, making it easy to quickly review the conversation with our AI.
Finally we enable access to the recording of the call, so that you can verify the source data our results are based upon.
### Pricing
We charge based on the complexity of a call and how urgently you need the information.
* We charge in proportion to the complexity of the call. Importantly, it is not based on call duration, but rather what information is needed. For example, with eligibility requests we consider how many custom questions you need answered, as well as how many codes you want benefits for. We do not factor in the time it takes to navigate the IVR system or even wait on hold. We eat that cost for you.
* We also charge based on how urgently you need information. Urgent requests are 2x the price of non-urgent requests. Non-urgent requests return results in 48 hours. Urgent requests return results on the same day if submitted before noon eastern time.
Once we've aligned on pricing of your non-urgent requests, we provide free access to our web portal. Access to our API requires a one-time implementation fee as it come with dedicated time from one of our engineers.
As you scale up usage, we provide volume based discounts. Contact us for more information.
## API Details
For more information, take a look at our quickstarts for [dental](api-reference/dental-quickstart), [mental health](api-reference/mental-health-quickstart), and [medical](api-reference/medical-benefits-quickstart) providers.
Supported operations include:
1. Creating an inquiry to call insurance for a provider.
2. Reading a previously submitted inquiry to get its status and results.
Each operation is supported individually or in bulk.
### API Reference
Learn more about our what you can do with our API
# Webhooks
Source: https://docs.healthharbor.co/webhooks
We support webhooks as an alternative to polling to receive real-time updates on your inquiries. This allows your backend to receive updates as soon as they are available without the need to poll our API for updates or keep track of inquiries in progress.
## Getting Started with Webhooks
To enable webhooks, you'll need to register a subscription with a webhook endpoint. This endpoint will receive a POST request with the inquiry data whenever an update has been made (e.g. when the call is initiated, in progress and completed).
This can be done by sending a POST request to the `/api/v0/subscription/` endpoint with a callback URL and an update frequency (defaults to 5 minutes). Only one subscription can be registered at a time. Any changes will update the existing subscription. It can be viewed by sending a GET request to the endpoint and be deleted by sending a DELETE request to the same endpoint.
```bash cURL theme={null}
curl -u [PROJECT_ID]:[API_KEY] --request POST "https://healthharbor.co/api/v0/subscription/" \
--header 'Content-Type: application/json' \
--data '{
"callback_url": "https://your-webhook-endpoint.com",
"update_frequency_min": 5
}'
```
```python Python theme={null}
import requests
import json
url = 'https://healthharbor.co/api/v0/subscription/'
payload = {
"callback_url": "https://your-webhook-endpoint.com",
"update_frequency_min": 5
}
response = requests.post(
url = url,
data=json.dumps(payload),
auth=([PROJECT_ID], [API_KEY])
)
```
```javascript Javascript theme={null}
const axios = require('axios');
const url = 'https://healthharbor.co/api/v0/subscription/';
const payload = {
callback_url: 'https://your-webhook-endpoint.com',
update_frequency_min: 5
};
axios.post(url, payload, {
auth: {
username: [PROJECT_ID],
password: [API_KEY]
}
});
```
### Webhook Request Format
As a request, you will receieve a JSON object similar to the following. Each request contains a subscription\_id, a message hash that can be used to uniquely identify the message to prevent duplicates and an array of inquiries that have been updated. Each inquiry object is the same as the one you would receive from the polling based API as a response. See the responses on the respective quickstarts for more information: [Dental](/docs/api-reference/dental-quickstart), [Mental Health](/docs/api-reference/mental-health-quickstart), [Medical](/docs/api-reference/medical-quickstart).
Due to limitations on POST request payload size, if the request is too large, it may be broken up into multiple requests that are sent in quick succession at the specified frequency.
```json theme={null}
{
"subscription_id": "TEST_SUBSCRIPTION_ID",
"inquiries": [
{
"id": "inquiry_id",
"status": "IN_PROGRESS",
"creation_ts": "2024-05-24T18:18:27.134818",
"summary": "",
"results": null,
"request": {
"type": "BENEFITS",
"desired_completion_date": "05-24-2024",
"patient_name": "Alan Liu",
"dob": "01-25-1980",
"member_id": "U1231234",
"group_id": null,
"insurance_in_network": false,
"npi": "1234567890",
"tax_id": "123456789",
"external_id": "correlation_id",
"diagnosis_codes": null,
"claims_date_of_service": null,
"claim_number": null,
"insurance": "METLIFE",
"benefits_query": [
"TREATMENT_HISTORY"
],
"benefits_codes": [
],
"is_specialist": null
}
}
],
"message_hash": "aa2c28076dfd961db84b9396e35cf5511d07338012983e702833cf92a107e2fa"
}
```
### Best Practices
#### Handle duplicate events
Webhook endpoints might sometimes receive the same event multiple times. To prevent duplicate event processing, ensure your event handling is idempotent. One approach is to log the events you have processed and then skip any events that are already logged. We provide a message hash with every request that can be used to uniquely identify the message.
#### Exempt webhook route from CSRF protection
If you're utilizing Rails, Django, or another web framework, your site likely verifies that every POST request includes a CSRF token. This crucial security feature safeguards you and your users against cross-site request forgery attempts. However, this protection can sometimes interfere with the processing of legitimate events. In such cases, you may need to exclude the webhooks route from CSRF protection.
### Webhook Security and Verification
We sign all Webhook events with a signature to ensure that they are authentic and have not been tampered with. This signature is included in the `X-HealthHarbor-Signature` header of the request. You can use this signature to verify the authenticity of the event.
Signatures are generated using a hash-based message authentication code (HMAC) with SHA-256. The signature is computed using the secret key provided by Health Harbor (contact [alan@healthharbor.co](mailto:alan@healthharbor.co) if you need the webhook secret). You can verify the signature by re-computing it using the same secret key and comparing it to the signature in the request.
Here's an example code snippet that compares the signature in the request to the computed signature:
```python Python theme={null}
import hmac
import hashlib
import os
from flask import request
WEBHOOK_SECRET = os.environ.get('WEBHOOK_SECRET')
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers['X-HealthHarbor-Signature']
payload = request.data
computed_signature = hmac.new(WEBHOOK_SECRET, payload, hashlib.sha256).hexdigest()
if computed_signature == signature:
# Signature is valid
else:
# Signature is invalid
```
```javascript Javascript theme={null}
const crypto = require('crypto');
const secret = process.env.WEBHOOK_SECRET;
const signature = req.headers['X-HealthHarbor-Signature'];
const payload = req.body;
const computedSignature = crypto.createHmac('sha256', secret)
.update(payload)
.digest('hex');
if (computedSignature === signature) {
// Signature is valid
} else {
// Signature is invalid
}
```