Create Patient

Creates a Patient in Metriport for the specified Facility where the patient is receiving care.

POST /medical/v1/patient

Create Patient

cURL

curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/patient \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "dob": "<string>",
  "genderAtBirth": "<string>",
  "personalIdentifiers": [
    {
      "type": "<string>",
      "state": "<string>",
      "value": "<string>"
    }
  ],
  "address": [
    {
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>"
    }
  ],
  "contact": [
    {
      "phone": "<string>",
      "email": "<string>"
    }
  ],
  "externalId": "<string>",
  "status": {
    "hieOptOut": true,
    "treatmentRelationship": true
  },
  "cohorts": [
    "<string>"
  ],
  "networkQuery": {
    "sources": {
      "hie": {
        "enabled": true
      },
      "pharmacy": {
        "enabled": true,
        "realtime": true
      },
      "lab": {
        "enabled": true
      }
    },
    "proofedIdentityId": "<string>",
    "metadata": {}
  }
}
'

import requests

url = "https://api.sandbox.metriport.com/medical/v1/patient"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "dob": "<string>",
    "genderAtBirth": "<string>",
    "personalIdentifiers": [
        {
            "type": "<string>",
            "state": "<string>",
            "value": "<string>"
        }
    ],
    "address": [
        {
            "addressLine1": "<string>",
            "addressLine2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zip": "<string>",
            "country": "<string>"
        }
    ],
    "contact": [
        {
            "phone": "<string>",
            "email": "<string>"
        }
    ],
    "externalId": "<string>",
    "status": {
        "hieOptOut": True,
        "treatmentRelationship": True
    },
    "cohorts": ["<string>"],
    "networkQuery": {
        "sources": {
            "hie": { "enabled": True },
            "pharmacy": {
                "enabled": True,
                "realtime": True
            },
            "lab": { "enabled": True }
        },
        "proofedIdentityId": "<string>",
        "metadata": {}
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    dob: '<string>',
    genderAtBirth: '<string>',
    personalIdentifiers: [{type: '<string>', state: '<string>', value: '<string>'}],
    address: [
      {
        addressLine1: '<string>',
        addressLine2: '<string>',
        city: '<string>',
        state: '<string>',
        zip: '<string>',
        country: '<string>'
      }
    ],
    contact: [{phone: '<string>', email: '<string>'}],
    externalId: '<string>',
    status: {hieOptOut: true, treatmentRelationship: true},
    cohorts: ['<string>'],
    networkQuery: {
      sources: {
        hie: {enabled: true},
        pharmacy: {enabled: true, realtime: true},
        lab: {enabled: true}
      },
      proofedIdentityId: '<string>',
      metadata: {}
    }
  })
};

