Create a prior authorization

Create a PA with POST /prior-authorization. The same endpoint supports delegated and non-delegated workflows. Your organization’s configuration determines who reviews and submits the PA.

Example sandbox request

View example request

Use this synthetic request with a sandbox organization’s token. It sends a name-based prescription and clinical evidence, with a mock outcome for testing. The provider identifier is illustrative; use your configured sandbox test provider if your workflow requires one.Save this as pa-request.json:

{
  "patient": {
    "internal_id": "sandbox-patient-001",
    "first_name": "Jamie",
    "last_name": "Example",
    "date_of_birth": "1990-01-15",
    "gender": "female",
    "address": {
      "street": "123 Example Street",
      "city": "San Francisco",
      "state_province": "CA",
      "zip_postal_code": "94107"
    }
  },
  "provider": {
    "first_name": "Alex",
    "last_name": "Example",
    "npi": "1234567893",
    "address": {
      "street": "456 Example Avenue",
      "city": "San Francisco",
      "state_province": "CA",
      "zip_postal_code": "94107"
    }
  },
  "insurance_content": {
    "member_number": "SANDBOX001",
    "rx_bin": "012345",
    "rx_pcn": "TESTPCN",
    "rx_group": "TESTGROUP",
    "payer_name": "Example Health Plan",
    "plan_name": "Example Pharmacy Plan"
  },
  "prescription": {
    "drug_name": "Metformin",
    "strength": "500 mg",
    "dose_form": "tablet",
    "route_of_administration": "oral",
    "quantity": 30,
    "days_supply": 30,
    "directions": "Take one tablet by mouth daily.",
    "prescription_date": "2026-09-01T10:00:00Z"
  },
  "evidence": [
    {
      "title": "Sandbox visit note",
      "date_created": "2026-09-01T10:00:00Z",
      "content": "Synthetic integration test. The clinician reviewed the medication history and recorded the treatment plan."
    }
  ],
  "mock_result": {
    "result": "Approved",
    "detail_code": "approval"
  }
}

curl https://api.develophealth.ai/prior-authorization \
  -H "Authorization: Bearer $DEVELOP_HEALTH_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @pa-request.json

Store the returned data.id. To track the PA, call GET /prior-authorization/{id} with that ID or handle prior_authorization.status_change webhooks. See sandbox testing for denial and not-submitted scenarios.

Required and recommended inputs

Field	Requirement	What to provide
`patient`	Required	Stable `internal_id`, first and last name, date of birth, gender, and complete address; phone and email when available
`provider`	Required	Prescriber’s first and last name, NPI, and address object; provide complete address and contact details when available
`insurance` or `insurance_content`	At least one is required	Prefer member ID with Rx BIN, PCN, and group. See insurance for alternatives
`prescription`	Required for this workflow	Coded or name-based prescription, as described below
`diagnoses`	Recommended	Relevant ICD-10 codes, each in an object with a `code` field
`evidence`	Recommended	Clinical information your PA team needs to support this prescription. See clinical evidence for supported formats
`pharmacy`	Optional	Dispensing pharmacy information when available

If diagnoses is omitted, we’ll try to extract diagnoses from the evidence you provide. If we can’t extract them, they must be added during PA review. Incomplete clinical data can prevent submission after the API accepts a request. See optional workflows for resubmissions, appeals, provider outreach, and benefit verification before PA submission.

Patient and provider data

Addresses

The patient requires a complete address with:

street
city
state_province, using a valid US state
zip_postal_code, as a string so leading zeros are preserved

street_line_2 is optional and country defaults to USA. Use the patient’s current address as recorded with their insurer. The provider’s address object is required, but its individual fields are optional. Send a complete address when available to help with payer matching and follow-up.

Gender

patient.gender is required and accepts male, female, other, or not_specified. Use not_specified when the information has not been provided. Send known information that matches the payer record. Missing demographics can affect matching and cause delays or inaccurate results.

Patient identifiers

Use a stable patient.internal_id for the same patient across BV and PA requests. Store each returned PA ID separately so you can associate webhook updates with the correct workflow. The patient ID does not deduplicate create requests.

Provider details

Send the prescribing provider’s NPI. Provide the provider’s phone and fax when available. The fax number is required when requesting provider outreach. The PA create request has no top-level entity field for a legal entity name or tax ID.

Insurance

Provide at least one of insurance (card images) or insurance_content (structured details). You can send both. For insurance_content, prioritize the member ID and pharmacy routing codes:

