Create a prior authorization from documents

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

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.

{
  "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

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.

{
  "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.

Start Here

Account

API

Webhooks

Basic Configuration

Patients

AI Assistants

Insurance & Eligibility

Prior Authorizations

Create a prior authorization from documents

Submit a request

Supply explicit data

Poll for the result

Retry submissions safely

​Submit a request

​Supply explicit data

​Poll for the result

​Retry submissions safely

Submit a request

Supply explicit data

Poll for the result

Retry submissions safely