> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsolum.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a prior authorization from documents > Submit uploaded documents and optional data, then poll for the created prior authorization. This endpoint is available after the prior authorization requests backend release is enabled in your environment. Check your environment's API reference before integrating. Use `POST /v1/prior-authorization-requests` to extract uploaded documents and create a prior authorization asynchronously. Upload the files using the Files API first, then submit their IDs. You can supply any information you already know in `data`. ## Submit a request ```bash theme={null} curl -X POST "$SOLUM_API_URL/v1/prior-authorization-requests" \ -H "X-API-Key: $SOLUM_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: referral-2026-001" \ -d '{ "file_ids": ["5a86bb0a-3387-4963-b3f1-91cf8b3184b1"], "data": { "type": "treatment", "requesting_provider_id": "80934acb-b6f8-4bcf-bdf5-0aa2bb4f0404" } }' ``` The server returns `202 Accepted` and a `Location` header pointing to the request. Acceptance means the request was saved; extraction and creation may still fail. ```json theme={null} { "id": "3c6231dd-766e-4890-9001-ad9f2a31c3bf", "status": "queued", "prior_authorization_id": null, "error": null, "created_at": "2026-09-09T12:00:00Z", "updated_at": "2026-09-09T12:00:00Z", "completed_at": null } ``` `file_ids` accepts 1–15 distinct file IDs belonging to your company. Supported documents are PDF, PNG, and JPEG, with a combined size limit of 50 MB. Comment attachments, message attachments, and form-submission attachments are not accepted. Documents associated with a patient must belong to the patient ultimately selected for this prior authorization. ## Supply explicit data `data` uses the fields of the regular prior authorization creation request, with every field optional at submission. The service extracts the documents, overlays your explicit data, then validates the result using the regular creation rules. * Omitted fields retain extracted values. * Explicit values override extracted values. * Nested objects merge field by field. For example, a supplied `patient_data.date_of_birth` overrides that field while retaining extracted names. * Arrays replace the entire extracted array. * Explicit `null` clears an extracted value. Clearing a required value causes validation to fail. * `patient_id` selects an existing patient instead of extracted `patient_data`; `patient_policy_id` selects an existing coverage instead of extracted `policy_data`. Do not supply both alternatives in the same identity pair. Provider IDs are resolved only within your company. Ambiguous matches need an explicit ID. Documents that conflict with an explicitly selected patient's identity fail validation. Creation and document attachment succeed together; a failed operation does not leave a partially created prior authorization or a new patient created by that operation. ## Poll for the result ```bash theme={null} curl "$SOLUM_API_URL/v1/prior-authorization-requests/3c6231dd-766e-4890-9001-ad9f2a31c3bf" \ -H "X-API-Key: $SOLUM_API_KEY" ``` Poll every few seconds, increasing the interval for requests that take longer. Processing may take several minutes. Stop polling at either terminal state. | Status | Meaning | | ------------ | ------------------------------------------------------------------------------------------------------------------ | | `queued` | Accepted and waiting for processing. | | `processing` | Extraction or creation is running, or awaiting an internal retry. | | `completed` | The prior authorization and its document attachments were created. `prior_authorization_id` identifies the result. | | `failed` | The operation ended unsuccessfully. `error` describes the failure. | A successful retrieval returns `200 OK`, including when the operation itself failed. Polling responses contain status and safe error details, without document contents or the submitted clinical data. ```json theme={null} { "id": "3c6231dd-766e-4890-9001-ad9f2a31c3bf", "status": "failed", "prior_authorization_id": null, "error": { "code": "validation_failed", "message": "The merged data could not create a prior authorization.", "retryable": false, "fields": [ { "path": "data.requesting_provider_id", "code": "required", "message": "Provide a valid value for this field." } ] }, "created_at": "2026-09-09T12:00:00Z", "updated_at": "2026-09-09T12:01:00Z", "completed_at": "2026-09-09T12:01:00Z" } ``` A failed request is terminal, including one whose error is marked `retryable`. That flag indicates a transient failure for which a new submission may succeed. To correct missing or invalid information, submit a new request with the same files and corrected `data`. ## Retry submissions safely `Idempotency-Key` is optional and scoped to your company. Repeating the same key and normalized request payload returns the original request and its current status. Reusing the key with different input returns `409 Conflict`. The key remains reserved for the lifetime of the request; corrected submissions need a new key. Without a key, every submission creates an independent request and may create another prior authorization. Use the same key when retrying after a network timeout. Invalid input is rejected synchronously with `422`; unavailable source files return `404`. Errors discovered during extraction or final validation appear on the polled request. A request in another company is not visible and returns `404`. Request completion is available through polling. Completion webhooks are deferred. Existing patient-created webhooks and configured workflow actions still run when this operation creates a new patient; those actions are dispatched separately after the creation transaction commits.