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

# Audit & Evidence

> What FaceSign retains for audit purposes, how to retrieve it, retention periods, and known gaps.

For regulated deployments — especially banking and payments — the ability to produce verification evidence for a specific session months or years after the fact is a procurement requirement. This page documents what FaceSign retains, how to retrieve it, and where the current gaps are.

<Note>
  Retention and audit capabilities are evolving. Where a gap exists, we've called it out explicitly rather than claiming a capability we don't yet have. If your compliance program requires something documented as a gap below, email [security@facesign.ai](mailto:security@facesign.ai) before signing a contract — we may be able to accommodate via DPA addendum.
</Note>

## What's retained by default

Every completed session produces a **session report** that persists beyond the session itself. Retention windows depend on the environment:

| Environment             | Default retention                                                                |
| ----------------------- | -------------------------------------------------------------------------------- |
| Sandbox (`sk_test_`)    | 7 days                                                                           |
| Production (`sk_live_`) | Per contract (typically 90 days to 7 years based on your regulatory obligations) |

Retained fields:

| Field                             | Description                                                                         |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| **Session ID**                    | Unique identifier for the verification attempt                                      |
| **Status**                        | `created`, `inProgress`, `incomplete`, or `complete`                                |
| **Timestamps**                    | Created, started, finished (Unix ms)                                                |
| **Client reference ID**           | Your internal user/transaction identifier                                           |
| **Metadata**                      | Custom key-value pairs you passed at session creation                               |
| **Transcript**                    | Full conversation between avatar and user, time-stamped                             |
| **Node reports**                  | Outcome of each verification step (liveness, recognition, document scan, OTP, etc.) |
| **AI analysis**                   | Age range, sex detection, real-vs-virtual assessment, behavioral observations       |
| **Video AI analysis**             | Per-criterion fraud scoring (if `videoAIAnalysisEnabled: true`)                     |
| **Location**                      | GeoIP city, country, coordinates, timezone, ISP, VPN detection                      |
| **Device**                        | Browser, OS, mobile/desktop/tablet                                                  |
| **Hashed biometric fingerprints** | One-way hashes for future recognition (only if consented)                           |

## What is NOT retained by default

* **Raw video frames** — processed in memory and discarded at session end
* **Raw audio** — processed in memory and discarded at session end
* **Document images** — discarded at session end unless explicitly opted in via `retainSessionMedia: true`
* **Unencrypted biometric data** — all biometric data is tokenized at ingest

If you need media retention for audit (e.g., bank regulator requirements to hold document scans), opt in at session creation. See [Biometric Data Handling](/docs/security/biometric-data) for the full retention model.

## Retrieving audit evidence

### For a specific session (by ID)

The primary retrieval mechanism is `GET /sessions/:id`, which returns the full session report including transcript, node reports, and any retained media URLs.

```bash wrap theme={null}
curl https://api.facesign.ai/sessions/3f0a4e1e-9c2b-4b6f-8d3a-2a8e1b7c4f01 \
  -H "Authorization: Bearer sk_live_..."
```

See [`GET /sessions/:id`](/docs/api-reference/getSession) for the full response schema.

### For a specific user (by client reference ID)

If you passed a `clientReferenceId` at session creation (recommended — typically your internal user ID), you can list all sessions for that reference:

```bash wrap theme={null}
curl "https://api.facesign.ai/sessions?clientReferenceId=user-123" \
  -H "Authorization: Bearer sk_live_..."
```

See [`GET /sessions`](/docs/api-reference/listSessions) for filtering options.

### Media URLs

Retained media (document images, session video if opted in) is accessed via signed download URLs on the session response.

<Warning>
  **Signed URLs expire 15 minutes after generation.** For long-term audit storage, download media immediately upon session completion and store it in your own object storage with your own retention lifecycle.
</Warning>

## Known gaps

These are capabilities regulated customers commonly ask for. We're being explicit about which are available today.

| Capability                                        | Status                                                                                                                                |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Retrieve by session ID                            | ✅ Available today (`GET /sessions/:id`)                                                                                               |
| List by `clientReferenceId`                       | ✅ Available today (`GET /sessions`)                                                                                                   |
| Filter by date range / status                     | 🟡 Basic filters available; see [listSessions](/docs/api-reference/listSessions)                                                      |
| Full-text search across transcripts               | ❌ Not available. Workaround: retrieve sessions and search client-side, or mirror transcripts into your own search index via webhooks. |
| Bulk export (e.g., all sessions for a date range) | 🟡 Available via pagination on `GET /sessions`; no dedicated bulk endpoint.                                                           |
| Audit trail of access to session data             | ❌ Not available. FaceSign does not currently log which API keys accessed which session.                                               |
| Legal hold / retention override                   | 🟡 Supported on a contract basis; contact [security@facesign.ai](mailto:security@facesign.ai).                                        |
| Immutable write-once storage                      | ❌ Not available. Mirror critical sessions to your own WORM storage if required by regulation.                                         |
| SIEM integration (event streaming)                | ❌ Not available. Workaround: consume webhooks into your own SIEM.                                                                     |

If a gap above blocks your procurement process, please raise it early — we may be able to document a compensating control or prioritize the capability based on your timeline.

## Recommended architecture

For regulated deployments, we recommend treating FaceSign as the **verification system of record during the session** and your own infrastructure as the **audit system of record for the long term**:

1. **At session completion**, consume the `session.status: complete` webhook
2. **Fetch the full session report** via `GET /sessions/:id`
3. **Download any retained media** via the signed URLs (within 15 minutes)
4. **Persist** the transcript, node reports, and media in your own audit infrastructure with your own retention lifecycle, WORM guarantees, and access logging

This pattern satisfies most bank and payment regulator requirements (retrievability, tamper-evidence, access logging) by leveraging your existing compliance infrastructure rather than requiring FaceSign to re-implement them.

## Compliance framework alignment

For how audit evidence relates to specific frameworks (GDPR, CCPA, BIPA, PSD3, SOC 2, ISO 27001), see [Compliance & Regulatory](/docs/security/compliance).