fetch('https://api.sandbox.metriport.com/medical/v1/patient', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'dob' => '<string>',
    'genderAtBirth' => '<string>',
    'personalIdentifiers' => [
        [
                'type' => '<string>',
                'state' => '<string>',
                'value' => '<string>'
        ]
    ],
    'address' => [
        [
                'addressLine1' => '<string>',
                'addressLine2' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'zip' => '<string>',
                'country' => '<string>'
        ]
    ],
    'contact' => [
        [
                'phone' => '<string>',
                'email' => '<string>'
        ]
    ],
    'externalId' => '<string>',
    'status' => [
        'hieOptOut' => true,
        'treatmentRelationship' => true
    ],
    'cohorts' => [
        '<string>'
    ],
    'networkQuery' => [
        'sources' => [
                'hie' => [
                                'enabled' => true
                ],
                'pharmacy' => [
                                'enabled' => true,
                                'realtime' => true
                ],
                'lab' => [
                                'enabled' => true
                ]
        ],
        'proofedIdentityId' => '<string>',
        'metadata' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.metriport.com/medical/v1/patient"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dob\": \"<string>\",\n  \"genderAtBirth\": \"<string>\",\n  \"personalIdentifiers\": [\n    {\n      \"type\": \"<string>\",\n      \"state\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"address\": [\n    {\n      \"addressLine1\": \"<string>\",\n      \"addressLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zip\": \"<string>\",\n      \"country\": \"<string>\"\n    }\n  ],\n  \"contact\": [\n    {\n      \"phone\": \"<string>\",\n      \"email\": \"<string>\"\n    }\n  ],\n  \"externalId\": \"<string>\",\n  \"status\": {\n    \"hieOptOut\": true,\n    \"treatmentRelationship\": true\n  },\n  \"cohorts\": [\n    \"<string>\"\n  ],\n  \"networkQuery\": {\n    \"sources\": {\n      \"hie\": {\n        \"enabled\": true\n      },\n      \"pharmacy\": {\n        \"enabled\": true,\n        \"realtime\": true\n      },\n      \"lab\": {\n        \"enabled\": true\n      }\n    },\n    \"proofedIdentityId\": \"<string>\",\n    \"metadata\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.metriport.com/medical/v1/patient")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dob\": \"<string>\",\n  \"genderAtBirth\": \"<string>\",\n  \"personalIdentifiers\": [\n    {\n      \"type\": \"<string>\",\n      \"state\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"address\": [\n    {\n      \"addressLine1\": \"<string>\",\n      \"addressLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zip\": \"<string>\",\n      \"country\": \"<string>\"\n    }\n  ],\n  \"contact\": [\n    {\n      \"phone\": \"<string>\",\n      \"email\": \"<string>\"\n    }\n  ],\n  \"externalId\": \"<string>\",\n  \"status\": {\n    \"hieOptOut\": true,\n    \"treatmentRelationship\": true\n  },\n  \"cohorts\": [\n    \"<string>\"\n  ],\n  \"networkQuery\": {\n    \"sources\": {\n      \"hie\": {\n        \"enabled\": true\n      },\n      \"pharmacy\": {\n        \"enabled\": true,\n        \"realtime\": true\n      },\n      \"lab\": {\n        \"enabled\": true\n      }\n    },\n    \"proofedIdentityId\": \"<string>\",\n    \"metadata\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.metriport.com/medical/v1/patient")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dob\": \"<string>\",\n  \"genderAtBirth\": \"<string>\",\n  \"personalIdentifiers\": [\n    {\n      \"type\": \"<string>\",\n      \"state\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"address\": [\n    {\n      \"addressLine1\": \"<string>\",\n      \"addressLine2\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"zip\": \"<string>\",\n      \"country\": \"<string>\"\n    }\n  ],\n  \"contact\": [\n    {\n      \"phone\": \"<string>\",\n      \"email\": \"<string>\"\n    }\n  ],\n  \"externalId\": \"<string>\",\n  \"status\": {\n    \"hieOptOut\": true,\n    \"treatmentRelationship\": true\n  },\n  \"cohorts\": [\n    \"<string>\"\n  ],\n  \"networkQuery\": {\n    \"sources\": {\n      \"hie\": {\n        \"enabled\": true\n      },\n      \"pharmacy\": {\n        \"enabled\": true,\n        \"realtime\": true\n      },\n      \"lab\": {\n        \"enabled\": true\n      }\n    },\n    \"proofedIdentityId\": \"<string>\",\n    \"metadata\": {}\n  }\n}"

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

Metriport SDK

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const facilityId = "00000000-00000000-00000000-00000000";
const patient = await metriport.createPatient(
  {
    firstName: "Jose",
    lastName: "Juarez",
    dob: "1951-05-05",
    genderAtBirth: "M",
    personalIdentifiers: [
      {
        type: "driversLicense",
        state: USState.CA,
        value: "51227265",
      },
    ],
    address: [
      {
        zip: "12345",
        city: "San Diego",
        state: USState.CA,
        country: "USA",
        addressLine1: "Guadalajara Street"
      },
    ],
    contact: [
      {
        phone: "1234567899",
        email: "[e-mail]",
      },
    ],
    externalId: "123456789",
    status: { 
      hieOptOut: false,
      treatmentRelationship: true
    },
    cohorts: ["00000000-00000000-00000000-00000000"]
  },
  facilityId
);

