> ## 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. # Request a prior authorization from documents > Extract uploaded files, apply explicit data, and create a prior authorization asynchronously. Poll the Location URL until completed or failed. ## OpenAPI ````yaml https://api.getsolum.com/openapi.json post /v1/prior-authorization-requests openapi: 3.1.0 info: title: Solum Health API description: '## Solum Health Backend API ' version: 1.0.0 servers: [] security: [] paths: /v1/prior-authorization-requests: post: tags: - Prior Authorization Requests summary: Request a prior authorization from documents description: >- Extract uploaded files, apply explicit data, and create a prior authorization asynchronously. Poll the Location URL until completed or failed. operationId: create_request_v1_prior_authorization_requests_post parameters: - name: idempotency-key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Optional durable submission key. Reuse with identical input to retrieve the same request; use a new key for corrected input. title: Idempotency-Key description: >- Optional durable submission key. Reuse with identical input to retrieve the same request; use a new key for corrected input. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestCreate' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RequestView' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict '422': description: Validation Error content: application/json: schema: type: object properties: type: type: string example: validation_error code: type: string example: invalid_parameter message: type: string example: Field validation failed param: type: string example: phone_number required: - type - code - message security: - APIKeyHeader: [] - HTTPBearer: [] components: schemas: RequestCreate: properties: file_ids: items: type: string format: uuid type: array maxItems: 15 minItems: 1 title: File Ids data: $ref: '#/components/schemas/PartialPriorAuthorization' additionalProperties: false type: object required: - file_ids title: RequestCreate RequestView: properties: id: type: string format: uuid title: Id status: $ref: '#/components/schemas/AsyncOperationStatus' prior_authorization_id: anyOf: - type: string format: uuid - type: 'null' title: Prior Authorization Id error: anyOf: - $ref: '#/components/schemas/RequestError' - type: 'null' created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At additionalProperties: false type: object required: - id - status - prior_authorization_id - error - created_at - updated_at - completed_at title: RequestView ErrorResponse: properties: type: type: string title: Type code: type: string title: Code message: type: string title: Message param: anyOf: - type: string - type: 'null' title: Param meta: anyOf: - additionalProperties: true type: object - type: 'null' title: Meta additionalProperties: false type: object required: - type - code - message title: ErrorResponse description: >- Clean error response schema following RFC 7807 inspired format. Error is returned directly without wrapper, with all fields in snake_case. Fields: - type: Error category (e.g., "validation_error", "resource_error") - code: Specific error code (e.g., "resource_missing", "invalid_field") - message: Human-readable error message - param: The parameter that caused the error (optional) - meta: Generic free-form bag for resource-specific context (optional). For 409 resource_conflict responses the conflicting resource is nested here under the resource-specific key, e.g. ``meta.existing_patient``. PartialPriorAuthorization: properties: type: anyOf: - $ref: '#/components/schemas/PriorAuthorizationTypeEnum' - type: 'null' patient_id: anyOf: - type: string format: uuid - type: 'null' title: Patient Id patient_data: anyOf: - $ref: '#/components/schemas/PartialPatient' - type: 'null' payor_id: anyOf: - type: string format: uuid - type: 'null' title: Payor Id payor_data: anyOf: - $ref: '#/components/schemas/PartialPayor' - type: 'null' service: anyOf: - $ref: '#/components/schemas/PartialService' - type: 'null' requesting_provider_id: anyOf: - type: string format: uuid - type: 'null' title: Requesting Provider Id servicing_provider_id: anyOf: - type: string format: uuid - type: 'null' title: Servicing Provider Id servicing_location_id: anyOf: - type: string format: uuid - type: 'null' title: Servicing Location Id organization_id: anyOf: - type: string format: uuid - type: 'null' title: Organization Id notes: anyOf: - type: string - type: 'null' title: Notes external_id: anyOf: - type: string maxLength: 255 - type: 'null' title: External Id scheduled_submission_date: anyOf: - type: string format: date - type: 'null' title: Scheduled Submission Date copy_files_from_prior_authorization_id: anyOf: - type: string format: uuid - type: 'null' title: Copy Files From Prior Authorization Id additionalProperties: false type: object title: PartialPriorAuthorization AsyncOperationStatus: type: string enum: - queued - processing - completed - failed title: AsyncOperationStatus RequestError: properties: code: type: string title: Code message: type: string title: Message retryable: type: boolean title: Retryable fields: items: $ref: '#/components/schemas/FieldError' type: array title: Fields additionalProperties: false type: object required: - code - message - retryable title: RequestError PriorAuthorizationTypeEnum: type: string enum: - assessment - treatment - reassessment - reassessment_and_treatment title: PriorAuthorizationTypeEnum description: Authorization type. PartialPatient: properties: first_name: anyOf: - type: string - type: 'null' title: First Name last_name: anyOf: - type: string - type: 'null' title: Last Name date_of_birth: anyOf: - type: string format: date - type: 'null' title: Date Of Birth additionalProperties: false type: object title: PartialPatient PartialPayor: properties: insurance_id: anyOf: - type: string format: uuid - type: 'null' title: Insurance Id member_id: anyOf: - type: string - type: 'null' title: Member Id insurance_display_name: anyOf: - type: string - type: 'null' title: Insurance Display Name additionalProperties: false type: object title: PartialPayor PartialService: properties: specialty: anyOf: - $ref: '#/components/schemas/PriorAuthorizationSpecialtyEnum' - type: 'null' description: Clinical specialty the authorization covers. examples: - aba service_type_codes: anyOf: - items: $ref: '#/components/schemas/ServiceType' type: array - type: 'null' title: Service Type Codes description: Service types the authorization covers. examples: - - mental_health_provider_outpatient start_date: anyOf: - type: string format: date - type: 'null' title: Start Date description: Requested service start date (`YYYY-MM-DD`). examples: - '2025-01-01' end_date: anyOf: - type: string format: date - type: 'null' title: End Date description: >- Requested service end date (`YYYY-MM-DD`). Send `null` for open-ended requests where the payor will set the end date in the approval. examples: - '2025-12-31' cpt_codes: anyOf: - items: $ref: '#/components/schemas/ServiceCptCode' type: array - type: 'null' title: Cpt Codes description: Requested CPT/HCPCS codes paired with unit counts. examples: - - code: '97153' units: '160' requested_visits: anyOf: - type: integer maximum: 100000 minimum: 0 - type: 'null' title: Requested Visits description: >- Requested number of visits. Optional — used by therapy disciplines (physical / occupational / speech therapy) whose authorizations are granted by visit count rather than a fixed coverage block. Decoupled from `cpt_codes` (a payor may authorize visits with no CPT code). examples: - 20 requested_weeks: anyOf: - type: integer maximum: 100000 minimum: 0 - type: 'null' title: Requested Weeks description: >- Requested number of weeks the services span. Optional — captured alongside `requested_visits` for visit-based therapy authorizations. Does not drive the end date. examples: - 8 visits_last_90_days: anyOf: - type: integer maximum: 100000 minimum: 0 - type: 'null' title: Visits Last 90 Days description: >- Number of visits the patient already had in the 90 days before this request. Optional — payors ask for it on therapy re-authorizations. Entered by the caller; Solum does not compute it. examples: - 14 locations: anyOf: - items: $ref: '#/components/schemas/PlaceOfService' type: array - type: 'null' title: Locations description: >- Places of service requested for this authorization (CMS POS categories). examples: - - office - home additionalProperties: false type: object title: PartialService FieldError: properties: path: type: string title: Path code: type: string title: Code message: type: string title: Message additionalProperties: false type: object required: - path - code - message title: FieldError PriorAuthorizationSpecialtyEnum: type: string enum: - aba - speech_therapy - occupational_therapy - physical_therapy - mental_behavioral_health title: PriorAuthorizationSpecialtyEnum description: Clinical specialty the authorization covers. ServiceType: type: string enum: - medical_care - surgical - consultation - diagnostic_x_ray - diagnostic_lab - radiation_therapy - anesthesia - surgical_assistance - other_medical - blood_charges - used_durable_medical_equipment - durable_medical_equipment_purchase - ambulatory_service_center_facility - renal_supplies_in_home - alternate_method_dialysis - chronic_renal_disease_equipment - pre_admission_testing - durable_medical_equipment_rental - pneumonia_vaccine - second_surgical_opinion - third_surgical_opinion - social_work - diagnostic_dental - periodontics - restorative - endodontics - maxillofacial_prosthetics - adjunctive_dental_services - health_benefit_plan_coverage - plan_waiting_period - chiropractic - chiropractic_office_visits - dental_care - dental_crowns - dental_accident - orthodontics - prosthodontics - oral_surgery - routine_preventive_dental - home_health_care - home_health_prescriptions - home_health_visits - hospice - respite_care - hospital - hospital_inpatient - hospital_room_and_board - hospital_outpatient - hospital_emergency_accident - hospital_emergency_medical - hospital_ambulatory_surgical - long_term_care - major_medical - medically_related_transportation - air_transportation - cabulance - licensed_ambulance - general_benefits - in_vitro_fertilization - mri_cat_scan - donor_procedures - acupuncture - newborn_care - pathology - smoking_cessation - well_baby_care - maternity - transplants - audiology_exam - inhalation_therapy - diagnostic_medical - private_duty_nursing - prosthetic_device - dialysis - otological_exam - chemotherapy - allergy_testing - immunizations - routine_physical - family_planning - infertility - abortion - aids - emergency_services - cancer - pharmacy - free_standing_prescription_drug - mail_order_prescription_drug - brand_name_prescription_drug - generic_prescription_drug - podiatry - podiatry_office_visits - podiatry_nursing_home_visits - professional_physician - anesthesiologist - professional_visit_office - professional_visit_inpatient - professional_visit_outpatient - professional_visit_nursing_home - professional_visit_skilled_nursing_facility - professional_visit_home - psychiatric - psychiatric_room_and_board - psychotherapy - psychiatric_inpatient - psychiatric_outpatient - rehabilitation - rehabilitation_room_and_board - rehabilitation_inpatient - rehabilitation_outpatient - occupational_therapy - physical_medicine - speech_therapy - skilled_nursing_care - skilled_nursing_care_room_and_board - substance_abuse - alcoholism - drug_addiction - vision_optometry - frames - routine_exam - lenses - nonmedically_necessary_physical - experimental_drug_therapy - burn_care - brand_name_prescription_drug_formulary - brand_name_prescription_drug_non_formulary - independent_medical_evaluation - partial_hospitalization_psychiatric - day_care_psychiatric - cognitive_therapy - massage_therapy - pulmonary_rehabilitation - cardiac_rehabilitation - pediatric - nursery - skin - orthopedic - cardiac - lymphatic - gastrointestinal - endocrine - neurology - eye - invasive_procedures - gynecological - obstetrical - obstetrical_gynecological - mail_order_prescription_drug_brand_name - mail_order_prescription_drug_generic - physician_visit_office_sick - physician_visit_office_well - coronary_care - private_duty_nursing_inpatient - private_duty_nursing_home - surgical_benefits_professional - surgical_benefits_facility - mental_health_provider_inpatient - mental_health_provider_outpatient - mental_health_facility_inpatient - mental_health_facility_outpatient - substance_abuse_facility_inpatient - substance_abuse_facility_outpatient - screening_x_ray - screening_laboratory - mammogram_high_risk_patient - mammogram_low_risk_patient - flu_vaccination - eyewear_and_accessories - case_management - dermatology - durable_medical_equipment - diabetic_supplies - generic_prescription_drug_formulary - generic_prescription_drug_non_formulary - allergy - intensive_care - mental_health - neonatal_intensive_care - oncology - physical_therapy - pulmonary - renal - residential_psychiatric_treatment - transitional_care - transitional_nursery_care - urgent_care title: ServiceType description: |- X12 Service Type — human-readable enum values stored in the database. See app/utils/service_type_mapping.py for code-to-type mappings. ServiceCptCode: properties: code: type: string title: Code description: CPT or HCPCS procedure code. units: type: string title: Units description: >- Quantity for this code. Stored as a string because some payors permit non-integer quantities (e.g. `0.5` hours of evaluation). unit_type: $ref: '#/components/schemas/PriorAuthorizationUnitTypeEnum' description: >- What the quantity is measured in — `units`, `visits`, or `hours`. Defaults to `units`; entries created before this field existed read back as `units`. default: units modifiers: anyOf: - items: $ref: '#/components/schemas/CptModifier' type: array - type: 'null' title: Modifiers description: >- CPT/HCPCS modifiers that apply to this code (e.g. `95`, `gt`, `ep`). Alphabetic input is case-insensitive and surrounding whitespace is trimmed; responses return lowercase values (e.g. `ep`). Optional — entries created before this field existed omit it and read back as `None`. type: object required: - code - units title: ServiceCptCode description: CPT/HCPCS input with validated, canonical modifier values. PlaceOfService: type: string enum: - telehealth_other_home - school - telehealth_home - office - home - independent_clinic - community_mental_health_center - other title: PlaceOfService description: CMS Place of Service categories. Wire values are the snake_case keys. PriorAuthorizationUnitTypeEnum: type: string enum: - units - visits - hours title: PriorAuthorizationUnitTypeEnum description: >- Quantity unit a CPT/HCPCS line is measured in. Lives inside the `service_cpt_codes` / `result_cpt_codes` JSON (not a dedicated column), so this is a plain str Enum with no `__pg_type__`. Old rows predate the field — readers default a missing value to `units`. Wire values mirror the Prisma `PriorAuthorizationUnitType` enum (`units` / `visits` / `hours`); keep them in sync by hand (the `...Enum` suffix here intentionally keeps this out of `verify-enum-sync`'s name-matched set, same as the other PA enums). CptModifier: type: string enum: - cf - ep - hm - ho - hn - ad - ae - pt - af - ot - hp - gt - u1 - u2 - u3 - u4 - u5 - u6 - u7 - u8 - gp - go - gn - cq - co - kx - gq - fq - ga - gx - gy - gz - lt - rt - xe - xs - xu - '59' - '76' - '77' - '93' - '95' - '96' - '97' title: CptModifier description: >- CPT/HCPCS modifiers appended to default codes. Matches Prisma @@map("cpt_modifier"). PROVISIONAL value set observed in the ops playbook — confirm the closed list with ops before relying on it; if open-ended, switch the column to String[]. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key HTTPBearer: type: http scheme: bearer ````