How it works API endpoint Request structure Example request Response format Error responses Validation rules Performance specifications Required permissions Important implementation notes Workflow example Related operations

FHIR `$inquire` operation for HealthLake

The $inquire operation enables you to check the status of a previously submitted prior authorization request. This operation implements the Da Vinci Prior Authorization Support (PAS) Implementation Guide, providing a standardized FHIR-based workflow to retrieve the current authorization decision.

How it works

Submit Inquiry: You send a FHIR Bundle containing the Claim you want to check and supporting information
Search: HealthLake searches for the corresponding ClaimResponse in your data store
Retrieve: The most recent authorization status is retrieved
Respond: You receive an immediate response with the current authorization status (queued, approved, denied, etc.)

Note

$inquire is a read-only operation that retrieves existing authorization status. It does not modify or update any resources in your data store.

API endpoint


POST /datastore/{datastoreId}/r4/Claim/$inquire  
Content-Type: application/fhir+json

Request structure

Bundle requirements

Your request must be a FHIR Bundle resource with:

Bundle.type: Must be "collection"
Bundle.entry: Must contain exactly one Claim resource with:
- use = "preauthorization"
- status = "active"
Referenced Resources: All resources referenced by the Claim must be included in the Bundle

Query-by-Example

The resources in your input Bundle serve as a search template. HealthLake uses the information provided to locate the corresponding ClaimResponse.

Required resources

Resource	Cardinality	Profile	Description
Claim	1	PAS Claim Inquiry	The prior authorization you're inquiring about
Patient	1	PAS Beneficiary Patient	Patient demographic information
Organization (Insurer)	1	PAS Insurer Organization	Insurance company
Organization (Provider)	1	PAS Requesting Organization	Healthcare provider who submitted the request

Important search criteria

HealthLake searches for the ClaimResponse using:

Patient reference from the Claim
Insurer reference from the Claim
Provider reference from the Claim
Created date from the Claim (as a time filter)

Patient-Specific Queries Only

All inquiries must be tied to a specific patient. System-wide queries without patient identification are not permitted.

Example request


POST /datastore/example-datastore/r4/Claim/$inquire  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "resourceType": "Bundle",  
  "id": "PASClaimInquiryBundleExample",  
  "meta": {  
    "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-inquiry-request-bundle"]  
  },  
  "identifier": {  
    "system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",  
    "value": "5269368"  
  },  
  "type": "collection",  
  "timestamp": "2005-05-02T14:30:00+05:00",  
  "entry": [  
    {  
      "fullUrl": "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",  
      "resource": {  
        "resourceType": "Claim",  
        "id": "MedicalServicesAuthorizationExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry"]  
        },  
        "status": "active",  
        "type": {  
          "coding": [{  
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",  
            "code": "professional"  
          }]  
        },  
        "use": "preauthorization",  
        "patient": {  
          "reference": "Patient/SubscriberExample"  
        },  
        "created": "2005-05-02T11:01:00+05:00",  
        "insurer": {  
          "reference": "Organization/InsurerExample"  
        },  
        "provider": {  
          "reference": "Organization/UMOExample"  
        }  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Patient/SubscriberExample",  
      "resource": {  
        "resourceType": "Patient",  
        "id": "SubscriberExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary"]  
        },  
        "name": [{  
          "family": "SMITH",  
          "given": ["JOE"]  
        }],  
        "gender": "male"  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Organization/UMOExample",  
      "resource": {  
        "resourceType": "Organization",  
        "id": "UMOExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]  
        },  
        "name": "Provider Organization"  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Organization/InsurerExample",  
      "resource": {  
        "resourceType": "Organization",  
        "id": "InsurerExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]  
        },  
        "name": "Insurance Company"  
      }  
    }  
  ]  
}

Response format

Success response (200 OK)

You'll receive a PAS Inquiry Response Bundle containing:

ClaimResponse with the current authorization status; multiple ClaimResponse if it matches search criteria
All original resources from your request (echoed back)
Timestamp of when the response was assembled

Possible ClaimResponse Outcomes

Outcome	Description
`queued`	Authorization request is still pending review
`complete`	Authorization decision has been made (check `disposition` for approved/denied)
`error`	An error occurred during processing
`partial`	Partial authorization granted


{  
  "resourceType": "Bundle",  
  "identifier": {  
        "system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",  
        "value": "5269367"  
  },  
  "type": "collection",  
  "timestamp": "2005-05-02T14:30:15+05:00",  
  "entry": [  
    {  
      "fullUrl": "http://example.org/fhir/ClaimResponse/InquiryResponseExample",  
      "resource": {  
        "resourceType": "ClaimResponse",  
        "id": "InquiryResponseExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse-inquiry"]  
        },  
        "status": "active",  
        "type": {  
          "coding": [{  
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",  
            "code": "professional"  
          }]  
        },  
        "use": "preauthorization",  
        "patient": {  
          "reference": "Patient/SubscriberExample"  
        },  
        "created": "2005-05-02T11:05:00+05:00",  
        "insurer": {  
          "reference": "Organization/InsurerExample"  
        },  
        "request": {  
          "reference": "Claim/MedicalServicesAuthorizationExample"  
        },  
        "outcome": "complete",  
        "disposition": "Approved",  
        "preAuthRef": "AUTH12345"  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",  
      "resource": {  
        "resourceType": "Claim",  
        "id": "MedicalServicesAuthorizationExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry"]  
        },  
        "status": "active",  
        "type": {  
          "coding": [{  
            "system": "http://terminology.hl7.org/CodeSystem/claim-type",  
            "code": "professional"  
          }]  
        },  
        "use": "preauthorization",  
        "patient": {  
          "reference": "Patient/SubscriberExample"  
        },  
        "created": "2005-05-02T11:01:00+05:00",  
        "insurer": {  
          "reference": "Organization/InsurerExample"  
        },  
        "provider": {  
          "reference": "Organization/UMOExample"  
        }  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Patient/SubscriberExample",  
      "resource": {  
        "resourceType": "Patient",  
        "id": "SubscriberExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary"]  
        },  
        "name": [{  
          "family": "SMITH",  
          "given": ["JOE"]  
        }],  
        "gender": "male"  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Organization/UMOExample",  
      "resource": {  
        "resourceType": "Organization",  
        "id": "UMOExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]  
        },  
        "name": "Provider Organization"  
      }  
    },  
    {  
      "fullUrl": "http://example.org/fhir/Organization/InsurerExample",  
      "resource": {  
        "resourceType": "Organization",  
        "id": "InsurerExample",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]  
        },  
        "name": "Insurance Company"  
      }  
    }  
  ]  
}

