Match Patient

curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/patient/match \
  --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>"
    }
  ]
}
'

import requests

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

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>"
        }
    ]
}
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>'}]
  })
};

fetch('https://api.sandbox.metriport.com/medical/v1/patient/match', 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/match",
  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>'
        ]
    ]
  ]),
  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/match"

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

	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/match")
  .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}")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const patient = await metriport.matchPatient(
  {
    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",
      },
    ],
  },
);

POST

medical

patient

match

Match Patient

curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/patient/match \
  --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>"
    }
  ]
}
'

import requests

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

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>"
        }
    ]
}
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>'}]
  })
};

fetch('https://api.sandbox.metriport.com/medical/v1/patient/match', 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/match",
  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>'
        ]
    ]
  ]),
  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/match"

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

	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/match")
  .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}")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const patient = await metriport.matchPatient(
  {
    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",
      },
    ],
  },
);

Body

The more demographic information you can provide about a Patient, the higher chances Metriport will be able to find a match previously created in Metriport. 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)

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.

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const patient = await metriport.matchPatient(
  {
    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",
      },
    ],
  },
);

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

Getting Started

API Reference

Handling Data

FHIR

API Tools

More Info

Legacy API Reference

Match Patient

Body

Response