Usage Communication Format

The Patient Access transformer maps each usage event to one Communication resource in the CMS trace repository. The resource follows the shared trace conventions, with the patientaccess tag and the member and application values as identifiers.

Example Communication

The following Communication was created from the example usage event, a GET Patient/patient-005 request made by the example-health-app application, without enrichment:

{
  "resourceType": "Communication",
  "id": "1601",
  "meta": {
    "tag": [
      {
        "system": "https://smiledigitalhealth.com/communication/category",
        "code": "patientaccess",
        "display": "Patient Access"
      }
    ]
  },
  "identifier": [
    {
      "system": "https://smiledigitalhealth.com/communication/message-key",
      "value": "ad59d558-6230-488f-bbef-6d2f279c5576"
    },
    {
      "system": "https://smiledigitalhealth.com/communication/patientid",
      "value": "patient-005"
    },
    {
      "system": "https://smiledigitalhealth.com/communication/userid",
      "value": "d749550c-2f63-4c5a-9bf2-696b3af9d328"
    },
    {
      "system": "https://smiledigitalhealth.com/credentialmap/oidc/client",
      "value": "example-health-app"
    }
  ],
  "status": "completed",
  "category": [
    {
      "coding": [
        {
          "system": "https://smiledigitalhealth.com/communication/event-type",
          "code": "FHIR_REQUEST"
        },
        {
          "system": "https://smiledigitalhealth.com/communication/event-sub-type",
          "code": "FHIR_READ"
        }
      ],
      "text": "Transaction Log Message Type Information"
    }
  ],
  "sent": "2026-08-26T15:10:10.698-04:00",
  "received": "2026-08-26T15:10:10.685-04:00",
  "recipient": [
    {
      "display": "example-health-app"
    }
  ],
  "payload": [
    {
      "contentAttachment": {
        "contentType": "application/json",
        "url": "Binary/1602",
        "title": "ENDPOINT_RECEIVE",
        "creation": "2026-08-26T15:10:10.685-04:00"
      }
    },
    {
      "contentAttachment": {
        "contentType": "application/json",
        "url": "Binary/1603",
        "title": "ENDPOINT_REPLY",
        "creation": "2026-08-26T15:10:10.698-04:00"
      }
    }
  ],
  "note": [
    {
      "text": "Patient Access API request processed successfully."
    }
  ]
}

Enriched Elements

When enrichment finds the member, the member's active Coverage, and the application's Organization, the same request produces a Communication with the following additional and changed elements:

{
  "contained": [
    {
      "resourceType": "Patient",
      "id": "member",
      "identifier": [
        {
          "type": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                "code": "MB"
              }
            ]
          },
          "system": "https://example.org/member-id",
          "value": "M-100045"
        }
      ],
      "name": [
        {
          "family": "Chen",
          "given": ["Carol"],
          "suffix": ["Jr"]
        }
      ]
    },
    {
      "resourceType": "Organization",
      "id": "requester",
      "identifier": [
        {
          "system": "https://smiledigitalhealth.com/credentialmap/oidc/client",
          "value": "example-health-app"
        }
      ],
      "name": "Example Health App"
    }
  ],
  "subject": {
    "reference": "#member",
    "display": "Chen, Carol Jr"
  },
  "recipient": [
    {
      "reference": "#requester",
      "display": "Example Health App"
    }
  ],
  "identifier": [
    {
      "system": "https://smiledigitalhealth.com/communication/message-key",
      "value": "ad59d558-6230-488f-bbef-6d2f279c5576"
    },
    {
      "system": "https://smiledigitalhealth.com/communication/patientid",
      "value": "patient-005"
    },
    {
      "system": "https://smiledigitalhealth.com/communication/userid",
      "value": "d749550c-2f63-4c5a-9bf2-696b3af9d328"
    },
    {
      "system": "https://smiledigitalhealth.com/credentialmap/oidc/client",
      "value": "example-health-app"
    },
    {
      "system": "https://smiledigitalhealth.com/communication/planid",
      "value": "PLAN-GOLD-2026"
    },
    {
      "system": "https://smiledigitalhealth.com/communication/groupid",
      "value": "GRP-7781"
    }
  ]
}

Each enriched element is added on its own: for example, when only the Organization is found, the Communication contains the requester but has no subject.

Fields Used for Usage Reporting

An identifier is absent when the corresponding additionalJson value is absent from the event, for example when the request failed authentication.

Searching for Usage

Reporting clients can search the trace endpoint for a member's successful Patient Access API requests:

GET https://example.com/trace-fhir/Communication?_tag=https://smiledigitalhealth.com/communication/category|patientaccess&identifier=https://smiledigitalhealth.com/communication/patientid|patient-005&status=completed

Add received=ge2026-01-01&received=lt2027-01-01 to limit the search to a reporting period, or search by the .../credentialmap/oidc/client identifier to find the requests made by one application.