> ## Documentation Index
> Fetch the complete documentation index at: https://docs.develophealth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a prior authorization

> Required PA inputs, prescription quantities, and ways to send clinical evidence.

Create a PA with `POST /prior-authorization`. The same endpoint supports
[delegated and non-delegated workflows](/api-reference/prior-authorization/overview).
Your organization's configuration determines who reviews and submits the PA.

## Example sandbox request

<Accordion title="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`:

  ```json theme={null}
  {
    "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"
    }
  }
  ```

  ```bash theme={null}
  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}`](/api-reference/prior-authorization/get_item)
  with that ID or handle `prior_authorization.status_change` webhooks. See
  [sandbox testing](/guides/testing#simulate-prior-authorization-outcomes) for
  denial and not-submitted scenarios.
</Accordion>

## 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](#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](#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](/api-reference/prior-authorization/overview#what-your-application-needs-to-do).

Incomplete clinical data can prevent submission after the API accepts a request.

See [optional workflows](#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:

```json theme={null}
{
  "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](#clinical-evidence) have different
format rules. Use `evidence` for medical records and other
supporting documents.

### Read extracted insurance data

[`GET /prior-authorization/{id}`](/api-reference/prior-authorization/get_item) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](#upload-insurance-cards) 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](/api-reference/prior-authorization/post) 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](/api-reference/prior-authorization/overview#what-your-application-needs-to-do).
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](#optional-workflows). Use the
[PA response guide](/api-reference/prior-authorization/response-handling)
for the exact state and outcome handling rules.

## Optional workflows

<Accordion title="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](/api-reference/prior-authorization/post) 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. |
</Accordion>

<Accordion title="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](/api-reference/provider-outreach-webhooks)
  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. |
</Accordion>

<Accordion title="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](/api-reference/prior-authorization/post) 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. |
</Accordion>

<Accordion title="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.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.