Get Medical Inquiry

GET

api

medical

inquiries

{id}

{
  "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",
        "call_recording_url": "https://www.google.com/voice_recording.wav",
        "transcript": "..."
      }
    ],
    "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": {
      "PHYSICAL_THERAPY": {
        "is_covered": true,
        "is_prior_auth_required": true,
        "prior_auth_info": "Call Benefits Office at 555-999-1234.",
        "is_deductible_waived": true,
        "copay_amount": "50.00",
        "coinsurance_percentage": "30",
        "frequency_limitations": "None"
      },
      "CHIROPRACTIC": {
        "is_covered": false,
        "more_info": ""
      }
    },
    "procedure_codes": [
      [
        {
          "procedure_code": "94625",
          "procedure_name": "Pulmonary Rehabilitation Coverage"
        },
        {
          "is_covered": true,
          "is_prior_auth_required": true,
          "prior_auth_info": "Call United Healthcare at 555-123-1234",
          "is_deductible_waived": false,
          "copay_amount": "20.00",
          "coinsurance_percentage": "20",
          "frequency_limitations": "Two visits per week",
          "more_info": "Diagnosis of medium to severe COPD is required for coverage."
        }
      ],
      [
        {
          "procedure_code": "94626",
          "procedure_name": "Pulmonary Rehabilitation Coverage"
        },
        {
          "is_covered": false,
          "more_info": ""
        }
      ]
    ]
  },
  "request": {
    "type": "BENEFITS",
    "desired_completion_date": "03-19-2024",
    "patient_name": "Alex Martin",
    "dob": "01-31-2020",
    "member_id": "123456789",
    "group_id": "123456",
    "insurance_in_network": true,
    "npi": "1234567890",
    "tax_id": "123456789",
    "external_id": "<string>",
    "practice_billing_address": "123 Main St, New York, NY 10001",
    "diagnosis_codes": [
      "F41.1",
      "F42.23"
    ],
    "claims_date_of_service": "01-31-2020",
    "claim_number": "1234567890",
    "additional_info": "The patient is on a Medicare plan and we need to know their secondary insurance benefits.",
    "insurance": "UNITED_HEALTHCARE",
    "benefits_query": [
      "PULMONARY_REHAB_COVERAGE"
    ],
    "benefits_codes": [
      "99395"
    ],
    "benefits_form_name": "",
    "is_specialist": true,
    "place_of_service": "doctors office",
    "billed_amount": 100,
    "insurance_payor_id": "60054",
    "insurance_phone_number": "<string>"
  }
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

string

required

Response

200

application/json

Successful Response

string

required

unique generated (uuid4) id for the inquiry

status

enum<string>

required

status of the inquiry

Available options:

SCHEDULED,

IN_PROGRESS,

SUCCESS,

UNSUCCESSFUL,

CANCELLED,

UNKNOWN

Example:

"SUCCESS"

creation_ts

string

required

timestamp of when the inquiry was created

Example:

"2020-01-01T00:00:00.000000Z"

request

object

required

The request that was used to create the inquiry.

request.type

enum<string>

required

type of the inquiry

Available options:

CLAIMS_STATUS,

BENEFITS,

UNKNOWN

Example:

"BENEFITS"

request.desired_completion_date

string

required

The requested completion date of the inquiry in MM-DD-YYYY format. Calls will typically be completed by the morning of the requested completion date, but in some cases may be completed earlier.

Example:

"03-19-2024"

request.patient_name

string

required

name of the patient

Example:

"Alex Martin"

request.dob

string

required

date of birth of the patient in MM-DD-YYYY format

Example:

"01-31-2020"

request.member_id

string

required

member id of the patient

Example:

"123456789"

request.npi

string

required

Ten digit NPI of the provider

Example:

"1234567890"

request.tax_id

string

required

Nine digit tax id of the provider

Example:

"123456789"

request.insurance

required

The insurance provider for the patient.

Available options:

AETNA,

HUMANA,

