Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Data · object
*
Required
object
Represents a request for creating a prior authorization for a medication. This includes detailed
information about the patient, their diagnosis, prescribed medication, evidence supporting the need for treatment,
insurance details, and responses to relevant questionnaires.
Add Example Value
is_training_data
Is Training Data · boolean
is_training_data
boolean
Whether this prior authorization request is for training purposes. If true, the request will not be sent through the standard workflow.
diagnoses
Diagnoses · array
*
diagnoses
Required
array
Clinical diagnoses for the patient in ICD-10 format. i.e. 'E66.9'
evidence
Evidence · array
evidence
array
A collection of evidence items supporting the authorization request. Any other supporting evidence that doesn't fit into one of the explicitly declared fields above can be added here.
patient
Patient · object
*
patient
Required
object
Demographic information for the patient
address
Address · object
*
address
Required
object
The patient's postal address
street
Street · string
*
street
Required
string
Street address of residence.
street_line_2
Street Line 2 · string
street_line_2
string
Additional street address information.
city
City · string
*
city
Required
string
City of residence.
state_province
State Province · string
*
state_province
Required
string
State or province of residence.
zip_postal_code
Zip Postal Code · string
*
zip_postal_code
Required
string
ZIP or postal code part of the address.
country
Country · string
*
country
Required
string
Country of residence.
date_of_birth
Date Of Birth · string
*
date_of_birth
Required
string
The patient's date of birth
email
Email · string
email
string
The patient's email address
first_name
First Name · string
*
first_name
Required
string
The patient's first name
last_name
Last Name · string
*
last_name
Required
string
The patient's last name
gender
Gender · enum<string>
*
gender
Required
enum<string>
The patient's gender
internal_id
Internal Id · string
*
internal_id
Required
string
Your internal ID for this patient. This is used for linking all of the requests for a given patient.
phone
Phone · string
phone
string
The patient's phone number
insurance
Insurance · array
insurance
array
Insurance information for the patient. We will extract the required information from the insurance card images you provide. Please provide both the front and the back of the card.
insurance_content
Insurance Content · object
insurance_content
object
Insurance information for the patient. Values provided here will be used in combination with those extracted from any insurance cards provided. We recommend providing this information when available to ensure best results.
client_name
Client Name · string
client_name
string
The client/employer name.
group_number
Group Number · string
group_number
string
The group number on the card.
member_name
Member Name · string
member_name
string
The member name on the card.
member_number
Member Number · string
member_number
string
The member number on the card.
payer_name
Payer Name · string
payer_name
string
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
plan_name
Plan Name · string
plan_name
string
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
rx_bin
Rx Bin · string
rx_bin
string
The Rx BIN number on the card.
rx_group
Rx Group · string
rx_group
string
The Rx group number on the card.
rx_pcn
Rx Pcn · string
rx_pcn
string
The Rx PCN number on the card.
prescription
Prescription · object
*
prescription
Required
object
Information regarding the prescription this prior authorization is being created for.
days_supply
Days Supply · integer
*
days_supply
Required
integer
The number of days the prescription will be expected to last.
quantity
Quantity · integer
*
quantity
Required
integer
The quantity of the medication.
directions
Directions · string
*
directions
Required
string
Instructions on how the medication should be taken.
drug_name
Drug Name · string
*
drug_name
Required
string
The name of the medication.
strength
Strength · string
*
strength
Required
string
The strength of the medication.
dose_form
DoseForm · enum<string>
*
dose_form
Required
enum<string>
The form of the medication.
dispense_unit
DispenseUnit · enum<string>
*
dispense_unit
Required
enum<string>
The unit of measurement for the medication.
route_of_administration
RouteOfAdministration · enum<string>
*
route_of_administration
Required
enum<string>
The route of administration for the medication.
extra
Extra · object
extra
object
An optional dictionary containing additional information related to the drug or future prescription.
prescription_date
Prescription Date · string
*
prescription_date
Required
string
The date the prescription was issued
provider
Provider · object
*
provider
Required
object
Details of the healthcare provider who created the prescription.
address
Address · object
*
address
Required
object
The provider's postal address.
street
Street · string
*
street
Required
string
Street address of residence.
street_line_2
Street Line 2 · string
street_line_2
string
Additional street address information.
city
City · string
*
city
Required
string
City of residence.
state_province
State Province · string
*
state_province
Required
string
State or province of residence.
zip_postal_code
Zip Postal Code · string
*
zip_postal_code
Required
string
ZIP or postal code part of the address.
country
Country · string
*
country
Required
string
Country of residence.
fax
Fax · string
fax
string
The provider's fax number.
first_name
First Name · string
*
first_name
Required
string
The provider's first name.
last_name
Last Name · string
*
last_name
Required
string
The provider's last name.
npi
Npi · string
*
npi
Required
string
The provider's NPI.
phone
Phone · string
phone
string
The provider's phone number.
pharmacy
Pharmacy · object
pharmacy
object
Information about the pharmacy where the prescription will be filled.
name
Name · string
*
name
Required
string
The name of the pharmacy.
address
Address · object
*
address
Required
object
Represents a postal address.
street
Street · string
*
street
Required
string
Street address of residence.
street_line_2
Street Line 2 · string
street_line_2
string
Additional street address information.
city
City · string
*
city
Required
string
City of residence.
state_province
State Province · string
*
state_province
Required
string
State or province of residence.
zip_postal_code
Zip Postal Code · string
*
zip_postal_code
Required
string
ZIP or postal code part of the address.
country
Country · string
*
country
Required
string
Country of residence.
questionnaires
Questionnaires · array
questionnaires
array
List of questionnaires. This is the best place to send structured Q&A format data, such as intake forms, etc.
visit_notes
Visit Notes · array
visit_notes
array
List of visit notes.
mock_result
Option 1 · object
mock_result
object
Specifies the simulated outcome for a completed prior authorization. Setting this field will instantly complete the prior authorization request and send a webhook with the value of this field. You will not be charged for these requests and you will not be sent the prior auth for manual review.
result
Result · enum<string>
result
enum<string>
The Prior Authorization has been approved.
detail_code
PriorAuthOutcomeApprovalDetail · enum<string>
detail_code
enum<string>
A code indicating the reason for the prior auth approval. The possible values are:
prior_auth_not_required: A prior authorization is not required.
approval: The prior authorization request has been approved.
This endpoint is designed to streamline the submission of prior authorization requests for medications or treatments. It requires various key pieces of information about the patient, including demographics, insurance details, and the prescription in question. Additionally, the submission should include supporting evidence, such as visit notes, lab results, and intake forms, to justify the need for the prescribed medication or treatment.
To effectively use this endpoint, please ensure the following information is included in your request:
Patient Demographics: Essential details such as the patient’s name, date of birth, and contact information.
Insurance Details: A photo or scan of the patient’s insurance card (preferably front and back), including the group number, payer, membership number and RX details. If an image is not available, or the patient provided extra information not on their card (such as rx codes) you can also provide this structured data in the API.
Prescription Information: Detailed data on the prescribed medication or treatment, such as drug name, dosage, and administration instructions.
Evidence: Critical supporting documents and data such as visit notes and laboratory results. This section is particularly versatile, allowing for a variety of formats and contents to support the authorization request.
Given the diverse nature of medical records and evidence, our API is built to accommodate a wide range of data formats. Structured data can be filled into predefined fields, while unstructured data, such as additional JSON content about the patient, can be included in the content block within the evidence objects. This flexibility ensures that even non-standardized data can be effectively utilized in the prior authorization process.
In the future we will support uploading files and scans, such as PDFs, images, and other documents, to the evidence section. Currently these are not utilized in the answering flow, but we will be adding support for them in the future. The API does support uploading these, and in a future version of our answering model they will be used.
We highly recommend you talk to a member of your company who actively submits prior authorizations when collecting the data for this endpoint. For the system to work effectively, we require the exact same data that those staff members currently have access to. A great test is to collect the data and see if the staff member is able to use that data alone to submit a new prior authorization through your existing system.
After submitting a request, the system processes the data and returns a response indicating either the successful reception of the request or detailing any errors or additional information needed. Our advanced AI algorithms will analyze the provided information, including any uploaded files or scans, extracting and utilizing relevant details to facilitate the authorization process.
You’ll notice in the response error section at the bottom of this page that there are several possible errors that can occur. Particularly during the ramp up period you’ll likely see the daily_prior_auth_request_limit_reached error. We’re still in the process of reaching 100% plan coverage, so seeing the unsupported_patient error is also expected. We want to make integrating as easy as possible, so the details of these error codes can generally be ignored. You’ll likely want to process them all the same way as detailed below.
We’d suggested taking the following approach when integrating:
Make the API request for all prior authorizations that you need to submit, and let us handle the ramp up on our end. i.e. We’d recommend not feature flagging or limiting this to certain patients. We have a daily limit that starts off at just 5 requests that we can increase rapidly. Using this approach allows us to work with your ops team to gradually increase the volume we handle as we see successful responses from the insurance companies.
If you receive an error code, fallback to your companies existing process for handling prior authorizations. We’ll gradually reduce the number of errors you receive as we ramp up to 100% coverage.
As a developer reading these docs we understand it might be difficult to know what data to provide and how best to structure it. Please know that we at Develop Health are here to help! A member of our engineering team will happily work with you to ensure you’re providing the right data in the right format.
Authorizations
Authorization
string
headerrequired
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
is_training_data
boolean
default: false
Whether this prior authorization request is for training purposes. If true, the request will not be sent through the standard workflow.
diagnoses
object[]
required
Clinical diagnoses for the patient in ICD-10 format. i.e. 'E66.9'
diagnoses.code
string
required
ICD-10 code for the diagnosis. i.e. 'E66.9'
evidence
object[]
A collection of evidence items supporting the authorization request. Any other supporting evidence that doesn't fit into one of the explicitly declared fields above can be added here.
evidence.content
object
Detailed content of the evidence, which varies based on the type of evidence.
evidence.date_created
string
required
The date and time (if available) when the evidence was created. This is important for ensuring we have an accurate timeline of the patient's history.
evidence.title
string
required
Title of the evidence. This will be shown to users in the platform UI so it's recommended to give it a name that would be meaningful to them, such as 'Intake Form'
patient
object
required
Demographic information for the patient
patient.address
object
required
The patient's postal address
patient.address.street
string
required
Street address of residence.
patient.address.street_line_2
string
Additional street address information.
patient.address.city
string
required
City of residence.
patient.address.state_province
string
required
State or province of residence.
patient.address.zip_postal_code
string
required
ZIP or postal code part of the address.
patient.address.country
string
required
Country of residence.
patient.date_of_birth
string
required
The patient's date of birth
patient.email
string
The patient's email address
patient.first_name
string
required
The patient's first name
patient.last_name
string
required
The patient's last name
patient.gender
enum<string>
required
The patient's gender
Available options:
male,
female,
other,
not_specified
patient.internal_id
string
required
Your internal ID for this patient. This is used for linking all of the requests for a given patient.
patient.phone
string
The patient's phone number
insurance
object[]
Insurance information for the patient. We will extract the required information from the insurance card images you provide. Please provide both the front and the back of the card.
insurance.file_content
string
required
insurance_content
object
Insurance information for the patient. Values provided here will be used in combination with those extracted from any insurance cards provided. We recommend providing this information when available to ensure best results.
insurance_content.client_name
string
The client/employer name.
insurance_content.group_number
string
The group number on the card.
insurance_content.member_name
string
The member name on the card.
insurance_content.member_number
string
The member number on the card.
insurance_content.payer_name
string
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
insurance_content.plan_name
string
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
insurance_content.rx_bin
string
The Rx BIN number on the card.
insurance_content.rx_group
string
The Rx group number on the card.
insurance_content.rx_pcn
string
The Rx PCN number on the card.
prescription
object
required
Information regarding the prescription this prior authorization is being created for.
prescription.days_supply
integer
required
The number of days the prescription will be expected to last.
prescription.quantity
integer
required
The quantity of the medication.
prescription.directions
string
required
Instructions on how the medication should be taken.
prescription.drug_name
string
required
The name of the medication.
prescription.strength
string
required
The strength of the medication.
prescription.dose_form
enum<string>
required
The form of the medication.
Available options:
tablet,
capsule,
suspension,
cream,
solution,
ointment,
suppository,
inhaler,
liquid,
powder,
injectable,
patch,
gel,
lozenge,
concentrate
prescription.dispense_unit
enum<string>
required
The unit of measurement for the medication.
Available options:
milliliter,
liter,
gram,
milligram,
microgram,
unit,
tablet,
capsule,
patch,
inhaler,
applicator,
pack,
vial
prescription.route_of_administration
enum<string>
required
The route of administration for the medication.
Available options:
oral,
subcutaneous,
intravenous,
intramuscular,
topical,
inhalation,
nasal,
ophthalmic,
otic,
rectal,
vaginal,
transdermal,
buccal,
sublingual
prescription.extra
object
An optional dictionary containing additional information related to the drug or future prescription.
prescription.prescription_date
string
required
The date the prescription was issued
provider
object
required
Details of the healthcare provider who created the prescription.
provider.address
object
required
The provider's postal address.
provider.address.street
string
required
Street address of residence.
provider.address.street_line_2
string
Additional street address information.
provider.address.city
string
required
City of residence.
provider.address.state_province
string
required
State or province of residence.
provider.address.zip_postal_code
string
required
ZIP or postal code part of the address.
provider.address.country
string
required
Country of residence.
provider.fax
string
The provider's fax number.
provider.first_name
string
required
The provider's first name.
provider.last_name
string
required
The provider's last name.
provider.npi
string
required
The provider's NPI.
provider.phone
string
The provider's phone number.
pharmacy
object
Information about the pharmacy where the prescription will be filled.
pharmacy.name
string
required
The name of the pharmacy.
pharmacy.address
object
required
Represents a postal address.
pharmacy.address.street
string
required
Street address of residence.
pharmacy.address.street_line_2
string
Additional street address information.
pharmacy.address.city
string
required
City of residence.
pharmacy.address.state_province
string
required
State or province of residence.
pharmacy.address.zip_postal_code
string
required
ZIP or postal code part of the address.
pharmacy.address.country
string
required
Country of residence.
questionnaires
object[]
List of questionnaires. This is the best place to send structured Q&A format data, such as intake forms, etc.
questionnaires.questions
object[]
required
A list of questions included in the questionnaire.
questionnaires.questions.answer
string
required
The answer to the question.
questionnaires.questions.choices
string[]
Optional list of choices for the question. If provided, the answer must be one of the choices. It's important to include this list of choices for any multiple choice question. This allows our AI to know what a user has effectively said 'no' to by picking another option. I.e. for a question 'Do you have any of the following conditions: Diabetes, Heart Disease, Cancer, None of the above' if the user answers 'None of the above' we can infer that they don't have any of those conditions. Without the choices list we would have no way of knowing that.
questionnaires.questions.question
string
required
The question to be answered.
questionnaires.date_created
string
required
The date and time when the questionnaire was answered. This is important for ensuring we have an accurate timeline of the patient's history.
visit_notes
object[]
List of visit notes.
visit_notes.title
string
The title of the visit note. This is optional and can be used to give the note a meaningful name, such as 'Initial Consultation'.
visit_notes.content
string
required
The content of the visit note.
visit_notes.date_created
string
required
The date and time (if available) when the visit note was created. This is important for ensuring we have an accurate timeline of the patient's history.
mock_result
object
Specifies the simulated outcome for a completed prior authorization. Setting this field will instantly complete the prior authorization request and send a webhook with the value of this field. You will not be charged for these requests and you will not be sent the prior auth for manual review.
mock_result.result
enum<string>
default: Approved
The Prior Authorization has been approved.
Available options:
Approved
mock_result.detail_code
enum<string>
A code indicating the reason for the prior auth approval. The possible values are:
prior_auth_not_required: A prior authorization is not required.
approval: The prior authorization request has been approved.
Available options:
prior_auth_not_required,
approval
Response
200 - application/json
status
Available options:
success
error
object
Error payload of the response, containing details of the error that occurred during the creation of the prior authorization request.
error.title
string
required
A brief title summarizing the error.
error.description
string
A detailed message explaining the error. These messages may be unique to the specific prior authorization request.
error.code
enum<string>
required
A specific code identifying the error. While we'll aim to ensure that the occurence of these errors is minimal, it's likely they will occur. To prevent delays to patient care, we generally recommend that you implement a strategy of falling back to your existing process for handling a prior authorization if you encounter one of these errors. The Develop Health team will then work with you in parallel to fix the issue. The following codes are currently possible:
unsupported_patient: This means that the patient you submitted the prior authorization for is not currently supported. We're rapidly increasing our PBM and payer coverage, so we'll be reducing the occurrence of these over time.
unsupported_drug: The drug you submitted is not yet supported for prior authorization.
daily_prior_auth_request_limit_reached: The daily limit for prior authorization requests has been reached. There is a temporary limit set on new accounts to ensure that submissions are accurate before we allow unlimited submissions. The Develop Health team will work with you to increase this limit as quickly as possible.
daily_prior_auth_request_new_plan_limit_reached: The daily limit for prior authorization requests for new plans has been reached. As we increase our payer and plan coverage this limit ensures that submissions are accurate before we allow unlimited submissions.
insurance_card_member_id_ocr_failure: We were unable to extract the member ID from the insurance card image provided and no discrete values were provided.
other: An unexpected error occurred during the prior authorization process.
Available options:
unsupported_patient,
unsupported_drug,
daily_prior_auth_request_limit_reached,
daily_prior_auth_request_new_plan_limit_reached,
insurance_card_member_id_ocr_failure,
other
data
object
Data payload of the response, containing details of the created prior authorization request, or None if the request was unsuccessful.
data.id
string
required
The unique identifier for the created prior authorization request.
