Create Patient
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>",
"additionalIds": {
"healthix": [
"<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>",
"additionalIds": { "healthix": ["<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>',
additionalIds: {healthix: ['<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>',
'additionalIds' => [
'healthix' => [
'<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 \"additionalIds\": {\n \"healthix\": [\n \"<string>\"\n ]\n },\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 \"additionalIds\": {\n \"healthix\": [\n \"<string>\"\n ]\n },\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 \"additionalIds\": {\n \"healthix\": [\n \"<string>\"\n ]\n },\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_bodyimport { 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: "jose@domain.com",
},
],
externalId: "123456789",
status: {
hieOptOut: false,
treatmentRelationship: true
},
cohorts: ["00000000-00000000-00000000-00000000"]
},
facilityId
);
Patient
Create Patient
Creates a Patient in Metriport for the specified Facility where the patient is receiving care.
Listen to this page5 sec
POST
/
medical
/
v1
/
patient
Create Patient
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>",
"additionalIds": {
"healthix": [
"<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>",
"additionalIds": { "healthix": ["<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>',
additionalIds: {healthix: ['<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>',
'additionalIds' => [
'healthix' => [
'<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 \"additionalIds\": {\n \"healthix\": [\n \"<string>\"\n ]\n },\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 \"additionalIds\": {\n \"healthix\": [\n \"<string>\"\n ]\n },\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 \"additionalIds\": {\n \"healthix\": [\n \"<string>\"\n ]\n },\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_bodyimport { 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: "jose@domain.com",
},
],
externalId: "123456789",
status: {
hieOptOut: false,
treatmentRelationship: true
},
cohorts: ["00000000-00000000-00000000-00000000"]
},
facilityId
);
Query Params
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"].The Patient's date of birth (DOB), formatted
YYYY-MM-DD
as per ISO 8601.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.An array of the Patient's personal IDs, such as a driver's license or SSN. May be empty.
An array of
Address objects, representing the Patient's current and/or previous addresses.Show Address properties
Show Address properties
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.
An array of
Contact objects, representing the Patient's current and/or previous contact information. May be empty.Show Contact properties
Show Contact properties
The Patient's email address. Supports a wide range of valid email formats including special characters.Valid email examples:
user@example.comtest!user@example.comuser+tag@example.comuser_name@example.comuser-name@example.comuser.name@example.com
invalid-email(missing @ and domain)user@(missing domain)@example.com(missing local part)+1234567890@example.com(phone number format)mailto:user@example.com(mailto: prefix not allowed)
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.Additional external identifiers for this patient. Currently only
healthix may be set on create/update.Show additionalIds properties
Show additionalIds properties
EHR identifiers (
athenahealth, canvas, elation, healthie) are populated by our
EHR apps and cannot be set via this field. Omitting additionalIds
leaves existing mappings unchanged. If the Healthix MRN cannot be applied (e.g. conflict),
the patient create/update still succeeds — check additionalIds.healthix on the response
(or a subsequent GET) to confirm the mapping.Patient status flags for HIE opt-out and treatment relationship consent.
Show status properties
Show status properties
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.The list of cohort IDs this patient should be assigned to.
See Working With Cohorts to learn more about how to use this field.
When provided, kicks off a network query
for the patient.
Example Request Body:
Show networkQuery properties
Show networkQuery properties
Data sources to query. At least one source must be enabled.
Show Source configuration
Show Source configuration
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.Required when the
purposeOfUse query parameter is ias. The verified identity returned on the
ias.identity.verified webhook.Custom metadata to include with the request. This will be returned in webhook payloads.
Show Metadata properties
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.
{
"sources": {
"hie": { "enabled": true },
"pharmacy": { "enabled": true, "realtime": true },
"lab": { "enabled": true }
},
"metadata": {
"youCan": "putAny",
"stringKeyValue": "pairsHere"
}
}
Response
The ID assigned to this Patient. This ID will be used to uniquely identify this Patient in medical
documents.
A map containing additional external identifiers. EHR IDs are populated when the patient is
created or mapped through one of our EHR apps. The
healthix ID can also
be set by customers on patient create/update, and is included in webhook payloads when present.Show AdditionalIdentifiers properties
Show AdditionalIdentifiers properties
Athena patient ID. If more than one patient in Athena maps to a Metriport patient, they
will all be included.
Canvas patient ID. If more than one patient in Canvas maps to a Metriport patient, they
will all be included.
Elation Patient ID. If more than one patient in Elation maps to a Metriport patient, they
will all be included.
Healthie Patient ID. If more than one patient in Healthie maps to a Metriport patient, they
will all be included.
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.The status of the network query that was
kicked off for the patient. Only present when the
Example Response Body (all sources started):Example Response Body (with source errors):
networkQuery field is included in the request.Show networkQuery properties
Show networkQuery properties
The unique identifier for this network query request. Use
this to track the query status and correlate webhooks.
The overall status of the network query. Can be one of:
processing- at least one source is still being queriedcompleted- all sources have completed successfullypartial- some sources completed, some failedfailed- all sources failed
Array of status objects for each data source being
queried. A source type may appear multiple times if it was
retried after a failure.
Array of errors for data sources that could not be
queried. Only present when one or more sources fail to
start.
Show SourceError properties
Show SourceError properties
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){
"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"
}
]
}
{
"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"
}
]
}
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: "jose@domain.com",
},
],
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"],
"healthix": ["MRN123456"]
},
"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": "jose@domain.com"
}
]
}

