API Documentation
- Quickstart Guide
- Changelog
- POSTRun Benefit Verification
- GETRetrieve Benefit Verification
- POSTCancel Benefit Verification
- POSTSend Prior Authorization
- GETRetrieve Prior Authorization
- POSTAuthorize Provider
- POSTCheck Clinical Qualification
- GETRetrieve Clinical Qualification
- POSTCheck Prior Authorization Status
- POSTSubmit Patient Enrollment
- Authentication
- Webhooks
Retrieve Benefit Verification
curl --request GET \
--url https://api.develophealth.ai/benefit-verification/{id} \
--header 'Authorization: Bearer <token>'{
"status": "success",
"data": {
"id": "bv_dj3wiu",
"object": "benefit_verification",
"status": "completed",
"status_description": "The verification was successful",
"review_status": "not_reviewed",
"drugs": [
{
"name": "Wegovy",
"dosage": "0.25 mg",
"quantity": 28,
"coverage": "covered",
"coverage_detail_code": "insurer_reported_value",
"prior_authorization_required": "yes",
"copay": "$30 for 28 days supply",
"copay_options": [
{
"amount_cents": 3000,
"supply_duration_days": 28
}
],
"determination_details": {
"is_on_formulary": true
}
},
{
"name": "Ozempic",
"dosage": "0.25 mg",
"quantity": 28,
"coverage": "covered",
"coverage_detail_code": "insurer_reported_value",
"prior_authorization_required": "yes",
"copay": "$30 for 28 days supply",
"copay_options": [
{
"amount_cents": 3000,
"supply_duration_days": 28
}
],
"determination_details": {
"is_on_formulary": true
}
},
{
"name": "Mounjaro",
"dosage": "2.5 mg",
"quantity": 28,
"coverage": "covered",
"coverage_detail_code": "insurer_reported_value",
"prior_authorization_required": "yes",
"copay": "$30 for 28 days supply",
"copay_options": [
{
"amount_cents": 3000,
"supply_duration_days": 28
}
],
"determination_details": {
"is_on_formulary": true
}
}
],
"drug_history": {
"currently_taking_drugs": [
{
"name": "Metformin"
}
],
"previously_taken_drugs": [
{
"name": "Jardiance"
},
{
"name": "Rybelsus"
}
]
},
"diagnoses": [
{
"code": "E66.9"
},
{
"code": "I10"
}
],
"patient": {
"internal_id": "39dca4a2-8788-4fd6-9e31-15c56e454322",
"first_name": "John",
"last_name": "Smith",
"gender": "male",
"date_of_birth": "1980-01-01",
"address": {
"street": "123 Main St, Apt 1",
"city": "Los Angeles",
"state_province": "CA",
"zip_postal_code": "94001",
"country": "USA"
},
"phone": "555-555-5555"
},
"provider": {
"first_name": "Jane",
"last_name": "Green",
"address": {
"street": "9071 E. Mississippi Ave",
"city": "Denver",
"state_province": "CO",
"zip_postal_code": "80247",
"country": "USA"
},
"phone": "1231231234",
"npi": "0000000000",
"in_network_payers": []
},
"entity": {
"legal_name": "Test Entity",
"tax_id": "111223333"
},
"insurance": [
{
"scanned_content": {
"client_name": "Company",
"group_number": "12345678",
"member_name": "John Smith",
"member_number": "12345678",
"payer_name": "United",
"plan_name": "Plus Plan",
"rx_bin": "123456",
"rx_group": "ADV",
"rx_pcn": "FAC"
},
"discrete_content": {},
"url": "https://example.com/insurance_doc"
},
{
"scanned_content": {
"error": "Unable to extract information from card"
},
"discrete_content": {},
"url": "https://example.com/insurance_doc2"
}
],
"patient_coverage_status": "covered",
"verification_methods": [
{
"id": "bva_23j3234",
"type": "ai_call",
"transcript": "Call transcript",
"recording_url": "https://example.com/recording"
}
],
"patient_plan_fund_source": "question_not_asked",
"patient_coverage_type": "question_not_asked",
"priority": 2
}
}Retrieve details of a specific benefit verification request.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Response
Represents the response structure for a benefit verification query in a healthcare context.
This class extends the generic ApiResponse, specifically tailored to handle responses related to benefit verifications. It primarily includes the data attribute, which holds detailed information about the benefit verification process and its results.
success Represents the data the data contained in the response for a get benefit verification request.
The ID of the benefit verification request.
Benefit Verifications will always start in the pending state. Once the verification is complete, the status will change to completed or failed. If the verification is still in progress, the status will remain pending.
pending, failed, completed, cancelled Provides additional information about the verification status.
The status on if this benefits investigation has been reviewed in the portal. Users of the portal can click the 'Mark as Reviewed' button to mark the benefits investigation as reviewed.
reviewed, not_reviewed List of drug coverage information related to the verification.
Represents information about a specific drug.
The name of the drug.
The prescribed dosage of the drug.
The quantity of the drug prescribed.
This field will start off as null and will be populated if the benefit verification is successfully completed. The drug coverage result
covered, not_covered This field will start off as null and will be populated if the benefit verification is successfully completed. The options are:
- insurer_reported_value: This is the exact value that the insurer reported for the drug coverage.
- diagnoses_not_covered: The drug is being reported as not covered due to this patients specific diagnosis codes
insurer_reported_value, diagnoses_not_covered This field will start off as null and will be populated if the benefit verification is successfully completed. A not_applicable value will be returned if the drug is not covered by the insurance plan.
yes, no, not_applicable This field will start off as null and will be populated if the benefit verification is successfully completed and a copay is received.
A collection of more granular details surrounding the drug coverage determination.
Whether the drug is on the formulary for the patient's plan.
Whether the drug is explicitly excluded from the patient's plan.
Whether the prior authorization is acting as an exception request. This is only applicable if the drug is not on the formulary.
Demographic information for the patient
Your internal ID for this patient. This is used for linking all of the requests for a given patient.
1The first name of the patient.
1The last name of the patient.
1The gender of the patient.
male, female, other, not_specified The date of birth of the patient.
The address of the patient.
Street address of residence.
1City of residence.
1State or province of residence.
1ZIP or postal code part of the address.
1Country of residence.
1Additional street address information.
The contact phone number of the patient.
The contact email address of the patient.
Details of the healthcare provider whose NPI number can be used for the benefit verification.
The first name of the provider.
1The last name of the provider.
1The address of the provider.
Street address of residence.
1City of residence.
1State or province of residence.
1ZIP or postal code part of the address.
1Country of residence.
1Additional street address information.
The National Provider Identifier (NPI) of the provider.
1The contact phone number of the provider.
List of insurance payers that the provider is in-network with. This is optional and no longer seems to have much of an impact on the verification process. You can omit this if it is not readily available information
Insurance information for the patient.
An object containing details that were extracted from the insurance card images provided in the creation request.
The client/employer name.
The group number on the card.
The member name on the card.
The member number on the card.
The payer name on the card. This field is not normalized, so the same plan may have different names depending on the way it appears on the card. i.e. 'United Healthcare', 'United', 'United Health' could all appear
The plan name on the card. This field is not normalized, so the same plan may have different names depending on the way it appears on the card
The Rx BIN number on the card.
The Rx group number on the card.
The Rx PCN number on the card.
Error message if we were unable to extract information from the card.
An object containing manually-provided insurance details from the creation request.
The client/employer name.
The group number on the card.
The member name on the card.
The member number on the card.
The payer name on the card. This field is not normalized, so the same plan may have different names depending on the way it appears on the card. i.e. 'United Healthcare', 'United', 'United Health' could all appear
The plan name on the card. This field is not normalized, so the same plan may have different names depending on the way it appears on the card
The Rx BIN number on the card.
The Rx group number on the card.
The Rx PCN number on the card.
If applicable, the Base64 encoded insurance card image you send in the request is stored on our servers. A signed URL to the image is returned here. This URL has a short expiry time, so you should download the image immediately after receiving it if you want to view the asset.
This field indicates the insurance coverage status of the patient. The options are:
- covered: Indicates that the patient is covered by the insurance plan.
- patient_not_found: Indicates that the patient could not be found in the insurance database.
- coverage_expired: Implies that the patient's insurance coverage has expired.
- coverage_not_started: Suggests that the patient's insurance coverage is in place but has not started yet.
- patient_not_covered_unspecified: Used when the patient is not covered by the insurance plan, but the specific reason is not specified.
- unknown: We were unable to determine the patient's insurance coverage status.
patient_not_found, coverage_expired, coverage_not_started, covered, patient_not_covered_unspecified, human_unable_to_answer, missing_from_transcript, unknown List of verification methods used to determine the coverage status of the drug. These will contain evidence from the verification procedure, such as a transcript of the phone conversation between the AI and the insurance provider.
Represents the verification method used in a benefit verification response.
The priority of the benefit verification request, as defined in the creation request.
0, 1, 2, 3 The type of object the response is about, which is 'benefit_verification'.
benefit_verification Specific error information if the benefit verification failed
A brief title summarizing the error.
A specific code identifying the error. This list will likely expand over time to provide more specific error codes. The following codes are currently supported:
- Unable to Route Call: We were unable to determine the correct number to call using the insurance information provided. More information is required.
- Document Info Missing or Incorrect: The insurance documents provided are missing information that is necessary to identify the patient. The information could be outdated or not present in the documentation. For example, the documents might be missing the member ID for the patient, or could have a medical only ID, or could have an out of date address. To fix this error you can try re-uploading documents that contain the information specified in the message for this error.
- Document Quality Error: The insurance documents provided are not valid insurance documents or are low quality (blurry or low resolution) and therefore cannot be processed by our system. To fix this error you can try re-uploading higher quality documents.
- Insurance Card OCR Failure: This error means we were unable to read the necessary information from the insurance card image provided. This could be due to the image being unclear. Please check the images provided and/or provide the information manually if possible. This is generally an issue that would be handled on your side, and may involve reaching out to the patient to get a better image of their insurance card.
- Insurance Unable to Provide Information: The insurance company was unable to provide the information needed to determine the patient's coverage status. This could be due to various reasons such as the insurance representative being unable or unwilling to provide the necessary details, or issues during the call, like refusal to transfer to a supervisor.
- Patient Not Found: The plan contact we called was unable to locate the patient in their system. We weren't able to identify a root cause issue with the documentation provided, but re-uploading additional documents may help.
- Unable to Gather Benefits: We were unable to gather benefits from the insurance company. This could be due to a variety of reasons, such as the insurance company not being able to provide the information, or the information provided not being sufficient to determine the patient's coverage status. To fix this error, you can try providing insurace information manually and/or providing medication history.
- Internal Error: There was an internal error during the benefit verification.
Patient Not Found, Insurance Card OCR Failure, Insurance Unable to Provide Information, Document Quality Error, Document Info Missing or Incorrect, Unable to Route Call, Unable to Gather Benefits, Internal Error A more detailed code that can be used to identify the specific issue that caused the error.
incorrect_member_id, incorrect_dob, incorrect_address, incorrect_phone_number, missing_member_id, medical_only_member_id, name_mismatch A detailed message explaining the error, such as: 'We were unable to extract the member ID from the insurance card image provided, the image(s) my be unclear.' These messages may be unique to the specific benefit verification request.
A more detailed message that can be used to identify the specific issue that caused the error.
The patient's drug history
The drugs that the patient is currently taking.
Represents information about a currently or previously taken drug.
The name of the drug.
List of diagnoses for the patient.
Represents a medical diagnosis with a code and description.
ICD-10 code for the diagnosis. i.e. 'E66.9'
A large proportion (20%+) of payers will often ask for information on the legal entity that the provider is associated with. Without this information the benefit verification will fail. Although this is currently optional it will be required in the future. We highly recommend providing this information.
Details of the mock result if one was used for this benefit verification.
An enumeration.
completed The case to simulate for the benefit verification. The options are:
- drugs_covered__prior_auth_required__has_copay: Drug is covered, prior authorization required, and there is a copay.
- drugs_covered__prior_auth_required__no_copay: Drug is covered, prior authorization required, but there is no copay.
- drugs_covered__prior_auth_not_required__has_copay: Drug is covered, no prior authorization required, and there is a copay.
- drugs_covered__prior_auth_not_required__no_copay: Drug is covered, no prior authorization required, and there is no copay.
- drugs_not_covered__prior_auth_na__no_copay: Drug is not covered, prior authorization not applicable (because the drug is not covered), and there is no copay.
drugs_covered__prior_auth_required__has_copay, drugs_covered__prior_auth_required__no_copay, drugs_covered__prior_auth_not_required__has_copay, drugs_covered__prior_auth_not_required__no_copay, drugs_not_covered__prior_auth_na__no_copay The source of the patient's plan funding. The options are:
- commercial: The patient's plan is commercial insurance.
- government: The patient's plan is government-funded.
- question_not_asked: The patient's plan funding source was not asked.
- unable_to_determine: The patient's plan funding source was asked, but could not be determined.
commercial, government, question_not_asked, unable_to_determine The type of coverage the patient has. The options are:
- medicare
- medicare_advantage
- tricare
- medicaid
- other
- question_not_asked
- unable_to_determine
medicare, medicare_advantage, tricare, medicaid, other, question_not_asked, unable_to_determine If this Benefit Verification was canceled and subsequently resubmitted, this field stores the ID of the new (replacement) Benefit Verification.
If this Benefit Verification was submitted as a replacement for a canceled one, this field stores the ID of the canceled Benefit Verification it replaces.
curl --request GET \
--url https://api.develophealth.ai/benefit-verification/{id} \
--header 'Authorization: Bearer <token>'{
"status": "success",
"data": {
"id": "bv_dj3wiu",
"object": "benefit_verification",
"status": "completed",
"status_description": "The verification was successful",
"review_status": "not_reviewed",
"drugs": [
{
"name": "Wegovy",
"dosage": "0.25 mg",
"quantity": 28,
"coverage": "covered",
"coverage_detail_code": "insurer_reported_value",
"prior_authorization_required": "yes",
"copay": "$30 for 28 days supply",
"copay_options": [
{
"amount_cents": 3000,
"supply_duration_days": 28
}
],
"determination_details": {
"is_on_formulary": true
}
},
{
"name": "Ozempic",
"dosage": "0.25 mg",
"quantity": 28,
"coverage": "covered",
"coverage_detail_code": "insurer_reported_value",
"prior_authorization_required": "yes",
"copay": "$30 for 28 days supply",
"copay_options": [
{
"amount_cents": 3000,
"supply_duration_days": 28
}
],
"determination_details": {
"is_on_formulary": true
}
},
{
"name": "Mounjaro",
"dosage": "2.5 mg",
"quantity": 28,
"coverage": "covered",
"coverage_detail_code": "insurer_reported_value",
"prior_authorization_required": "yes",
"copay": "$30 for 28 days supply",
"copay_options": [
{
"amount_cents": 3000,
"supply_duration_days": 28
}
],
"determination_details": {
"is_on_formulary": true
}
}
],
"drug_history": {
"currently_taking_drugs": [
{
"name": "Metformin"
}
],
"previously_taken_drugs": [
{
"name": "Jardiance"
},
{
"name": "Rybelsus"
}
]
},
"diagnoses": [
{
"code": "E66.9"
},
{
"code": "I10"
}
],
"patient": {
"internal_id": "39dca4a2-8788-4fd6-9e31-15c56e454322",
"first_name": "John",
"last_name": "Smith",
"gender": "male",
"date_of_birth": "1980-01-01",
"address": {
"street": "123 Main St, Apt 1",
"city": "Los Angeles",
"state_province": "CA",
"zip_postal_code": "94001",
"country": "USA"
},
"phone": "555-555-5555"
},
"provider": {
"first_name": "Jane",
"last_name": "Green",
"address": {
"street": "9071 E. Mississippi Ave",
"city": "Denver",
"state_province": "CO",
"zip_postal_code": "80247",
"country": "USA"
},
"phone": "1231231234",
"npi": "0000000000",
"in_network_payers": []
},
"entity": {
"legal_name": "Test Entity",
"tax_id": "111223333"
},
"insurance": [
{
"scanned_content": {
"client_name": "Company",
"group_number": "12345678",
"member_name": "John Smith",
"member_number": "12345678",
"payer_name": "United",
"plan_name": "Plus Plan",
"rx_bin": "123456",
"rx_group": "ADV",
"rx_pcn": "FAC"
},
"discrete_content": {},
"url": "https://example.com/insurance_doc"
},
{
"scanned_content": {
"error": "Unable to extract information from card"
},
"discrete_content": {},
"url": "https://example.com/insurance_doc2"
}
],
"patient_coverage_status": "covered",
"verification_methods": [
{
"id": "bva_23j3234",
"type": "ai_call",
"transcript": "Call transcript",
"recording_url": "https://example.com/recording"
}
],
"patient_plan_fund_source": "question_not_asked",
"patient_coverage_type": "question_not_asked",
"priority": 2
}
}