> ## 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.

# Interactions

> Raw evidence captured per sandbox during a rollout.

An **interaction** is a single recorded event from a sandbox during a rollout: a FHIR request/response, an outbound HL7 message, a voice turn, an OCR'd fax document, a portal action, an SFTP upload, or an X12 response. Verial captures these as the rollout happens so the [verification engine](/guides/concepts/verification) can score them and so you can inspect them afterward.

For the concept, see [Interactions](/guides/concepts/interactions). This page covers how to read them back.

## Two Ways In

There are two ways to reach recorded interactions, and you usually want the first one.

1. **Scoped to a criterion.** `GET /criterion-runs/{id}` returns the `evidence` payload the check used to reach its verdict. This is the right entry point when you are triaging a specific failure because the evidence is already filtered down to what mattered for that check.
2. **Raw per-sandbox.** `GET /sandboxes/{id}/events` returns every event recorded against a sandbox, in order. Use this when you need the full interaction log, the exact request headers a FHIR call went out with, or turns that the criterion did not inspect.

<Note>
  The sandbox events endpoint (`GET /sandboxes/{id}/events`) is the lowest-level
  access. For task-scoped evidence, prefer the criterion-run endpoint.
</Note>

## Evidence by Protocol

| Protocol         | What gets recorded                                             | How to read it                                                                                    |
| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| FHIR             | Requests and responses against the sandbox FHIR store          | `evidence.field_results[]` on a `fhir-resource-state` criterion; raw calls via sandbox events     |
| HL7              | Outbound v2 messages your agent posted (`hl7_outbound` events) | `evidence.field_results[]` on an `hl7-structural` criterion; raw messages via sandbox events      |
| Voice            | Transcript turns from the IVR session                          | `evidence.phrase_results[]` on a `voice-transcript` criterion; full turns via sandbox events      |
| Fax              | OCR'd fax documents submitted to the sandbox                   | Criterion evidence references the matched document; raw documents via sandbox events              |
| Portal (Web Sim) | Portal actions and state transitions                           | `evidence.assertion_results[]` on a `portal-state-match` criterion; raw events via sandbox events |
| SFTP / Files     | File uploads and listings under the sandbox's SFTP prefix      | `evidence.field_results[]` plus matched path(s) on an `sftp-file-present` criterion               |
| X12              | X12 response records for the playground                        | `evidence.field_results[]` on an `x12-response` criterion                                         |

The `evidence` shape is summarized on the [Verification concept page](/guides/concepts/verification#evidence-payloads); the canonical definition is whatever the Criterion Run row currently holds.

## Example: Voice Transcript

A `voice-transcript` criterion records which phrases it searched for and in which turn it found them.

```json theme={null}
{
  "id": "crun_voice_01H...",
  "criterion_id": "crit_voice_01H...",
  "passed": true,
  "score": 1.0,
  "details": "All 2 required phrases found in transcript.",
  "evidence": {
    "phrase_results": [
      { "phrase": "prior authorization", "found": true, "turn": 3 },
      { "phrase": "member id", "found": true, "turn": 5 }
    ]
  }
}
```

To inspect the full transcript (every turn, not just the matched ones), pull sandbox events for the voice sandbox:

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

## Example: FHIR Request Log

A `fhir-resource-state` criterion compares the final state of a resource against expected fields.

```json theme={null}
{
  "id": "crun_fhir_01H...",
  "criterion_id": "crit_fhir_01H...",
  "passed": false,
  "score": 0.5,
  "details": "Appointment resource matched; 1 of 2 field assertions failed.",
  "evidence": {
    "field_results": [
      { "path": "participant.0.actor.display", "expected": "Dr. Rivera", "actual": "Dr. Rivera", "passed": true },
      { "path": "status", "expected": "booked", "actual": "proposed", "passed": false }
    ]
  }
}
```

The criterion evidence shows what the engine compared. If you want to see how the resource actually got into that state (which requests the agent made, in what order), pull events for the FHIR sandbox:

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

## Example: Portal Events

Portal (web simulator) criteria record assertion results against the sandbox's portal state.

```json theme={null}
{
  "id": "crun_portal_01H...",
  "criterion_id": "crit_portal_01H...",
  "passed": true,
  "score": 1.0,
  "details": "portal_state_match passed on 1 assertion",
  "evidence": {
    "assertion_results": [
      { "path": "payer", "expected": "BlueCross", "actual": "BlueCross", "passed": true }
    ]
  }
}
```

Sandbox events for the portal sandbox include every action the agent took (form submissions, navigations) and every state transition that resulted. Those events are what the portal-state-match criterion is reading against.

## Next Steps

<CardGroup cols={2}>
  <Card title="Criteria" icon="check" href="/guides/concepts/criteria">
    The typed assertions that produce each evidence shape.
  </Card>

  <Card title="Verification" icon="scale-balanced" href="/guides/concepts/verification">
    How the engine dispatches checks against sandbox state.
  </Card>
</CardGroup>