Skip to main content
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.
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.

​
Endpoints

MethodEndpointDescription
POST/sandboxes/{sandbox_id}/faxesSubmit a fax to the simulated fax line
GET/sandboxes/{sandbox_id}/faxes/{fax_id}Retrieve metadata for a previously submitted fax
See Send fax and Get fax for the full request/response reference.

​
Driving the rollout

Send a fax (for example a referral response): 
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: 
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. 
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

Criteria

The assertions the verification engine currently supports.

Fax API reference

Direct-access fax endpoints for authoring.

Files / SFTP

For structured document drops, prefer the SFTP simulator with sftp-file-present.

Simulators overview

Lifecycle, provisioning, and configuration patterns.