As a prerequisite, you must have credentials to access our API. If you do not have credentials, please reach out 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.

curl -u [PROJECT_ID]:[API_KEY] --request GET https://healthharbor.co/api/v0/mental_health/inquiries

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

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"
}'

Successful creations will return an inquiry_id. You can use this inquiry_id to check on its status and see results.

{
  "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.

curl -u [PROJECT_ID]:[API_KEY] --request GET "https://healthharbor.co/api/v0/mental_health/inquiries/722b06d8-1855-402b-9916-bfa450cc1572"

Here is a sample response.

JSON
{
  "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"
  }
}