SMART Permission Tickets, published by . This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/jmandel/smart-permission-tickets-wip/ and changes regularly. See the Directory of published versions

Payer Quality Gap Queries

This page defines one Permission Ticket type. The overview of all types is the Use Case Catalog; constraint definitions live on Access Constraints.

Status: Modeled

Purpose

A payer or value-based care organization retrieves the structured evidence a named quality measure needs — an HbA1c result, a mammogram report, a blood-pressure reading — for a member attributed to it.

CMS's Interoperability Framework names this flow among its criteria: "Payers, including CMS, and other Value-based care organizations may query for specific quality data elements (e.g., HbA1c, mammograms, colonoscopies, blood pressure, BMI, depression screening) necessary for payment or health care operations."

Today this evidence is gathered by chart retrieval at scale — during the HEDIS reporting season a provider organization fields thousands of record requests. A quality gap ticket is the element-scoped form of the same request for a single member: the signed artifact says precisely which elements, for which measure, over which period, and authorizes nothing else. The provider gets a verifiable, auditable record of exactly what was asked and why.

The ticket authorizes data only for quality measurement of the named measure. Using the ticket, or the data it returns, for another purpose — risk adjustment, underwriting — is outside the grant, and the trust framework the issuer operates under backs that limit. Evidence that lives only in clinical notes is document retrieval, not an element query, and is outside this type.

Typical Flow

A ticket is minted per member and measure, naming the payer as requester and the measure it serves → the payer's system presents the ticket at the provider's endpoint → the provider issues an access token limited to the named elements over the measurement period. One ticket serves one measure; a member's open gaps for the season are several tickets, each with its own purpose and audit trail, not one blurred union.

The payer typically mints the ticket itself, within a trust relationship it already has with the provider — a network, a value-based care contract, or a coverage relationship. The ticket does not establish that relationship; it carries a signed, scoped, single-purpose assertion that the provider can enforce uniformly and log. A provider may instead mint tickets from a payer's gap list; the artifact is identical either way.

Required Claims

• Subject: Patient, with subject.recipient_record SHOULD when the issuer is the Data Holder.
• Requester: Organization (the payer or value-based care entity), identified well enough to match a coverage or contract relationship.
• Profile claim: measure (CodeableConcept, required) — the quality measure the query serves. The requester names the data it needs in smart_scopes; measure says why, selecting the Data Holder's applicable policy and anchoring the audit and re-association trail.
• Presenter binding: Optional (B2B), as in claims adjudication: the Data Holder confirms the redeeming client acts for the requester, whether through binding, registration, or a trust-framework relationship.
• Expiration: exp SHOULD cover the reporting window the query serves.

Constraints

Draws from the constraint catalog, nothing new defined:

• smart_scopes (required) — the elements, one scope per element: patient/Observation.rs?code=http://loinc.org|4548-4 is an HbA1c query. Every scope carries a granular ?category or ?code narrowing, so the ticket authorizes specific elements rather than whole record types. This is the enforced limit.
• data_period (required) — the measurement or lookback period from the measure specification; without it a quality query is unbounded history. When a measure's elements carry different lookbacks — a ten-year colonoscopy window beside a one-year FIT window — mint one ticket per lookback; one wide window would over-expose the short-lookback elements.

This type carries just smart_scopes and data_period. claim_linkage is not part of it (there is no claim), and data_holder_filter is not part of it (the audience is a single named Data Holder). Cross-cutting constraints such as sensitivity_withhold MAY be added; servers that do not enforce them reject the ticket.

Policy Selection Inputs

Data Holder Processing

• Verify issuer trust for this ticket type — trusting an issuer for claims adjudication tickets does not imply trusting it for recurring quality queries.
• Confirm the requester's coverage or contract relationship to the member against the Data Holder's own records. The issuer attests the attribution behind the query, but releasing data to a payer is the provider's disclosure to make, so the relationship check is not delegated away.
• The Data Holder MAY narrow release to entries it judges consistent with the named measure.
• Records restricted from disclosure to the payer are excluded silently, exactly as in claims adjudication. The restriction matters here because no claim event implies the payer was party to the underlying care; the HIPAA self-pay restriction (45 CFR 164.522(a)(1)(vi)) is the leading case.

Open Questions

Open Question (OQ-QUALITY-GAP): Attribution record and lifetime. A payer-minted ticket rests on a member-attribution attestation. Against what relationship record does a Data Holder check it — coverage and eligibility, a value-based contract panel, a network attribution list — and how stale may that attestation be? And over what lifetime should a recurring quality query's ticket remain valid?

Example

{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}