Preferred: Member ID with Rx BIN, Rx PCN, and Rx group.
Some Rx codes missing: Member ID with every Rx code you have, plus payer and plan names.
No Rx codes available: Member ID with payer and plan names.

Field	What to send
`member_number`	The member ID on the card, preserved as a string
`rx_bin`	The six-digit pharmacy routing BIN, as a string to preserve leading zeros
`rx_pcn`	The pharmacy processor control number
`rx_group`	The pharmacy benefit group identifier; keep it separate from `group_number`
`payer_name`	The payer name as shown on the card, as free text
`plan_name`	The plan name as shown on the card
`member_name`	The member name on the card, when available
`group_number`	The group number on the card, when available
`client_name`	The employer or client name, when shown

Upload insurance cards

Send each card side as a separate item in insurance, with the file bytes encoded as Base64 in file_content. Insurance-card uploads require file contents; download URLs are unsupported. Replace these placeholders with Base64-encoded files:

{
  "insurance": [
    { "file_content": "BASE64_FRONT_OF_CARD" },
    { "file_content": "BASE64_BACK_OF_CARD" }
  ]
}

Supported formats are JPEG/JPG, PNG, TIFF, BMP, HEIC, or a single-page PDF. Keep each decoded insurance-card image below 4 MiB (4,194,304 bytes) before Base64 encoding. Resize larger images before uploading. This size guidance applies only to decoded insurance-card images. Send each PDF card side as a single-page file. Insurance cards and clinical evidence have different format rules. Use evidence for medical records and other supporting documents.

Read extracted insurance data

GET /prior-authorization/{id} returns insurance records in data.insurance. Each record uses discrete_content for the values you supplied and scanned_content for values extracted from card images.

Prescription and quantity

Prefer CodedPrescription when you have an NDC:

Format	Drug fields
`CodedPrescription`	`ndc`
`Prescription` (name-based)	`drug_name`, `strength`, `dose_form`, `route_of_administration`

Both formats also require directions, quantity, days_supply, and prescription_date.

Field	Meaning
`quantity`	The prescribed quantity; both PA prescription formats use an integer
`quantity_unit_of_measure`	Available on `CodedPrescription`; accepts an NCIt code or term from subset C89510 and defaults to `C38046` (Unspecified)
`days_supply`	How many days the prescription is expected to last
`directions`	Administration instructions from the prescription
`prescription_date`	When the prescription was issued, as an ISO 8601 date-time

Use the quantity and unit from the prescription when the chosen format can represent them. The name-based format has no quantity_unit_of_measure field, and neither format represents fractional quantities in its integer quantity field. For fractional quantities or ambiguous product presentations, confirm a supported mapping with Develop Health before sending the request. Do not round, assume an NDC supplies the unit, or use days_supply as a substitute. BV quantity examples do not define PA dispensing units.

Clinical evidence

Use evidence as the primary field for clinical information. Send chart notes, diagnoses, laboratory results, medication history, and prior treatment outcomes as text, structured JSON, or files. Include relevant dates and the information your PA team would use for the same request. Each item requires title, date_created, and either content or asset.

Text or structured evidence

An evidence item’s content can be text or a JSON object. For example, this synthetic item preserves treatment dates and the recorded response:

{
  "title": "Prior treatment history",
  "date_created": "2026-09-01T10:00:00Z",
  "content": {
    "medication": "Example prior therapy",
    "start_date": "2026-01-15",
    "end_date": "2026-06-15",
    "response": "Treatment stopped because of the adverse effects recorded in the visit note."
  }
}

date_created is the item’s creation time. If you also send evidence.document_date, use the clinical/source document date from a trusted record. Do not substitute upload, export, or ingestion time for that field.

File evidence

For a file, use asset. An asset takes exactly one of file_content (Base64 bytes) or file_url (a downloadable URL). This example shows the shape; replace the placeholder before sending:

{
  "title": "Clinical note",
  "date_created": "2026-09-01T10:00:00Z",
  "asset": {
    "file_content": "BASE64_DOCUMENT_CONTENT"
  }
}

Supported evidence formats are PDF, JPEG, PNG, HEIC, and HEIF. Convert Word, spreadsheet, TIFF, or BMP evidence to a supported format. The broader insurance-card format list does not apply to clinical evidence. For URL-based evidence, the service downloads the file immediately. A signed URL must remain valid and accessible for that download; a URL requiring an interactive sign-in will not work. If it fails, correct the URL or provide Base64 content. Do not send both asset and content for the same item, or both file fields in one asset. The API also accepts visit_notes and questionnaires. See the API reference for their formats.