Query Params

facilityId · string · required

The ID of the Facility where the Patient is receiving care.

Body

The more demographic information you can provide about a Patient, the higher chances Metriport will be able to find a match. For example: nicknames, old addresses, multiple phone numbers, a pre-marital last name, etc.

You may provide a comma/space delimited string to specify multiple first and last names. For example, the following inputs would be equivalent: "John,Jonathan" & "John Jonathan" - these would translate to ["John", "Jonathan"].

firstName · string · required

The Patient's first name(s).

lastName · string · required

The Patient's last name(s).

dob · string · required

The Patient's date of birth (DOB), formatted YYYY-MM-DD as per ISO 8601.

genderAtBirth · string · required

The Patient's gender at birth, can be one of M or F or O or U. Use O (other) when the patient's gender is known but it is not M or F, i.e intersex or hermaphroditic. Use U (unknown) when the patient's gender is not known.

personalIdentifiers · PersonalIdentifier[]

An array of the Patient's personal IDs, such as a driver's license or SSN. May be empty.

Show PersonalIdentifier properties

type · string · required

The ID type - currently driversLicense or ssn is supported.

state · string · required

The 2 letter state acronym where this ID was issued, for example: CA. Only required for type driversLicense.

value · string · required

The ID number. For type ssn, should be 9 digits.

address · Address[] · required

An array of Address objects, representing the Patient's current and/or previous addresses.

Show Address properties

addressLine1 · string · required

The address.

addressLine2 · string

The address details, for example: #4451.

city · string · required

The city.

state · string · required

The 2 letter state acronym, for example: CA.

zip · string · required

5 digit zip code.

country · string

If specified, must be "USA"; otherwise will default to "USA".

The first address in the array determines the primary address for the patient. The primary address is used for patient monitoring, specifically for ADT events. You can change which address is the primary address by simply re-ordering the address array using the PUT patient endpoint. Learn more about patient monitoring and cohorts.

contact · Contact[]

An array of Contact objects, representing the Patient's current and/or previous contact information. May be empty.

Show Contact properties

phone · string

The Patient's 10 digit phone number, formatted 1234567899.

email · string

The Patient's email address. Supports a wide range of valid email formats including special characters.

Valid email examples:

• [e-mail]
• test![e-mail]
• [e-mail]
• [e-mail]
• [e-mail]
• [e-mail]

Invalid email examples:

• invalid-email (missing @ and domain)
• user@ (missing domain)
• @example.com (missing local part)
• [e-mail] (phone number format)
• mailto:[e-mail] (mailto: prefix not allowed)

externalId · string

An external Patient ID to associate to a Patient in Metriport.

If externalId is provided, it will be returned in webhook payloads and responses involving the Patient.

status · object

Patient status flags for HIE opt-out and treatment relationship consent.

Show status properties

hieOptOut · boolean

When set to true, the patient is opted out of network discovery and document queries. Defaults to false.

treatmentRelationship · boolean

Whether the patient has treatment relationship consent. Defaults to true.

Patients with consent (false) cannot be assigned to treatment cohorts. Setting this to false automatically removes the patient from treatment cohorts. See the Treatment Relationship API reference to update consent programmatically.

cohorts · string[]

The list of cohort IDs this patient should be assigned to.

See Working With Cohorts to learn more about how to use this field.

networkQuery · object

When provided, kicks off a network query for the patient.

Show networkQuery properties

sources · object · required

Data sources to query. At least one source must be enabled.

Show Source configuration

hie · object

HIE (Health Information Exchange) source configuration.

Show HIE options

enabled · boolean · required

Whether to query the national networks for all-purpose clinical data.

pharmacy · object

Pharmacy source configuration.

