List Patient Care Gaps

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

import requests

url = "https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

GET

medical

patient

{patientId}

care-gaps

List Patient Care Gaps

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

import requests

url = "https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/care-gaps")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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 for one measure: a Patient entry, a MeasureReport with calculation Parameters contained on the report, and the clinical resources used as evidence. For more context on care gaps and how to interpret results, see the Care Gaps guide.

Path Params

string

required

The Metriport Patient ID.

Query Params

number

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

number

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

number

Calendar year of the care-gap bundle to read. Patient must have been queried in that year. Defaults to the current calendar year.

Response

object

required

Pagination metadata.

Show metadata properties

number

required

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

number

required

The limit used for this request.

number

required

The offset used for this request.

Bundle[]

required

Array of FHIR Bundle resources. Each bundle contains a Patient, one MeasureReport (with contained Parameters), and the evidence resources that report references.

Show Bundle properties

Patient

required

The patient this measure report applies to.

Show Patient properties

string

required

Always "Patient".

string

required

The Metriport patient id.

Identifier[]

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

Show Identifier properties

string

required

The external id from your system.

string

required

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

string

required

Always secondary.

HumanName[]

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

string

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

string

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

MeasureReport

required

The care gap measure report. Calculation parameters are contained on this resource.

Show MeasureReport properties

string

required

Always "MeasureReport".

string

required

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

string

required

One of complete, pending, or error.

string

required

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

string

required

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

object

required

Reference to the patient this report covers.

Show subject properties

string

required

Patient reference in the format Patient/{patientId}.

object

required

The measurement period.

Show period properties

string

Start of the measurement period (ISO 8601 date).

string

End of the measurement period (ISO 8601 date).

Extension[]

required

Show Extension properties

string

required

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

Parameters[]

required

Calculation parameters for this patient and measure, contained on the report.

Show Parameters properties

string

required

Always "Parameters".

Parameter[]

required

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

Show Parameter properties

string

required

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

boolean

A boolean parameter value.

integer

An integer parameter value.

number

A decimal parameter value.

string

A string parameter value.

string

A coded parameter value.

string

A date parameter value (ISO 8601).

string

A date-time parameter value (ISO 8601).

object

A period parameter value.

Show valuePeriod properties

string

Period start (ISO 8601 date).

string

Period end (ISO 8601 date).

Reference[]

References to the clinical resources used as evidence for this measure.

Show evaluatedResource properties

string

required

Resource reference, for example Observation/{id}.

MeasureReportGroup[]

The measure population groups.

Show MeasureReportGroup properties

string

required

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

CodeableConcept

The coded group type.

MeasureReportGroupPopulation[]

Population membership results for this group.

Show MeasureReportGroupPopulation properties

CodeableConcept

required

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

integer

required

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

Resource

Evidence resources referenced by the measure report’s evaluatedResource.

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": "BCSE.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"
              }
            ],
            "contained": [
              {
                "resourceType": "Parameters",
                "id": "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"
                    }
                  }
                ]
              }
            ],
            "evaluatedResource": [
              {
                "reference": "Observation/44444444-4444-4444-4444-444444444444"
              }
            ],
            "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:44444444-4444-4444-4444-444444444444",
          "resource": {
            "resourceType": "Observation",
            "id": "44444444-4444-4444-4444-444444444444",
            "status": "final",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "24604-1"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

List Patient Care Gaps

Path Params

Query Params

Response

​Path Params

​Query Params

​Response

Path Params

Query Params

Response