Add Patients to Cohort

Bulk assign multiple patients to a cohort.

POST /medical/v1/cohort/{id}/patient

Add Patients to Cohort

cURL

curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/cohort/{id}/patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "patientIds": [
    "<string>"
  ],
  "allPatients": true
}
'

Metriport SDK

import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

// Add specific patients to cohort
const cohortWithPatients = await metriport.addPatientsToCohort({
  cohortId: "00000000-0000-0000-0000-000000000000",
  patientIds: [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ]
});

// Add all patients to cohort
const cohortWithAllPatients = await metriport.addPatientsToCohort({
  cohortId: "00000000-0000-0000-0000-000000000000",
  allPatients: true
});

For more information, see the guide about Cohorts

Path Params

id · string · required

The ID of the cohort to assign patients to.

Body

You must provide either patientIds or allPatients, but not both.

patientIds · string[]

Array of patient IDs to assign to the cohort. Mutually exclusive with the allPatients property.

allPatients · boolean

Property to confirm you want to assign all patients in your metriport instance to the cohort. Mutually exclusive with the patientIds array.

Response

message · string · required

Confirmation message indicating the operation was successful.

cohort · Cohort · required

The cohort details.

Show Cohort properties

id · string · required

The unique identifier for the cohort (UUID format, e.g., 00000000-0000-0000-0000-000000000000).

eTag · string · required

The entity tag for optimistic concurrency control.

name · string · required

The unique name of the cohort within your organization.

description · string · required

The description of the cohort.

color · string · required

The color associated with the cohort.

purposeOfUse · string · required

The cohort's purpose of use: treatment or operations.

settings · object · required

Configuration settings for the cohort.

Show Settings properties

monitoring · object

Hide monitoring object properties

hie · object

HIE-based document monitoring - subscribes patients to HIE-based document monitoring (non-ADT) / medical record refresh based on the cadence.

Show hie object properties

enabled · boolean

Enable or disable scheduled data pulls for HIE monitoring. Defaults to disabled. When disabled, no scheduled pulls will occur regardless of the frequency setting.

frequency · string

How often scheduled data pulls should occur, can be one of daily, weekly, biweekly or monthly. Defaults to monthly.

See scheduled queries for timing details.

adt · object

ADT (Admission, Discharge, Transfer) monitoring - subscribes patients to ADT notifications based on their primary address.

Show adt object properties

enabled · boolean

Enable or disable ADT monitoring notifications. Defaults to disabled.

pharmacy · object

Pharmacy / medication history monitoring - enables retail fill data monitoring where available.

Show pharmacy object properties

notifications · boolean

Enable/disable pharmacy monitoring notifications. Defaults to disabled.

Pharmacy notifications are coming soon! While this feature is not yet live, you can configure your Pharmacy notification settings now. These settings will automatically take effect when the feature launches.

schedule · object

Enable pharmacy data pulls at scheduled dates.

Show schedule object properties

enabled · boolean

Enable or disable scheduled data pulls for pharmacy monitoring. When disabled, no scheduled pulls will occur regardless of the frequency setting. Defaults to disabled.

frequency · string

How often scheduled data pulls should occur, can be one of weekly, biweekly or monthly. Defaults to monthly.

See scheduled queries for timing details.

laboratory · object

Laboratory / lab results monitoring - enables laboratory test results monitoring where available.

Show laboratory object properties

notifications · boolean

Enable/disable laboratory monitoring notifications. Defaults to disabled.

size · number · required

The number of patients assigned to this cohort.

Metriport SDK

import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

// Add specific patients to cohort
const cohortWithPatients = await metriport.addPatientsToCohort({
  cohortId: "00000000-0000-0000-0000-000000000000",
  patientIds: [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ]
});

// Add all patients to cohort
const cohortWithAllPatients = await metriport.addPatientsToCohort({
  cohortId: "00000000-0000-0000-0000-000000000000",
  allPatients: true
});

{
  "message": "Patient(s) successfully added to cohort",
  "cohort": {
    "id": "00000000-0000-0000-0000-000000000000",
    "eTag": "1",
    "name": "High Risk",
    "description": "Patients that need frequent and robust monitoring.",
    "color": "red",
    "purposeOfUse": "treatment",
    "settings": {
        "monitoring": {
          "hie": {
            "enabled": true,
            "frequency": "weekly"
          },
          "adt": {
            "enabled": true
          },
          "pharmacy": {
            "notifications": true,
            "schedule": {
              "enabled": false,
              "frequency": "monthly"
            }
          },
          "laboratory": {
            "notifications": true
          }
        }
    },
    "size": 250
  }
}

Notes

• When assigning specific patientIds to a treatment cohort, patients with treatmentRelationship: false cannot be added. Use the Treatment Relationship endpoint to update consent before assigning those patients to treatment cohorts.
• When using allPatients: true on a treatment cohort, patients with treatmentRelationship: false are not added. The request still succeeds for all other patients.