OPTUM,

OXFORD,

UNITED_HEALTHCARE,

UNKNOWN

Example:

"UNITED_HEALTHCARE"

request.group_id

string

group id of the patient

Example:

"123456"

request.insurance_in_network

boolean

whether or not the provider is in-network. If it is not known, leave this field blank and it will be determined.

request.external_id

string

An identifier 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.

request.practice_billing_address

string

The billing address of the practice. If omitted, the address will be determined from the NPI.

Example:

"123 Main St, New York, NY 10001"

request.diagnosis_codes

string[]

Any diagnosis codes for the patient. If omitted, a general diagnosis code will be used.

Example:

["F41.1", "F42.23"]

request.claims_date_of_service

string

The date of service for the claim in MM-DD-YYYY format. Only used for claims inquiries.

Example:

"01-31-2020"

request.claim_number

string

The claim number for the inquiry if provided by the user. Only used for claims inquiries.

Example:

"1234567890"

request.additional_info

string

Any additional information about the inquiry that is not covered by the other fields. This can be used to pass in any additional information for the request. Please check with the Health Harbor team before using this field as it may not be incorporated into the inquiry unless we are already aware of it.

Example:

"The patient is on a Medicare plan and we need to know their secondary insurance benefits."

request.benefits_query

enum<string>[]

The specific set of benefits to query. These are customized for each customer. Contact alan@healthharbor.co for details.

An enumeration.

Available options:

DEDUCTIBLES_AND_MAXIMUMS,

PLAN_INFO,

NETWORK_STATUS,

CODE_LOOKUP_PRIOR_AUTH,

CODE_LOOKUP_BENEFITS,

PULMONARY_REHAB_COVERAGE,

PRIOR_AUTH_PHYSICAL_THERAPY,

WEIGHT_MANAGEMENT,

TRIAL,

UNKNOWN

Example:

["PULMONARY_REHAB_COVERAGE"]

request.benefits_codes

string[]

Codes processed for a CODE_LOOKUP_BENEFITS or a CODE_LOOKUP_PRIOR_AUTH benefits inquiry.

Example:

["99395"]

request.benefits_form_name

string

The name of a custom form for your providers. Contact alan@healthharbor.co for details.

Example:

""

request.is_specialist

boolean

The type of provider making the inquiry. If the provider is a specialist, set this to True. If the provider is a general PCP, set this to False.

Example:

true

request.place_of_service

string

Where the service will be performed. This is typically one of a few places: the doctors office or telehealth See this page for the full list: https://www.cms.gov/medicare/coding-billing/place-of-service-codes/code-sets

Example:

"doctors office"

request.billed_amount

number

The billed amount for the claim. Value should be a float with 2 decimal places. Only used for claims inquiries.

Example:

100

request.insurance_payor_id

string

The payor id for the insurance. Usually five characters. For example, one payor id for Aetna is 60054.

Example:

"60054"

request.insurance_phone_number

string

The phone number used for identifying the insurance

summary

string

summary of the call results

Example:

"Benefits retrieved successfully."

results

object

The output from the call containing the benefits results..

results.call_details

object[]

required

The details of the placed calls including the call time in iso format, representative name, reference number, and transcript.

Example:

[
  {
    "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",
    "transcript": "..."
  }
]

results.plan_information

object

The plan information for the patient including the plan type and effective date. Dates will be provided in MM-DD-YYYY format. Fields will only be included if applicable, for example, when the plan is not active, no other information will be provided.

Example:

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

results.maximums

object

The maximums for the patient including the individual and family deductible and out of pocket maximums. Fields will only be included if applicable, for example, on individual plans, family information will not be available.

Example:

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

results.procedure_classes

object

A dict that maps from the different categories of procedures to their benefits. Categories will contain prior auth, deductibles, copay amounts, coinsurance percentages and any frequency limitations. See examples for more information

Example:

