# TEFCA Individual Access

> How a person verifies once and requests their own records across the national networks, and what FinchNode gives back.

TEFCA Individual Access Services (IAS) lets a person request their own records from health systems on the national exchange networks. It's in beta: you can run the whole flow in the console today with synthetic data.

## Choose Connect or IAS

| | Connect | TEFCA IAS (beta) |
| --- | --- | --- |
| Who runs it today | Your patients, from your app | You, signed in to the FinchNode console |
| The person proves who they are by | Signing in to each health system's patient portal | Verifying their identity once |
| Health systems reached | The ones the person picks | Organizations on the networks that match the person |
| You get | Normalized records through the API | Documents, exported as data |

IAS has no API key access during the beta.

## Follow a request

1. **Verify identity.** The person verifies with a credential service provider ([CSP](/docs/resources/glossary#csp)) approved for TEFCA IAS. The IAS SOP requires [IAL2](/docs/resources/glossary#ial2) identity proofing and [AAL2](/docs/resources/glossary#aal2) sign-in.
2. **Consent.** They agree to send their verified identity to the network for this request.
3. **Discover.** A Qualified Health Information Network ([QHIN](/docs/resources/glossary#qhin)) asks organizations whether they hold records for the person. TEFCA uses [XCPD](/docs/resources/glossary#xcpd) for this.
4. **Query.** For a match the person picks, the network lists the documents that organization holds, over [XCA](/docs/resources/glossary#xca).
5. **Retrieve.** The person picks 1 to 5 documents per request, and FinchNode fetches them over XCA.
6. **Export.** A JSON file holds each document as base64, with its MIME type.
7. **Revoke.** Ending the session clears the retrieved documents from FinchNode.

Discovery uses only the demographics from the verified identity: name, date of birth, and address. Nobody can type in their own. The beta doesn't yet send every demographic the IAS SOP lists, such as phone or email. Every request carries the Exchange Purpose code `T-IAS`, which means individual access.

## Use the export

You get documents as the health system sent them. For single-part documents, FinchNode checks the hash and size when the network declares them. It doesn't render or convert the contents.

These documents don't appear in `/api/v1/users/{subject}/records`, and the export isn't a FHIR Bundle. An export looks like this (abbreviated, synthetic):

```json
{
  "mode": "sandbox",
  "synthetic": true,
  "encoding": "base64",
  "exportedAt": "2026-09-30T18:04:11.000Z",
  "documents": [
    {
      "documentId": "6f1c2a9e-3b7d-4e58-9a10-2c4b8d7e5f31",
      "name": "Continuity of Care Document",
      "mimeType": "text/xml",
      "bytes": 48213,
      "partCount": 1,
      "contents": ["PD94bWwgdmVyc2lvbj0iMS4wIj8+..."]
    }
  ],
  "failures": []
}
```

Decode each entry in `contents`, and use `mimeType` to decide how to read it. Most documents arrive in one part. When `partCount` is more than 1, the network returned the document in several parts. FinchNode keeps them in the order it received them and doesn't join them. `bytes` is the decoded size of all parts together.

## Stay within the limits

These apply to the beta exchange.

| Scope | Limit |
| --- | --- |
| Each retrieve request | 1 to 5 different documents |
| Each match | 100 documents from its query |
| Each session | 100 matches, 200 documents, and 12 MiB of stored results, counting base64 and metadata |
| Each FinchNode account | One active exchange at a time |
| Each hour, per account | 10 identity verification starts, and 30 requests to start, discover, query, or retrieve |
| Time | 15 minutes, or less if the identity expires sooner |

Going past the document count returns `413 sandbox_result_limit`. A retrieve that would pass the size limit marks that document as failed instead. When the identity expires, verify again and start a new exchange.

## Know what's kept

- The verified identity, including demographics and the identity token, is encrypted and kept for at most 15 minutes.
- Retrieved documents are encrypted while stored. Only the export returns their contents.
- Revoking a session clears its results. Revoking the identity clears every exchange that used it.
- After revoking or expiry, FinchNode keeps the session's status, times, and consent text, but no documents or identity.
- An expired session is refused at once. Its data is cleared on the next TEFCA request; there's no scheduled purge yet.
- Revoking can't recall a request already sent to the network, or delete a file you exported.
- Nothing is imported into the person's FinchNode records or shared with apps.

## Read the responses

- **A match.** It shows the organization and the matched patient, with birth date and a confidence score when the network gives them. A missing name shows as a placeholder.
- **Documents.** Each has a name, a MIME type, and a creation date when the organization provides one.
- **No match.** This is a normal answer. It doesn't mean the person has no records anywhere.
- **No response from some organizations.** You see a partial result if anything matched, or an unavailable result if nothing did. Discovery runs once per session, so start a new session to ask again.
- **A failed document.** It couldn't be retrieved or validated. Retrieve it again on its own.
- **FHIR responses.** The IAS SOP also allows answers over FHIR. The beta handles documents only.

## Look up the terms

The [glossary](/docs/resources/glossary) defines TEFCA, QHIN, IAS, CSP, IAL2, AAL2, XCPD, and XCA.