Show Pharmacy options

enabled · boolean · required

Whether to query pharmacy sources.

realtime · boolean

Whether to return results in near real time.

This is a premium feature - if you'd like access to it, contact us and let us know!

lab · object

Laboratory source configuration.

Show Lab options

enabled · boolean · required

Whether to query laboratory sources.

Legacy format: The API also accepts an array of source names (e.g., sources: ["hie", "pharmacy", "lab"]) for backward compatibility, but the object format above is recommended as it supports per-source options.

proofedIdentityId · string

Required when the purposeOfUse query parameter is ias. The verified identity returned on the ias.identity.verified webhook.

metadata · object

Custom metadata to include with the request. This will be returned in webhook payloads.

Show Metadata properties

Holds a record of up to 50 custom string key-value pairs. Key names can be up to 40 characters long and values up to 500 characters long.

Example Request Body:

{
  "sources": {
    "hie": { "enabled": true },
    "pharmacy": { "enabled": true, "realtime": true },
    "lab": { "enabled": true }
  },
  "metadata": {
    "youCan": "putAny",
    "stringKeyValue": "pairsHere"
  }
}

Response

id · string · required

The ID assigned to this Patient. This ID will be used to uniquely identify this Patient in medical documents.

externalId · string

The ID of the Patient on your internal system to associate to a Patient in Metriport.

status · object · required

Patient status flags.

Show status properties

hieOptOut · boolean · required

Whether the patient is opted out of HIE data sharing and pulling.

treatmentRelationship · boolean · required

Whether the patient has treatment relationship consent. When false, the patient cannot be assigned to treatment cohorts.

additionalIds · AdditionalIdentifiers

A map containing additional external identifiers. If the patient is created or mapped in Metriport through one of our EHR apps - this property will be populated with the ID from the EHR, and included within the webhook payloads.

Show AdditionalIdentifiers properties

athenahealth · string[]

Athena patient ID. If more than one patient in Athena maps to a Metriport patient, they will all be included.

canvas · string[]

Canvas patient ID. If more than one patient in Canvas maps to a Metriport patient, they will all be included.

elation · string[]

Elation Patient ID. If more than one patient in Elation maps to a Metriport patient, they will all be included.

firstName · string[] · required

The Patient's first name(s).

lastName · string[] · required

The Patient's last name(s).

dob · string · required

The Patient's date of birth (DOB), formatted YYYY-MM-DD as per ISO 8601.

genderAtBirth · string · required

The Patient's gender at birth, can be one of M or F or O or U. Use O (other) when the patient's gender is known but it is not M or F, i.e intersex or hermaphroditic. Use U (unknown) when the patient's gender is not known.

personalIdentifiers · PersonalIdentifier[]

An array of the Patient's personal IDs, such as a driver's license. May be empty.

Show PersonalIdentifier properties

type · string · required

The ID type - currently driversLicense is supported.

state · string · required

The 2 letter state acronym where this ID was issued, for example: CA.

value · string · required

The ID number.

address · Address[] · required

Show properties

addressLine1 · string

The address.

addressLine2 · string

The address details, for example: #4451.

city · string

The city.

state · string

The 2 letter state acronym, for example: CA.

zip · string · required

5 digit zip code.

country · string · required

Always "USA".

contact · Contact[]

Show properties

phone · string

The Patient's 10 digit phone number, formatted 1234567899.

email · string

The Patient's email address.

facilityIds · string[] · required

Array of the IDs of the Facilities where the Patient is receiving care.

networkQuery · object

The status of the network query that was kicked off for the patient. Only present when the networkQuery field is included in the request.

Show networkQuery properties

requestId · string · required

The unique identifier for this network query request. Use this to track the query status and correlate webhooks.

startedAt · string · required

ISO 8601 timestamp of when the network query request was initially made.

status · string · required

The overall status of the network query. Can be one of:

• processing - at least one source is still being queried
• completed - all sources have completed successfully
• partial - some sources completed, some failed
• failed - all sources failed

