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_body

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
);

POST

medical

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_body

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
);

Query Params

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"].

string

required

The Patient's first name(s).

string

required

The Patient's last name(s).

string

required

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

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.

PersonalIdentifier[]

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

Show PersonalIdentifier properties

string

required

The ID type - currently driversLicense or ssn is supported.

string

required

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

string

required

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

Address[]

required

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

Show Address properties

string

required

The address.

string

The address details, for example: #4451.

string

required

The city.

string

required

The 2 letter state acronym, for example: CA.

string

required

5 digit zip code.

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[]

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

Show Contact properties

string

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

string

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

user@example.com
test!user@example.com
user+tag@example.com
user_name@example.com
user-name@example.com
user.name@example.com

Invalid email examples:

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)

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.

object

Additional external identifiers for this patient. Currently only healthix may be set on create/update.

Show additionalIds properties

string[]

Healthix MRN for this patient. When additionalIds is provided, this must be present and contain exactly one non-empty string.

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.

object

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

Show status properties

boolean

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

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.

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.

object

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

Show networkQuery properties

object

required

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

Show Source configuration

object

HIE (Health Information Exchange) source configuration.

Show HIE options

boolean

required

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

object

Pharmacy source configuration.

Show Pharmacy options

boolean

required

Whether to query pharmacy sources.

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!

object

Laboratory source configuration.

Show Lab options

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.

string

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

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

string

required

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

string

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

object

required

Patient status flags.

Show status properties

boolean

required

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

boolean

required

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

AdditionalIdentifiers

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

string[]

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

string[]

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

string[]

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

string[]

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

string[]

Healthix MRN for this patient.

string[]

required

The Patient's first name(s).

string[]

required

The Patient's last name(s).

string

required

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

string

required

PersonalIdentifier[]

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

Show PersonalIdentifier properties

string

required

The ID type - currently driversLicense is supported.

string

required

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

string

required

The ID number.

Address[]

required

Show properties

string

The address.

string

The address details, for example: #4451.

string

The city.

string

The 2 letter state acronym, for example: CA.

string

required

5 digit zip code.

string

required

Always "USA".

Contact[]

Show properties

string

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

string

The Patient's email address.

string[]

required

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

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

string

required

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

string

required

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

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

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

string

required

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

string

required

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

string

required

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

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

string

required

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

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)

string

required

A human-readable description of the error.

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"
    }
  ]
}

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"
    }
  ]
}

Rate Limits

See limits and throttling

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

Create Patient

Query Params

Body

Response

Rate Limits

​Query Params

​Body

​Response

​Rate Limits

Query Params

Body

Response

Rate Limits