{
  "iss": "https://fhir.provider.example.org",
  "aud": "https://fhir.provider.example.org",
  "aud_type": "data_holder_url",
  "exp": 1792697950,
  "iat": 1782329950,
  "jti": "qg-7b41d6e8-90af-4c33-8d12-64e07f5a21c9",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/payer-quality-gap-v1",
  "presenter_binding": {
    "method": "trust_framework_client",
    "trust_framework": "https://directory.example-network.org",
    "framework_type": "udap",
    "entity_uri": "https://payer.example.com/organizations/quality"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://fhir.provider.example.org/mrn",
          "value": "C10288"
        }
      ],
      "birthDate": "1957-11-02",
      "name": [
        {
          "family": "Tran",
          "given": [
            "Lien"
          ]
        }
      ]
    },
    "recipient_record": {
      "reference": "https://fhir.provider.example.org/Patient/C10288",
      "type": "Patient"
    }
  },
  "requester": {
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "http://hl7.org/fhir/sid/us-npi",
        "value": "1093817465"
      }
    ],
    "name": "Example Health Plan"
  },
  "measure": {
    "coding": [
      {
        "system": "https://www.cms.gov/medicare/quality/measures",
        "code": "CMS122v12",
        "display": "Diabetes: Glycemic Status Assessment Greater Than 9%"
      }
    ],
    "text": "Diabetes glycemic status (HbA1c)"
  },
  "access": {
    "smart_scopes": [
      "patient/Observation.rs?code=http://loinc.org|4548-4"
    ],
    "data_period": {
      "start": "2026-01-01",
      "end": "2026-12-31"
    }
  }
}

eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL2ZoaXIucHJvdmlkZXIuZXhhbXBsZS5vcmciLCJhdWQiOiJodHRwczovL2ZoaXIucHJvdmlkZXIuZXhhbXBsZS5vcmciLCJhdWRfdHlwZSI6ImRhdGFfaG9sZGVyX3VybCIsImV4cCI6MTc5MjY5Nzk1MCwiaWF0IjoxNzgyMzI5OTUwLCJqdGkiOiJxZy03YjQxZDZlOC05MGFmLTRjMzMtOGQxMi02NGUwN2Y1YTIxYzkiLCJ0aWNrZXRfdHlwZSI6Imh0dHBzOi8vc21hcnRoZWFsdGhpdC5vcmcvcGVybWlzc2lvbi10aWNrZXQtdHlwZS9wYXllci1xdWFsaXR5LWdhcC12MSIsInByZXNlbnRlcl9iaW5kaW5nIjp7Im1ldGhvZCI6InRydXN0X2ZyYW1ld29ya19jbGllbnQiLCJ0cnVzdF9mcmFtZXdvcmsiOiJodHRwczovL2RpcmVjdG9yeS5leGFtcGxlLW5ldHdvcmsub3JnIiwiZnJhbWV3b3JrX3R5cGUiOiJ1ZGFwIiwiZW50aXR5X3VyaSI6Imh0dHBzOi8vcGF5ZXIuZXhhbXBsZS5jb20vb3JnYW5pemF0aW9ucy9xdWFsaXR5In0sInN1YmplY3QiOnsicGF0aWVudCI6eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50IiwiaWRlbnRpZmllciI6W3sic3lzdGVtIjoiaHR0cDovL2ZoaXIucHJvdmlkZXIuZXhhbXBsZS5vcmcvbXJuIiwidmFsdWUiOiJDMTAyODgifV0sImJpcnRoRGF0ZSI6IjE5NTctMTEtMDIiLCJuYW1lIjpbeyJmYW1pbHkiOiJUcmFuIiwiZ2l2ZW4iOlsiTGllbiJdfV19LCJyZWNpcGllbnRfcmVjb3JkIjp7InJlZmVyZW5jZSI6Imh0dHBzOi8vZmhpci5wcm92aWRlci5leGFtcGxlLm9yZy9QYXRpZW50L0MxMDI4OCIsInR5cGUiOiJQYXRpZW50In19LCJyZXF1ZXN0ZXIiOnsicmVzb3VyY2VUeXBlIjoiT3JnYW5pemF0aW9uIiwiaWRlbnRpZmllciI6W3sic3lzdGVtIjoiaHR0cDovL2hsNy5vcmcvZmhpci9zaWQvdXMtbnBpIiwidmFsdWUiOiIxMDkzODE3NDY1In1dLCJuYW1lIjoiRXhhbXBsZSBIZWFsdGggUGxhbiJ9LCJtZWFzdXJlIjp7ImNvZGluZyI6W3sic3lzdGVtIjoiaHR0cHM6Ly93d3cuY21zLmdvdi9tZWRpY2FyZS9xdWFsaXR5L21lYXN1cmVzIiwiY29kZSI6IkNNUzEyMnYxMiIsImRpc3BsYXkiOiJEaWFiZXRlczogR2x5Y2VtaWMgU3RhdHVzIEFzc2Vzc21lbnQgR3JlYXRlciBUaGFuIDklIn1dLCJ0ZXh0IjoiRGlhYmV0ZXMgZ2x5Y2VtaWMgc3RhdHVzIChIYkExYykifSwiYWNjZXNzIjp7InNtYXJ0X3Njb3BlcyI6WyJwYXRpZW50L09ic2VydmF0aW9uLnJzP2NvZGU9aHR0cDovL2xvaW5jLm9yZ3w0NTQ4LTQiXSwiZGF0YV9wZXJpb2QiOnsic3RhcnQiOiIyMDI2LTAxLTAxIiwiZW5kIjoiMjAyNi0xMi0zMSJ9fX0.vjX6uCey9mTHnpLGLxz5KQSDFIF4JyO5lLrVc5ARBPisOTeh73ZWefdJXYA3ftsbxYqSpBfk2RQ4hadSyDpQvg