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

# Document Validation Overview

> Validate clinical documentation against payor and provider rules before prior authorization submission

## What is Document Validation?

Document Validation evaluates clinical documentation **before** a prior authorization is submitted to a payor. It analyzes uploaded documents against validation rules to catch issues - missing signatures, outdated assessments, mismatched diagnosis codes - before they cause denials. Validation does not prevent submission as you can always proceed with creating and submitting a prior authorization, regardless of whether all rules pass.

Rules come from two sources:

* **Payor rules** - Managed by Silna based on each payor's specific requirements for a given specialty and document type.
* **Provider rules** - Self-configured by providers in the **Automation** tab of the Provider Overview in the Silna portal. These let providers enforce their own documentation standards on top of payor requirements.

## How It Works

Document Validation validates documents automatically when you upload them during a [PATCH (Update) Prior Authorization](/api-reference/v1priorauthorizationresource/update-prior-authorization) request. Validation typically completes in **30 to 45 seconds**.

### Validation Flow

```mermaid theme={null}
flowchart TD
    A["Client uploads documents via<br/>PATCH Update Prior Authorization"] --> B["Silna identifies applicable<br/>validation rules"]
    B --> C["Documents analyzed against<br/>payor and provider rule sets"]
    C --> D{"All rules<br/>pass?"}
    D -->|Yes| E["ALL_REQUIRED_DATA_RECEIVED"]
    D -->|No| F["DATA_REQUESTED<br/>with failed rule details"]
    F --> G{"Fix or<br/>proceed?"}
    G -->|Fix| H["Client fixes documents<br/>and re-uploads"]
    H --> A
    G -->|Proceed anyway| I["Disable validation for<br/>document type or skip via<br/>skip_document_intelligence flag"]
    I --> E

    style D fill:#e8daef,stroke:#333
    style E fill:#d4edda,stroke:#333
    style F fill:#f8d7da,stroke:#333
    style G fill:#fff3cd,stroke:#333
    style I fill:#cce5ff,stroke:#333
```

