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

# Fax

> Simulated fax numbers for inbound and outbound documents with OCR evidence.

The fax simulator stands in for a healthcare fax line: the workhorse of referral intake, prior-auth cover sheets, and records exchange. Each sandbox gets a fax number your agent can send documents to (PDF or TIFF), and the simulator can also deliver inbound faxes into the sandbox's inbox. Every submitted document is OCR'd and preserved as interaction evidence.

## How your agent connects

The fax sandbox's `credentials` payload includes a `fax_number` your agent sends documents to. Your agent submits faxes via `POST /sandboxes/{sandbox_id}/faxes` on the direct-service surface and can retrieve metadata plus rendered content via `GET /sandboxes/{sandbox_id}/faxes/{fax_id}`. Inbound faxes seeded by task scenarios are recorded as sandbox events.

<Note>
  The fax simulator is not currently mounted on the run-scoped `/v1/benchmark-runs/{id}/fax/*` surface. During a benchmark run, resolve the fax sandbox from the `sandboxes` list on the run response and call the direct `/sandboxes/{id}/faxes` endpoints with an organization API key.
</Note>

## Endpoints

| Method | Endpoint                                 | Description                                      |
| ------ | ---------------------------------------- | ------------------------------------------------ |
| `POST` | `/sandboxes/{sandbox_id}/faxes`          | Submit a fax to the simulated fax line           |
| `GET`  | `/sandboxes/{sandbox_id}/faxes/{fax_id}` | Retrieve metadata for a previously submitted fax |

See [Send fax](/api-reference/fax/send) and [Get fax](/api-reference/fax/get) for the full request/response reference.

## Driving the rollout

Send a fax (for example a referral response):

```bash theme={null}
curl -X POST "https://api.verial.ai/sandboxes/$FAX_SANDBOX_ID/faxes" \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "patient-123",
    "to_number": "+15555551234",
    "document_type": "referral",
    "content_reference": "doc-ref-abc"
  }'
```

Retrieve a submission:

```bash theme={null}
curl "https://api.verial.ai/sandboxes/$FAX_SANDBOX_ID/faxes/fax_01H..." \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

The response includes delivery status, OCR'd text, and references to the rendered pages.

## Configuration

The fax simulator has no required configuration at create time. Inbound fax documents are typically seeded by the dataset or by task scenarios that drop faxes into the inbox before a task run starts.

```bash theme={null}
curl -X POST https://api.verial.ai/simulators \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "Fax", "name": "Referral Fax Line"}'
```

For tasks that expect a specific document shape (e.g. a cover sheet with header fields), Verial can render documents from a `DocumentSpec` description. See the generic document rendering helper in `services/pdf.ts` (title, header fields, sections) for how the platform constructs inbound faxes.

## Verification

There is no dedicated fax check type in the current criterion catalog. Fax evidence is scored in two ways:

* **Interaction evidence.** Every fax submitted or received is logged as an interaction. OCR'd text is attached as evidence you can inspect on a criterion run or through the interaction log.
* **Cross-simulator criteria.** If the fax's contents are expected to flow into another system (for example the agent transcribes a referral fax and posts a FHIR ServiceRequest), the `fhir-resource-state` criterion on that downstream resource is what scores correctness.

Dedicated fax-content assertions (regex on OCR, field extraction) are on the roadmap. Until then, route fax content to another simulator your criterion can read.

## Next Steps

<CardGroup cols={2}>
  <Card title="Criteria" icon="check-double" href="/guides/concepts/criteria">
    The assertions the verification engine currently supports.
  </Card>

  <Card title="Fax API reference" icon="code" href="/api-reference/fax/send">
    Direct-access fax endpoints for authoring.
  </Card>

  <Card title="Files / SFTP" icon="folder-open" href="/guides/simulators/files-sftp">
    For structured document drops, prefer the SFTP simulator with `sftp-file-present`.
  </Card>

  <Card title="Simulators overview" icon="server" href="/guides/simulators/overview">
    Lifecycle, provisioning, and configuration patterns.
  </Card>
</CardGroup>