Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.metriport.com/llms.txt

Use this file to discover all available pages before exploring further.

IAS lets a person retrieve their own medical records through your application - it’s distinct from Metriport’s Treatment data flow. Treatment is for clinicians providing treatment to the patient; IAS is for the patient themselves.

​
How it works

Create the patient that will be querying their records in Metriport using the Create Patient endpoint, if they don’t exist already. What changes between Treatment and IAS is the purpose of the request. You signal this with the purposeOfUse query parameter on Start Network Query (treatment or ias; defaults to treatment when omitted). For example, Start Network Query with IAS: 
POST /medical/v1/network/query?patientId=018f7c31-bbbb...&purposeOfUse=ias

{
  "sources": {
    "hie": { "enabled": true },
    "pharmacy": { "enabled": true },
    "lab": { "enabled": true }
  },
  "proofedIdentityId": "pid_018f7c30..."
}
When purposeOfUse is ias, Metriport routes the request through IAS using identity verification artifacts that the network requires for individual access. When it’s treatment (or omitted), Metriport routes through the Treatment rail like it does today. Data returned from IAS will be integrated into the consolidated patient record, like everything else.

​
What you need to do

To use IAS, your application needs to do two things on top of your existing Treatment integration:
  1. Verify the user’s identity via a Metriport-hosted session before their first IAS retrieval. Verification happens at NIST IAL2 with an approved Credential Service Provider. Metriport hosts the flow — you redirect the user in and receive a proofedIdentityId via webhook when they finish.
  2. Pass the proofedIdentityId and an active AAL2 session on every IAS-purposed network query. AAL2 is a multifactor challenge the user satisfies in your app’s session; Metriport provides the challenge flow and returns a session ID you pass via the x-aal2-session header.

​
The full flow

For a user who’s never used IAS in your app:
  1. Verify their identity with Create Identity Session. Receive proofedIdentityId via the ias.identity.verified webhook.
  2. Issue a multifactor challenge with Create AAL2 Challenge. Receive aal2SessionId after the user completes it.
  3. Call your existing Start Network Query with purposeOfUse=ias in the query string, proofedIdentityId in the request body, and the x-aal2-session header.
  4. When the query completes, fetch results with your existing Start Consolidated Data Query.
Subsequent retrievals for the same user skip step 1. Once the user has a verified identity, you only need to refresh the AAL2 session before each new query.