<Info>
  Validation failures do **not** prevent you from moving forward with creating a prior authorization. If you choose to proceed despite failures, you can either [disable validation for specific document types](#overriding-validations) or set `skip_document_intelligence: true` on your next PATCH request. The prior authorization will then advance to `ALL_REQUIRED_DATA_RECEIVED` as normal.
</Info>

### Integration Steps

1. **Upload documents** - Call [PATCH Prior Authorization](/api-reference/v1priorauthorizationresource/update-prior-authorization) with clinical documents attached to the appropriate document types.
2. **Poll for results** - Call [GET Prior Authorization](/api-reference/v1priorauthorizationresource/get-prior-authorization) with `with_requirements=true`. Once the status moves to `DATA_REQUESTED` or `ALL_REQUIRED_DATA_RECEIVED`, validation results are available in `required_data.documents[].document_validation_batch`.
3. **Handle failures** - If `document_validation_batch.result` is `"FAILED"`, use the batch ID to get detailed rule results. You can fix documents and re-upload, or choose to proceed despite the failures (see [Overriding Validations](#overriding-validations)).
4. **Complete the request** - Once the status is `ALL_REQUIRED_DATA_RECEIVED` (either because all validations passed or because you chose to proceed), call [POST Complete Prior Authorization](/api-reference/v1priorauthorizationcompleterequestresource/complete-prior-authorization).

## Rule Types

Document Validation evaluates documents across seven rule categories. Both payor rules and provider-configured rules use the same rule types:

| Rule Type       | What It Validates                      | Example Checks                                                                        |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
| **CLINICIAN**   | Clinician credentials and identity     | Valid signature present, matching NPI/credential, correct taxonomy code               |
| **TIME\_FRAME** | Document dates and expiration          | Document not expired, evaluation within required window, dates align with auth period |
| **DIAGNOSIS**   | Diagnosis codes and dates              | Required ICD codes present, diagnosis date documented                                 |
| **TREATMENT**   | Treatment and referral information     | Referred specialties match requirements, CPT codes present                            |
| **PATIENT**     | Patient demographics and history       | Age verification, clinical history present, patient identity confirmed                |
| **ASSESSMENT**  | Diagnostic tools and clinical criteria | Required assessment instruments used, diagnostic criteria met, severity documented    |
| **DOCUMENT**    | Document type and completeness         | Document matches the required type                                                    |

## Reading Validation Results

### From the Prior Authorization

When you call [GET Prior Authorization](/api-reference/v1priorauthorizationresource/get-prior-authorization) with `with_requirements=true`, each document in `required_data.documents[]` includes:

```json theme={null}
{
  "document_type": "DIAGNOSIS_REPORT",
  "required": true,
  "requirement_satisfied": false,
  "document_validation_batch": {
    "id": "0194a4ed-130d-775b-81fd-ca2b4eb618ce",
    "result": "FAILED"
  }
}
```

* `document_validation_batch.result` - `"PASSED"` or `"FAILED"`
* `document_validation_batch.id` - Use this ID to fetch detailed rule results via the [Get Document Validation Batch](/api-reference/v1documentvalidationbatchresource/get-document-validation-batch) endpoint
* `requirement_satisfied` - Set to `false` when validation fails. The prior authorization will stay in `DATA_REQUESTED` until the documents are fixed or validation is [overridden](#overriding-validations)

<Warning>
  The `document_validation` field on the GET Prior Authorization response is **deprecated**. It only returns a single document validation and does not reflect the full batch. Use `document_validation_batch` instead, which provides the batch ID and aggregate result.
</Warning>

### Detailed Rule Results

Use the [Get Document Validation Batch](/api-reference/v1documentvalidationbatchresource/get-document-validation-batch) endpoint to retrieve the full breakdown of which rules passed and failed:

```json theme={null}
{
  "id": "batch-uuid",
  "document_type": "DIAGNOSIS_REPORT",
  "result": "FAILED",
  "document_validations": [
    {
      "id": "validation-uuid",
      "result": "FAILED",
      "passed_rules": [
        {
          "rule": "DIAGNOSIS_CODES",
          "result": "PASSED",
          "reason": "Required ICD-10 codes F84.0 found in document"
        }
      ],
      "failed_rules": [
        {
          "rule": "DOCUMENT_EXPIRED",
          "result": "FAILED",
          "reason": "Document date (2024-01-15) exceeds the 90-day validity window"
        }
      ],
      "rule_results": [...]
    }
  ]
}
```

Each rule result includes a human-readable `reason` explaining why it passed or failed.

<Tip>
  Use `document_validation_batch.id` from the GET Prior Authorization response to retrieve detailed results via the batch endpoints. The `document_validation` field on the PA response is deprecated — it only returns a single document validation. You can still use the [individual document validation endpoint](/api-reference/v1documentvalidationresource/get-document-validation) to look up a specific validation by ID.
</Tip>

## Overriding Validations

Validation is designed to help catch issues before submission, but it never prevents you from creating a prior authorization. If you want to proceed despite failures, there are two options:

### Option 1: Disable validation for specific document types

Set `document_intelligence_configurations[].document_validation.enabled` to `false` in your PATCH request to skip validation for individual document types while still validating others:

```json theme={null}
{
  "documents": [
    {
      "document_type": "REFERRAL",
      "file_id": "your-file-id"
    }
  ],
  "document_intelligence_configurations": [
    {
      "document_type": "REFERRAL",
      "document_validation": {
        "enabled": false
      }
    }
  ]
}
```

### Option 2: Skip all validation

Set `skip_document_intelligence` to `true` in your PATCH request to bypass validation entirely for that update:

```json theme={null}
{
  "skip_document_intelligence": true,
  "documents": [
    {
      "document_type": "REFERRAL",
      "file_id": "your-file-id"
    }
  ]
}
```

In either case, the prior authorization will advance to `ALL_REQUIRED_DATA_RECEIVED` once all other requirements are met, regardless of any previous validation failures.

## Using Document Validation Without Submitting a Prior Authorization

Document Validation runs as part of the prior authorization workflow, but you are **not required to submit the authorization to Silna** after validation completes. This is useful when you only want to validate documents — for example, to check clinical documentation quality before deciding whether to proceed.

1. **Create a prior authorization** — Call [POST Create Prior Authorization](/api-reference/v1priorauthorizationresource/create-prior-authorization) as usual.
2. **Upload documents** — Call [PATCH Update Prior Authorization](/api-reference/v1priorauthorizationresource/update-prior-authorization) with your documents.
3. **Poll for validation results** — Call [GET Prior Authorization](/api-reference/v1priorauthorizationresource/get-prior-authorization) with `with_requirements=true` to retrieve the validation results from `document_validation_batch`.
4. At this point, you can either save the prior authorization as a draft, making it visible in the "Drafts" tab in the Silna Web App, or you can abandon the authorization if desired. To save as draft, you would use the PATCH API in Step 2 but only set the field `save_as_draft` to be `true`.
   If instead you want to abandon the prior authorization you should call [DELETE Abort Prior Authorization](/api-reference/v1priorauthorizationresource/abort-prior-authorization) to remove the authorization entirely. This is available while the PA is in the `DATA_REQUESTED`, `DATA_RECEIVED`, or `ALL_REQUIRED_DATA_RECEIVED` statuses.

<Info>
  Whether you are saving the prior authorization as a draft or abandoning it all together after running Document Validation, you **should not** call POST Complete
</Info>

## Prior Authorization Lifecycle

Validation runs automatically after you upload documents and before the authorization can be completed. When rules fail, the response includes details about which rules failed and why. You can fix and re-upload, or skip validation and proceed.

```mermaid theme={null}
flowchart TD
    A["POST Create Prior Authorization"] --> B["DATA_REQUESTED"]
    B --> C["PATCH Update<br/>(upload documents)"]
    C --> D["DATA_RECEIVED"]
    D --> V{{"Validation<br/>(30-45s)"}}
    V -->|"Pass"| F["ALL_REQUIRED_DATA_RECEIVED"]
    V -->|"Fail"| B2["DATA_REQUESTED<br/>(with failed rule details)"]
    B2 -->|"Fix & re-upload"| C
    B2 -->|"Skip validation<br/>& proceed"| C
    F --> G["POST Complete"]
    G --> H["REQUESTED"]

    style B fill:#fff3cd,stroke:#333
    style B2 fill:#f8d7da,stroke:#333
    style D fill:#fff3cd,stroke:#333
    style V fill:#e8daef,stroke:#333
    style F fill:#d4edda,stroke:#333
    style H fill:#cce5ff,stroke:#333
```

## API Endpoints

| Endpoint                                                                                                                                       | Description                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Get Document Validation Batch](/api-reference/v1documentvalidationbatchresource/get-document-validation-batch)                                | Returns a batch with all document validations and rule results |
| [Get Document Validations in a Batch](/api-reference/v1documentvalidationbatchdocumentvalidationsresource/get-document-validations-in-a-batch) | Returns paginated document validations within a batch          |
| [Get Document Validation](/api-reference/v1documentvalidationresource/get-document-validation)                                                 | Returns a single document validation by ID                     |