> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Data Access

> PII filtering, signed document URLs, and the sensitive data window.

Verifa provides granular controls over which personally identifiable information
(PII) is accessible through the API and for how long.

## PII field whitelist

Each organization can configure which PII fields are returned in API responses
via the `api_pii_fields` setting. Only whitelisted fields appear in
`extracted_data` — all other fields are omitted.

### Available fields

| Field                      | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| `first_name`               | First name from the identity document.               |
| `last_name`                | Last name / surname.                                 |
| `date_of_birth`            | Date of birth (ISO 8601).                            |
| `address`                  | Structured address (line1, line2, city, state, zip). |
| `document_number`          | Document number (e.g. driver's license number).      |
| `nationality`              | Nationality or country of citizenship.               |
| `gender`                   | Gender as printed on the document.                   |
| `ssn`                      | Social Security Number (US documents only).          |
| `document_type`            | Type of document (e.g. drivers_license, passport).   |
| `document_expiration_date` | Document expiration date (ISO 8601).                 |
| `document_issuing_state`   | Issuing state or jurisdiction.                       |

If `api_pii_fields` is not configured, all fields are returned by default.

## Signed document URLs

Document images (ID front, ID back, selfie) are served through HMAC-signed URLs
with a configurable expiration time.

When you call `GET /api/v1/sessions/\{session_id\}/documents`, each document
includes:

```json
{
  "doc_type": "id_front",
  "mime_type": "image/jpeg",
  "url": "https://api.withverifa.com/api/v1/sessions/session_abc123/documents/id_front?expires=1738368300&sig=abc123...",
  "expires_in": 300
}
```

The `expires_in` value (in seconds) is controlled by the organization's
`image_url_expiry_seconds` setting (default: 300 seconds / 5 minutes).

Signed URLs are single-use from a security perspective — the signature is tied
to the specific session, document type, and expiration timestamp.

## Sensitive data window

Organizations can set a `sensitive_data_retention_days` value that limits how
long PII and documents are accessible after a session completes.

Once the window elapses:

* `GET /api/v1/sessions/\{session_id\}/result` returns an empty `extracted_data`
  object and sets `sensitive_data_expired: true`.
* `GET /api/v1/sessions/\{session_id\}/documents` returns an empty list.
* Non-PII fields (`status`, `face_match_passed`, `age_check_passed`) remain
  accessible.

### Example response after window expiry

```json
{
  "session_id": "session_abc123",
  "status": "approved",
  "is_sandbox": false,
  "face_match_passed": true,
  "face_match_score": 0.94,
  "extracted_data": {},
  "sensitive_data_expired": true,
  "created_at": "2026-01-01T12:00:00Z"
}
```

The window is measured from when the session enters a terminal status
(`completed`, `approved`, `rejected`, or `declined`). Pending or in-progress
sessions are not affected.

## Data subject access (Art. 15) export

To satisfy GDPR Article 15 access requests, Verifa provides full export
endpoints that return every piece of decrypted PII associated with a session
or identity in a single JSON document.

| Endpoint                                        | Scope                                                                               |
| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| `GET /api/v1/sessions/\{session_id\}/export`    | All PII, extracted fields, verification results, and document URLs for one session. |
| `GET /api/v1/identities/\{identity_id\}/export` | Same payload aggregated across every session linked to the identity.                |

Both endpoints:

* Return all decrypted PII Verifa holds for the subject — no fields filtered by
  the `api_pii_fields` whitelist.
* Include 24-hour TTL signed download URLs for each document image so the
  exported bundle can be retained alongside other DSAR evidence.
* Are recorded in the audit log as `api.session.export` and
  `api.identity.export` for compliance proof.

The output of either endpoint is sufficient on its own to fulfill an Article 15
access request.

## Related

* [Data Retention](/api-details/data-retention) — Retention policies and session
  redaction
* [Sessions](/core-concepts/sessions) — Session lifecycle and result retrieval
* [Authentication](/api-details/authentication) — API key scopes for PII access