sources · Source[] · required

Array of status objects for each data source being queried. A source type may appear multiple times if it was retried after a failure.

Show Source properties

type · string · required

The type of source: hie, pharmacy, or lab.

status · string · required

The status of this source: processing, completed, or failed.

startedAt · string · required

ISO 8601 timestamp of when this specific source request was initiated.

errors · SourceError[]

Array of errors for data sources that could not be queried. Only present when one or more sources fail to start.

Show SourceError properties

source · string · required

The type of source that failed: hie, pharmacy, or lab.

httpStatus · number · required

The HTTP status code representing the error. Common values: - 400 - Bad Request (access to this data source is not enabled for this account) - 429 - Too Many Requests (rate limit exceeded for this data source)

message · string · required

A human-readable description of the error.

timestamp · string · required

ISO 8601 timestamp of when the error occurred.

Example Response Body (all sources started):

{
  "requestId": "00000000-0000-0000-0000-000000000000",
  "startedAt": "2024-12-30T10:00:00.000Z",
  "status": "processing",
  "sources": [
    {
      "type": "hie",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:00.500Z"
    },
    {
      "type": "pharmacy",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:00.750Z"
    },
    {
      "type": "lab",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:01.000Z"
    }
  ]
}

Example Response Body (with source errors):

{
  "requestId": "00000000-0000-0000-0000-000000000000",
  "startedAt": "2024-12-30T10:00:00.000Z",
  "status": "processing",
  "sources": [
    {
      "type": "hie",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:00.500Z"
    }
  ],
  "errors": [
    {
      "source": "pharmacy",
      "httpStatus": 400,
      "message": "Access to pharmacy data source is not enabled for this account",
      "timestamp": "2024-12-30T10:00:00.600Z"
    },
    {
      "source": "lab",
      "httpStatus": 429,
      "message": "Rate limit exceeded for laboratory data source",
      "timestamp": "2024-12-30T10:00:00.800Z"
    }
  ]
}

Metriport SDK

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const facilityId = "00000000-00000000-00000000-00000000";
const patient = await metriport.createPatient(
  {
    firstName: "Jose",
    lastName: "Juarez",
    dob: "1951-05-05",
    genderAtBirth: "M",
    personalIdentifiers: [
      {
        type: "driversLicense",
        state: USState.CA,
        value: "51227265",
      },
    ],
    address: [
      {
        zip: "12345",
        city: "San Diego",
        state: USState.CA,
        country: "USA",
        addressLine1: "Guadalajara Street"
      },
    ],
    contact: [
      {
        phone: "1234567899",
        email: "[e-mail]",
      },
    ],
    externalId: "123456789",
    status: { 
      hieOptOut: false,
      treatmentRelationship: true
    },
    cohorts: ["00000000-00000000-00000000-00000000"]
  },
  facilityId
);

{
  "id": "018a80c4-292a-7486-a1234-76yuhe23yu14",
  "externalId": "1234567890",
  "status": {
    "hieOptOut": false,
    "treatmentRelationship": true
  },
  "additionalIds": { 
    "athenahealth": ["43210"], 
    "canvas": ["1234567890"], 
    "elation": ["0987654321"] 
  },
  "facilityIds": ["018a80c4-292a-7486-a1234-9uiu76yhe234"],
  "firstName": "Jose",
  "lastName": "Juarez",
  "dob": "1951-05-05",
  "genderAtBirth": "M",
  "personalIdentifiers": [
    {
      "type": "driversLicense",
      "state": "CA",
      "value": "51227265"
    }
  ],
  "address": [
    {
      "zip": "12345",
      "city": "San Diego",
      "state": "CA",
      "country": "USA",
      "addressLine1": "Guadalajara St"
    }
  ],
  "contact": [
    {
      "phone": "1234567899",
      "email": "[e-mail]"
    }
  ],
}

Rate Limits

See limits and throttling