Handle missing information and review

Track the PA after creation. When a non-delegated PA reaches awaiting_review, follow the PA review step. A PA waiting for provider information can remain in progress. If it stops at not_submitted with more_information_required, read the outcome detail and collect the missing information, then create a new linked request through the resubmission path. Use the PA response guide for the exact state and outcome handling rules.

Optional workflows

Resubmissions and appeals

To resubmit a PA, send a new request with the updated information. Set resubmission_info.previous_prior_auth_request_id to the original PA ID and use resubmission_info.note to explain what changed. The original PA must be in a terminal state.For an appeal, also include appeal_details with the appeal letter and urgency. The resubmission note is optional when appeal details are provided. See the create reference for the field formats.

`error.code`	HTTP status	What to do
`previous_pa_request_in_progress`	`409`	The referenced PA is still running. Wait for it to finish, or cancel it if it should stop, before creating the linked request. `error.existing_prior_auth_request_id` identifies it.
`invalid_qle_resubmission`	`400`	A quantity-limit exception must reference a PA that was approved or marked PA-not-required. Check the referenced PA and use `quantity_limit_exception_reason` only for that case.
`appeal_not_allowed`	`400`	The original PA was routed through the Medicare GLP-1 Bridge, which does not accept appeals. Send a new request with updated clinical information instead.

Provider outreach

Pharmacy organizations can set provider_outreach.enabled: true to request clinical documents from the prescriber before PA preparation continues. Include provider.fax. Use provider outreach events to follow communications and the PA status to track the overall request.

`error.code`	What to do
`provider_outreach_not_supported`	This organization is not configured as a pharmacy. Remove `provider_outreach`, or contact support if the organization configuration is incorrect.
`provider_outreach_fax_required`	Supply the prescriber’s fax number in `provider.fax` and retry.
`invalid_npi`	The outreach request’s provider NPI could not be validated in the NPI registry. Correct it and retry.
`provider_outreach_mock_result_conflict`	Send provider outreach and simulated outcomes in separate requests. Remove `mock_result` to test outreach.

Benefit verification before PA submission

Set trigger_benefit_verification.enabled: true to check medication coverage before proceeding with the PA. You can include alternatives in trigger_benefit_verification.additional_medications. See the create reference for the request format.When this workflow stops the PA, its status is not_submitted. Read outcome.detail_code and the benefit verification result:

`outcome.detail_code`	Meaning and next step
`benefit_verification_no_medication_coverage`	The prescribed medication is not covered. When configured to stop on this result, the PA ends before submission. Review the BV and consider an alternative or manual review.
`benefit_verification_only_alternative_medication_covered`	Only a submitted alternative is covered. Review it with the prescriber and create the appropriate request if treatment changes.
`benefit_verification_pa_not_required`	The medication is covered and no PA is required. Continue your workflow and review the BV for coverage and copay details.

Formulary alternatives

Some configured workflows check whether a formulary alternative is required before submitting a PA. If the PA stops with not_submitted and outcome.detail_code: "formulary_alternative_required", read the outcome detail for the alternative. Review it with the prescriber and create the appropriate request if treatment changes.

Start here

Benefit verification

Prior authorization

Integration

Create a prior authorization

Example sandbox request

Required and recommended inputs

Patient and provider data

Addresses

Gender

Patient identifiers

Provider details

Insurance

Upload insurance cards

Read extracted insurance data

Prescription and quantity

Clinical evidence

Text or structured evidence

File evidence

Handle missing information and review

Optional workflows

​Example sandbox request

​Required and recommended inputs

​Patient and provider data

​Addresses

​Gender

​Patient identifiers

​Provider details

​Insurance

​Upload insurance cards

​Read extracted insurance data

​Prescription and quantity

​Clinical evidence

​Text or structured evidence

​File evidence

​Handle missing information and review

​Optional workflows

Example sandbox request

Required and recommended inputs

Patient and provider data

Addresses

Gender

Patient identifiers

Provider details

Insurance

Upload insurance cards

Read extracted insurance data

Prescription and quantity

Clinical evidence

Text or structured evidence

File evidence

Handle missing information and review

Optional workflows