TEFCA Individual Access

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) approved for TEFCA IAS. The IAS SOP requires IAL2 identity proofing and 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) asks organizations whether they hold records for the person. TEFCA uses XCPD for this.
4. Query. For a match the person picks, the network lists the documents that organization holds, over 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):

{
  "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 defines TEFCA, QHIN, IAS, CSP, IAL2, AAL2, XCPD, and XCA.