{
  "PHYSICAL_THERAPY": {
    "is_covered": true,
    "is_prior_auth_required": true,
    "prior_auth_info": "Call Benefits Office at 555-999-1234.",
    "is_deductible_waived": true,
    "copay_amount": "50.00",
    "coinsurance_percentage": "30",
    "frequency_limitations": "None"
  },
  "CHIROPRACTIC": { "is_covered": false, "more_info": "" }
}

results.procedure_codes

array

A list that contains a tuple of procedure code information and their benefits. For medical, procedure codes, if covered, will contain deductible information, copays, coinsurance, frequency limitations and whether or not prior authorization is needed. Coinsurance refers to the patient's portion of the payment.

Example:

[
  [
    {
      "procedure_code": "94625",
      "procedure_name": "Pulmonary Rehabilitation Coverage"
    },
    {
      "is_covered": true,
      "is_prior_auth_required": true,
      "prior_auth_info": "Call United Healthcare at 555-123-1234",
      "is_deductible_waived": false,
      "copay_amount": "20.00",
      "coinsurance_percentage": "20",
      "frequency_limitations": "Two visits per week",
      "more_info": "Diagnosis of medium to severe COPD is required for coverage."
    }
  ],
  [
    {
      "procedure_code": "94626",
      "procedure_name": "Pulmonary Rehabilitation Coverage"
    },
    { "is_covered": false, "more_info": "" }
  ]
]

Create Medical Inquiries Get Medical Inquiries

{
  "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",
        "call_recording_url": "https://www.google.com/voice_recording.wav",
        "transcript": "..."
      }
    ],
    "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": {
      "PHYSICAL_THERAPY": {
        "is_covered": true,
        "is_prior_auth_required": true,
        "prior_auth_info": "Call Benefits Office at 555-999-1234.",
        "is_deductible_waived": true,
        "copay_amount": "50.00",
        "coinsurance_percentage": "30",
        "frequency_limitations": "None"
      },
      "CHIROPRACTIC": {
        "is_covered": false,
        "more_info": ""
      }
    },
    "procedure_codes": [
      [
        {
          "procedure_code": "94625",
          "procedure_name": "Pulmonary Rehabilitation Coverage"
        },
        {
          "is_covered": true,
          "is_prior_auth_required": true,
          "prior_auth_info": "Call United Healthcare at 555-123-1234",
          "is_deductible_waived": false,
          "copay_amount": "20.00",
          "coinsurance_percentage": "20",
          "frequency_limitations": "Two visits per week",
          "more_info": "Diagnosis of medium to severe COPD is required for coverage."
        }
      ],
      [
        {
          "procedure_code": "94626",
          "procedure_name": "Pulmonary Rehabilitation Coverage"
        },
        {
          "is_covered": false,
          "more_info": ""
        }
      ]
    ]
  },
  "request": {
    "type": "BENEFITS",
    "desired_completion_date": "03-19-2024",
    "patient_name": "Alex Martin",
    "dob": "01-31-2020",
    "member_id": "123456789",
    "group_id": "123456",
    "insurance_in_network": true,
    "npi": "1234567890",
    "tax_id": "123456789",
    "external_id": "<string>",
    "practice_billing_address": "123 Main St, New York, NY 10001",
    "diagnosis_codes": [
      "F41.1",
      "F42.23"
    ],
    "claims_date_of_service": "01-31-2020",
    "claim_number": "1234567890",
    "additional_info": "The patient is on a Medicare plan and we need to know their secondary insurance benefits.",
    "insurance": "UNITED_HEALTHCARE",
    "benefits_query": [
      "PULMONARY_REHAB_COVERAGE"
    ],
    "benefits_codes": [
      "99395"
    ],
    "benefits_form_name": "",
    "is_specialist": true,
    "place_of_service": "doctors office",
    "billed_amount": 100,
    "insurance_payor_id": "60054",
    "insurance_phone_number": "<string>"
  }
}

API Documentation

Dental

Mental Health

Medical

Authorizations

Path Parameters

Response