List Patient Suspects

Lists suspected conditions for a single patient as FHIR Bundles (analytics).

GET /medical/v1/patient/{patientId}/suspects

List Patient Suspects

cURL

curl --request GET \
  --url https://api.sandbox.metriport.com/medical/v1/patient/{patientId}/suspects \
  --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 suspected conditions for the patient identified by patientId in the path. Each result is a FHIR Bundle that includes a Patient resource, the suspected Condition, and evidence resources (Observations, Procedures, MedicationRequests) that support the suspicion.

For more context on suspecting and how to interpret results, see the Suspecting 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 suspected condition 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 Condition, and its supporting evidence.

Show Bundle properties

Patient · Patient · required

The patient this suspected condition 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.

Condition · Condition · required

The suspected condition.

Show Condition properties

resourceType · string · required

Always "Condition".

id · string · required

The unique identifier for this suspected condition.

subject · object · required

Show subject properties

reference · string · required

Patient reference in the format Patient/{patientId}.

code · object · required

The ICD-10-CM coded condition.

Show code properties

coding · Coding[] · required

Show Coding properties

system · string · required

Always "http://hl7.org/fhir/sid/icd-10-cm".

code · string · required

The ICD-10-CM code (e.g. "E11.9").

display · string

Human-readable condition name.

verificationStatus · object · required

Always unconfirmed — the condition has been flagged as a potential suspect but has not been clinically confirmed.

extension · Extension[] · required

Metriport-specific extensions summarizing the evidence.

Show Extension properties

suspect-type · string · required

URL: https://public.metriport.com/fhir/StructureDefinition/suspect-type. Either "suspect" (new suspected condition) or "recapture" (previously diagnosed condition requiring re-documentation).

evidence-count · integer · required

URL: https://public.metriport.com/fhir/StructureDefinition/evidence-count. Total number of supporting evidence records.

first-evidence-date · date · required

URL: https://public.metriport.com/fhir/StructureDefinition/first-evidence-date. Date of the earliest supporting evidence.

last-evidence-date · date · required

URL: https://public.metriport.com/fhir/StructureDefinition/last-evidence-date. Date of the most recent supporting evidence.

hcc-code · string · required

URL: https://public.metriport.com/fhir/StructureDefinition/hcc-code. The Hierarchical Condition Category code for this condition.

job-id · string · required

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

evidence · ConditionEvidence[] · required

The suspected manifestations and their supporting evidence references.

Show ConditionEvidence properties

code · CodeableConcept[] · required

The suspect manifestation definition coded using the Metriport suspect-manifestation CodeSystem. Includes a human-readable text field describing the clinical rule.

detail · Reference[]

References to the evidence resources in this bundle that support the suspicion.

Show Reference properties

type · string · required

Resource type (e.g. "Observation", "Procedure", "MedicationRequest").

reference · string · required

Relative reference (e.g. "Observation/{id}").

Observation | Procedure | MedicationRequest · Observation | Procedure | MedicationRequest

Evidence resources supporting the suspicion.

Show Observation properties

resourceType · string · required

Always "Observation".

id · string · required

The unique identifier for this observation.

status · string · required

One of registered, preliminary, final, amended, corrected, cancelled, entered-in-error, or unknown.

code · object · required

The observation type. Uses LOINC where available, falling back to the source coding system.

Show code properties

coding · Coding[] · required

One or more codings for the observation type.

effectiveDateTime · string

The date/time the observation was recorded (ISO 8601).

valueQuantity · object

The numeric result value.

Show valueQuantity properties

value · number

The numeric value.

unit · string

The unit of measure (e.g. "mg/dL", "mL/min/1.73m2").

category · CodeableConcept[]

The observation category (e.g. laboratory, vital-signs).

interpretation · CodeableConcept[]

Clinical interpretation of the result (e.g. H for high, L for low).

note · Annotation[]

Free-text notes associated with the observation.

subject · object

Reference to the patient (present when a patientId filter is applied).

Show Procedure properties

resourceType · string · required

Always "Procedure".

id · string · required

The unique identifier for this procedure.

status · string · required

One of preparation, in-progress, not-done, on-hold, stopped, completed, entered-in-error, or unknown.

