Prior authorization statuses, outcomes, and errors

After creating a PA, save its ID and use the status-change webhook or GET /prior-authorization/{id} to follow its progress. Read data.status first, then data.outcome when processing finishes.

Lifecycle

`data.status`	Terminal	Meaning
`processing`	No	Develop Health is preparing the PA.
`awaiting_review`	No	Answers and evidence are ready for review before submission.
`awaiting_provider_response`	No	The provider needs to supply information or complete a review.
`awaiting_outcome`	No	Submission is underway or the PA is waiting for a payer result or follow-up.
`validating_outcome`	No	A received result is being checked. The PA may return to `awaiting_outcome` for follow-up.
`completed`	Yes	Processing finished with an `Approved`, `Denied`, or `Other` outcome.
`not_submitted`	Yes	The workflow stopped before submission. Read `outcome.detail_code` and `outcome.detail` for the reason.
`failed`	Yes	An internal processing failure stopped the PA. Use your manual PA process and contact support with the PA ID. No stable public failure-detail code is exposed.
`cancelled`	Yes	The request was cancelled and PA processing has stopped.

Approval and denial are normal business outcomes. A completed PA can also have an Other outcome, such as no PA being required or a duplicate request. Use the status to determine whether the PA is still running. The legacy outcome.result: "Pending" value is a placeholder.

Activity and requests for information

Calls, faxes, messages, and provider outreach can occur without changing the PA’s status. Use data.activity_log and the webhook events for those updates. An individual outreach attempt can fail or expire while the PA continues. A request for more information can also be part of an ongoing PA. Only treat the request as stopped when its status is terminal.

Request errors

If creation is rejected, read the HTTP status and error.code. Correct the request before trying again. If the response includes error.existing_prior_auth_request_id, it identifies the earlier PA associated with the error.

`error.code`	HTTP status	What to do
`evidence_file_download_failed`	`400`	An evidence file could not be downloaded. Correct the URL or provide the file as Base64 content, then retry.
`invalid_diagnosis_codes`	`400`	Correct the invalid ICD-10-CM diagnosis codes and retry.
`insurance_card_member_id_ocr_failure`	`400`	An insurance-card file could not be processed. Check its format and Base64 content, or provide structured insurance information, then retry.
`unsupported_drug`	`400`	The prescription could not be resolved from the supplied NDC. Check the NDC or provide the name-based prescription format. Use your manual PA process if the drug remains unsupported.
`other`	Varies	Read the error description. Use your manual PA process when needed and contact support if the correction is unclear.

Errors for resubmissions, provider outreach, and optional workflows are documented with those features. See sandbox testing for mock_result_not_allowed, common API errors for authentication and validation, and rate limits for quota and retry guidance.

Other result codes

When data.status is completed and data.outcome.result is Other, use data.outcome.detail_code and data.outcome.detail to decide what to do next. Several codes share the same action:

Code	Meaning and next step
`coverage_inactive` `coverage_not_yet_started` `no_pharmacy_benefits`	Check insurance. Coverage has expired, has not started, or does not include pharmacy benefits. Verify the patient’s current pharmacy coverage before starting another PA.
`payer_unable_to_locate_member` `payer_reported_invalid_patient_info`	Check patient details. The payer could not match the patient or reported mismatched information. Verify insurance details and patient demographics.
`npi_taxonomy_ineligible`	Check provider eligibility. Resolve the prescriber’s eligibility with the payer or use a provider with an accepted type, specialty, or credentials.
`duplicate_request`	Contact the plan. The payer has already completed a PA for this patient and coverage and will not reprocess it. Call the plan to resolve the duplicate.
`prior_auth_not_required`	Continue without a PA. No PA is needed for this medication. Check coverage and copay separately.
`patient_consent_required`	Resolve patient consent. Consent requirements prevented communication or processing with the insurer. Resolve consent with the plan before proceeding.
`more_information_required`	Add clinical information. Read the outcome detail, add the requested information or documentation, and resubmit the PA.
`other`	Review manually. Read the outcome detail and use your manual review process. Contact support with the PA ID if the next step is unclear.

Stopped before submission

For data.status: "not_submitted" with data.outcome.detail_code: "more_information_required", read the outcome detail and collect the missing information. Then create a new linked request through the resubmission path. Optional BV and formulary workflows can also stop a PA before submission. Their outcome codes are documented with those features.

Retrieve errors

GET /prior-authorization/{id} returns 404 when the PA does not exist or is not visible to the authenticated organization.

Unknown values

Treat code lists as extensible. Preserve unknown codes in logs and route unrecognized terminal outcomes to manual review, using the outcome detail for context. An unfamiliar code alone does not mean an ongoing PA has stopped.

API basics

Benefit verification