List Patient Care Gaps

Lists care gaps for a single patient as FHIR Bundles (analytics).

GET /medical/v1/patient/{patientId}/care-gaps

List Patient Care Gaps

cURL

curl --request GET \
  --url https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps \
  --header 'x-api-key: <api-key>'

Analytics must be enabled for your account to receive data from this endpoint. Contact us to get started.

Returns a paginated list of care gaps for the patient identified by patientId in the path. Each result is a FHIR Bundle with a Patient entry, a MeasureReport, and a Parameters resource with supporting calculation details.

For more context on care gaps and how to interpret results, see the Care Gaps guide.

Path Params

patientId · string · required

The Metriport Patient ID.

Query Params

limit · number

Maximum number of results to return. Must be between 1 and 100. Defaults to 20.

offset · number

Number of results to skip for pagination. Must be 0 or greater. Defaults to 0.

Response

metadata · object · required

Pagination metadata.

Show metadata properties

total · number · required

Total number of care gap records matching the query for this patient.

limit · number · required

The limit used for this request.

offset · number · required

The offset used for this request.

results · Bundle[] · required

Array of FHIR Bundle resources. Each bundle contains a Patient, a MeasureReport, and a Parameters resource.

Show Bundle properties

Patient · Patient · required

The patient this measure report applies to.

Show Patient properties

resourceType · string · required

Always "Patient".

id · string · required

The Metriport patient id.

identifier · Identifier[]

Your system’s version of the patient id. Each entry uses Metriport’s external-id system and use: "secondary".

Show Identifier properties

value · string · required

The external id from your system.

system · string · required

Always https://public.metriport.com/fhir/StructureDefinition/external-id.json.

use · string · required

Always secondary.

name · HumanName[]

Name when present. Each entry may include given (string array) and/or family (string).

gender · string

Administrative gender when present: male, female, other, or unknown (FHIR).

birthDate · string

Date of birth as an ISO 8601 date (YYYY-MM-DD) when present.

MeasureReport · MeasureReport · required

The care gap measure report.

Show MeasureReport properties

resourceType · string · required

Always "MeasureReport".

id · string · required

The measure report ID, composed as {measureName}.{patientId}.{periodStart} (e.g. "BreastCancerScreening.00000000-0000-0000-0000-000000000000.2025-01-01").

status · string · required

One of complete, pending, or error.

type · string · required

One of individual, subject-list, summary, or data-collection.

measure · string · required

The canonical URL of the measure (e.g. "http://ncqa.org/fhir/Measure/BreastCancerScreening").

subject · object · required

Reference to the patient this report covers.

Show subject properties

reference · string · required

Patient reference in the format Patient/{patientId}.

period · object · required

The measurement period.

Show period properties

start · string

Start of the measurement period (ISO 8601 date).

end · string

End of the measurement period (ISO 8601 date).

extension · Extension[] · required

Show Extension properties

job-id · string · required

URL: https://public.metriport.com/fhir/StructureDefinition/job-id. The analytics job that produced this report.

group · MeasureReportGroup[]

The measure population groups.

Show MeasureReportGroup properties

id · string · required

The group identifier (e.g. the measure name).

code · CodeableConcept

The coded group type.

population · MeasureReportGroupPopulation[]

Population membership results for this group.

Show MeasureReportGroupPopulation properties

code · CodeableConcept · required

The population type. Common values: initial-population, denominator, denominator-exclusion, numerator.

count · integer · required

1 if the patient is in this population, 0 if not.

Parameters · Parameters · required

Supporting calculation parameters for this patient and measure.

Show Parameters properties

resourceType · string · required

Always "Parameters".

parameter · Parameter[] · required

Supporting calculation details for this patient and measure. Parameters vary by measure.

Show Parameter properties

name · string · required

The parameter name (e.g. "Age at end of measurement period", "Is continuously enrolled").

valueBoolean · boolean

A boolean parameter value.

valueInteger · integer

An integer parameter value.

valueDecimal · number

A decimal parameter value.

valueString · string

A string parameter value.

valueCode · string

A coded parameter value.

valueDate · string

A date parameter value (ISO 8601).

valueDateTime · string

A date-time parameter value (ISO 8601).

valuePeriod · object

A period parameter value.

Show valuePeriod properties

start · string

Period start (ISO 8601 date).

end · string

Period end (ISO 8601 date).

Response

{
  "metadata": {
    "total": 1,
    "limit": 20,
    "offset": 0
  },
  "results": [
    {
      "resourceType": "Bundle",
      "type": "collection",
      "entry": [
        {
          "fullUrl": "urn:uuid:11111111-1111-1111-1111-111111111111",
          "resource": {
            "resourceType": "Patient",
            "id": "00000000-0000-0000-0000-000000000000",
            "identifier": [
              {
                "value": "1234567890",
                "system": "https://public.metriport.com/fhir/StructureDefinition/external-id.json",
                "use": "secondary"
              }
            ],
            "name": [
              { "given": ["Alex"], "family": "Example" }
            ],
            "gender": "female",
            "birthDate": "1980-01-15"
          }
        },
        {
          "fullUrl": "urn:uuid:22222222-2222-2222-2222-222222222222",
          "resource": {
            "resourceType": "MeasureReport",
            "id": "BreastCancerScreening.00000000-0000-0000-0000-000000000000.2025-01-01",
            "status": "complete",
            "type": "individual",
            "measure": "http://ncqa.org/fhir/Measure/BreastCancerScreening",
            "subject": {
              "reference": "Patient/00000000-0000-0000-0000-000000000000"
            },
            "period": {
              "start": "2025-01-01",
              "end": "2025-12-31"
            },
            "extension": [
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/job-id",
                "valueString": "99999999-9999-9999-9999-999999999999"
              }
            ],
            "group": [
              {
                "id": "BreastCancerScreening",
                "code": {
                  "coding": [
                    {
                      "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                      "code": "BreastCancerScreening"
                    }
                  ]
                },
                "population": [
                  {
                    "code": {
                      "coding": [
                        {
                          "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                          "code": "initial-population"
                        }
                      ]
                    },
                    "count": 1
                  },
                  {
                    "code": {
                      "coding": [
                        {
                          "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                          "code": "denominator"
                        }
                      ]
                    },
                    "count": 1
                  },
                  {
                    "code": {
                      "coding": [
                        {
                          "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                          "code": "denominator-exclusion"
                        }
                      ]
                    },
                    "count": 0
                  },
                  {
                    "code": {
                      "coding": [
                        {
                          "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                          "code": "numerator"
                        }
                      ]
                    },
                    "count": 0
                  }
                ]
              }
            ]
          }
        },
        {
          "fullUrl": "urn:uuid:33333333-3333-3333-3333-333333333333",
          "resource": {
            "resourceType": "Parameters",
            "parameter": [
              {
                "name": "Age at end of measurement period",
                "valueInteger": 42
              },
              {
                "name": "Is continuously enrolled",
                "valueBoolean": true
              },
              {
                "name": "Mammography screening period",
                "valuePeriod": {
                  "start": "2023-10-01",
                  "end": "2025-12-31"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}