code · object · required

The procedure type. Uses CPT and/or SNOMED-CT where available.

Show code properties

coding · Coding[] · required

One or more codings for the procedure type.

performedDateTime · string

The date the procedure was performed (ISO 8601).

subject · object

Reference to the patient (present when a patientId filter is applied).

Show MedicationRequest properties

resourceType · string · required

Always "MedicationRequest".

id · string · required

The unique identifier for this medication request.

status · string · required

One of active, on-hold, cancelled, completed, entered-in-error, stopped, draft, or unknown.

intent · string · required

One of proposal, plan, order, original-order, reflex-order, filler-order, instance-order, or option. Defaults to "order".

medicationCodeableConcept · object · required

The medication. Uses RxNorm and/or NDC where available.

Show medicationCodeableConcept properties

coding · Coding[] · required

One or more codings for the medication.

authoredOn · string

The date the prescription was written (ISO 8601).

dosageInstruction · Dosage[]

Dosage instructions.

Show Dosage properties

doseAndRate · object[]

Show doseAndRate properties

doseQuantity · object

Show doseQuantity properties

value · number

The dose amount.

unit · string

The dose unit.

timing · object

When the medication should be administered.

subject · object

Reference to the patient (present when a patientId filter is applied).

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": ["Sam"], "family": "Example" }
            ],
            "gender": "male",
            "birthDate": "1975-03-20"
          }
        },
        {
          "fullUrl": "urn:uuid:55555555-5555-5555-5555-555555555555",
          "resource": {
            "resourceType": "Condition",
            "id": "88888888-8888-8888-8888-888888888888",
            "subject": {
              "reference": "Patient/00000000-0000-0000-0000-000000000000"
            },
            "code": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/sid/icd-10-cm",
                  "code": "E11.9",
                  "display": "Type 2 diabetes mellitus without complications"
                }
              ]
            },
            "verificationStatus": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                  "code": "unconfirmed",
                  "display": "Unconfirmed"
                }
              ]
            },
            "extension": [
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/suspect-type",
                "valueString": "suspect"
              },
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/evidence-count",
                "valueInteger": 3
              },
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/first-evidence-date",
                "valueDate": "2023-09-21"
              },
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/last-evidence-date",
                "valueDate": "2023-09-27"
              },
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/hcc-code",
                "valueString": "38"
              },
              {
                "url": "https://public.metriport.com/fhir/StructureDefinition/job-id",
                "valueString": "22222222-2222-2222-2222-222222222222"
              }
            ],
            "evidence": [
              {
                "code": [
                  {
                    "coding": [
                      {
                        "system": "https://public.metriport.com/fhir/CodeSystem/suspect-manifestation",
                        "code": "diabetes_fpg_126_199",
                        "display": "Diabetes (FPG 126-199 mg/dL)"
                      }
                    ],
                    "text": "Fasting glucose 126-199 mg/dL on two separate dates."
                  }
                ],
                "detail": [
                  {
                    "type": "Observation",
                    "reference": "Observation/33333333-3333-3333-3333-333333333333"
                  },
                  {
                    "type": "Observation",
                    "reference": "Observation/44444444-4444-4444-4444-444444444444"
                  }
                ]
              }
            ]
          }
        },
        {
          "fullUrl": "urn:uuid:66666666-6666-6666-6666-666666666666",
          "resource": {
            "resourceType": "Observation",
            "id": "33333333-3333-3333-3333-333333333333",
            "status": "final",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "1558-6"
                }
              ]
            },
            "effectiveDateTime": "2023-09-27",
            "valueQuantity": {
              "value": 141,
              "unit": "mg/dL"
            }
          }
        },
        {
          "fullUrl": "urn:uuid:77777777-7777-7777-7777-777777777777",
          "resource": {
            "resourceType": "Observation",
            "id": "44444444-4444-4444-4444-444444444444",
            "status": "final",
            "code": {
              "coding": [
                {
                  "system": "http://loinc.org",
                  "code": "1558-6"
                }
              ]
            },
            "effectiveDateTime": "2023-09-23",
            "valueQuantity": {
              "value": 152,
              "unit": "mg/dL"
            }
          }
        }
      ]
    }
  ]
}