Currently, a max of 100,000 patients in a batch is
supported.
This is an asynchronous endpoint: you upload a file with
patient demographics, and we notify you when the process
is completed through a webhook
message.

Input CSV File Format
The file with the patient demographics should be created as comma-separated values, CSV. You can access an example of the file here. We support up to 10 addresses, 10 email addresses, and 10 phone numbers. In order to provide those, just index each column with-N
at the end of the column name, where N
is the index (1-10).
Column headers are case sensitive. Be sure to match them exactly as shown in the example file; otherwise the whole file may be marked as invalid.
… | zip* | email-1 | email-2 | email-3 | … |
---|---|---|---|---|---|
… | 12345 | some@domain.com | another@domain.com | … | |
… | 12312 | avocado@food.com | … | ||
… | 99887 | lawyer@job.com | personal@domain.com | family@domain.com | … |
addressLine1-2
, then all address fields
with index 2
are required (otherwise, the respective row/Patient will be marked as invalid).
Following this logic, if you don’t provide any address field for index 3
through 10
, all the
address fields for those indexes are disconsidered, and the Patient is considered valid (assuming
other non-address fields are valid too).
At least one complete address must be provided:
- addressLine1-1
- addressLine2-1
- city-1
- state-1
- zip-1
Validation
This endpoint validates access to the provided Facility ID (or that there’s only one if omitted). It will return a404
if the facility can’t be found or 400
if there’s more than one Facility
and the ID was not provided.
Once the CSV is uploaded, the Metriport API will also validate the file is in the expected format
(CSV). It might set the status of the request to failed
and send a corresponding webhook message.
If those previous validations are successful, each row will be validated individually and it’s
respective status will be stored so it can be reviewed in the
result CSV file (it won’t fail the whole
request at this point).
Uploading the CSV
The URL is pre-signed to your account and has a duration of 10 minutes. It should only be used once. Use it to send aPUT
request like so:
Webhook with the result
Once the CSV file is uploaded, the Metriport API starts processing it and sends a webhook message to your App indicating the status isprocessing
. Once the patiets are created and their medical
data is available, we send a new webhook message indicating the request is done, including
a link to the resulting CSV file that contains the newly created Metriport IDs for the
successfully created Patients.
Bulk Patient Create Status
During the processing of a bulk patient create, the request can change status following the logic below:
waiting
: initial state, waiting for the CSV file;processing
: the CSV file has been uploaded and is being processed;completed
: the bulk create is completed;failed
: the bulk create failed (likely due to an uploaded file with invalid format);expired
: no file has been uploaded and the upload URL expired.
Query Params
The ID of the Facility where the Patients receive care.
All patients in a single request/CSV will be associated
with the same Facility. It can be omitted if there’s only
one Facility in your account.
When set to
true
, no Patients will be created, and this
request is only used to validate the CSV file and provide
feedback about each Patient demographics. Defaults to
false
.Body
No body is accepted/processed.Response
The ID that represents this bulk patient create.
The status of the bulk bulk patient create. Always
waiting
. See all the possible values
here.The URL to upload the CSV file containing the Patient
demographics to be used to create new Patients. It’s valid
for 10 minutes and should only be used once. See more
details here