Error responses

400 Bad Request

Returned when the request format is invalid or validation fails.


{  
    "resourceType": "OperationOutcome",  
    "issue": [  
        {  
            "severity": "error",  
            "code": "required",  
            "diagnostics": "Reference 'Patient/SubscriberExample' at path 'patient' for 'CLAIM' resource not found(at Bundle.entry[0].resource)"  
        }  
    ]  
}

401 Unauthorized

Returned when authentication credentials are missing or invalid.


{  
    "resourceType": "OperationOutcome",  
    "issue": [  
        {  
            "severity": "error",  
            "code": "forbidden",  
            "diagnostics": "Invalid authorization header"  
        }  
    ]  
}

403 Forbidden

Returned when the authenticated user lacks permission to access the requested resource.


{  
    "resourceType": "OperationOutcome",  
    "issue": [  
        {  
            "severity": "error",  
            "code": "exception",  
            "diagnostics": "Insufficient SMART scope permissions."  
        }  
    ]  
}

400 When none found

Returned when no matching ClaimResponse is found for the inquiry.


{  
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "not-found",
    "diagnostics": "Resource not found. No ClaimResponse found from the input Claim that matches the specified Claim properties patient, insurer, provider, and created(at Bundle.entry[0].resource)"
  }]
}

415 Unsupported Media Type

Returned when the Content-Type header is not application/fhir+json.


{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "value",  
    "diagnostics": "Incorrect MIME-type. Update request Content-Type header."  
  }]  
}

429 Too Many Requests

Returned when rate limits are exceeded.


{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "throttled",  
    "diagnostics": "Rate limit exceeded. Please retry after some time."  
  }]  
}

Validation rules

HealthLake performs comprehensive validation on your inquiry:

Bundle validation

Must conform to PAS Inquiry Request Bundle profile
Bundle.type must be "collection"
Must contain exactly one Claim resource
All referenced resources must be included in the Bundle

Claim validation

Must conform to PAS Claim Inquiry profile
Claim.use must be "preauthorization"
Claim.status must be "active"
Required fields: patient, insurer, provider, created

Resource validation

All resources must conform to their respective PAS Inquiry profiles
Required supporting resources must be present (Patient, Insurer Organization, Provider Organization)
Cross-references must be valid and resolvable within the Bundle

Performance specifications

Metric	Specification
Resource Count Limit	500 resources per Bundle
Bundle Size Limit	5 MB maximum

Required permissions

To use the $inquire operation, ensure your IAM role has:

healthlake:InquirePreAuthClaim - To call the operation

SMART on FHIR Scopes

Minimum required scopes:

SMART v1: user/ClaimResponse.read
SMART v2: user/ClaimResponse.s

Important implementation notes

Search behavior

When you submit an inquiry, HealthLake searches for the ClaimResponse using:

Patient reference from the input Claim
Insurer reference from the input Claim
Provider reference from the input Claim
Created date from the input Claim (as a time filter)

Multiple Matches: If multiple ClaimResponses match your search criteria, HealthLake returns all matching results. You should use the most recent ClaimResponse.created timestamp to identify the latest status.

Updated claims

If you've submitted multiple updates to the same prior authorization (e.g., Claim v1.1, v1.2, v1.3), the $inquire operation will retrieve the ClaimResponse associated with the most recent version based on the search criteria provided.

Read-only operation

The $inquire operation:

Does retrieve existing authorization status
Does return the most recent ClaimResponse
Does not modify or update any resources
Does not create new resources
Does not trigger new authorization processing

Workflow example

Typical Prior Authorization Inquiry Workflow


1. Provider submits PA request  
   POST /Claim/$submit  
   → Returns ClaimResponse with outcome="queued"  
  
2. Payer reviews request (asynchronous)  
   → Updates ClaimResponse status internally  
  
3. Provider checks status  
   POST /Claim/$inquire  
   → Returns ClaimResponse with outcome="queued" (still pending)  
  
4. Provider checks status again later  
   POST /Claim/$inquire  
   → Returns ClaimResponse with outcome="complete", disposition="Approved"

Claim/$submit - Submit a new prior authorization request or update an existing one
Patient/$everything - Retrieve comprehensive patient data for prior authorization context

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

$export

$lookup

FHIR $inquire operation for HealthLake