POST
/
medical
/
v1
/
patient
/
bulk
Bulk Patient Create
curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/patient/bulk
The Bulk Patient Create endpoint allows you to create and kick off Document Queries for a batch of Patients in a single request.
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.
The response to this endpoint contains a URL that you should use to upload a file containing the Patient demographics that will be used to create individual Patients. More on this below.

​
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.
Example The first Patient below has two email addresses, the second Patient only has one email, and the third Patient has three email addresses:
…zip*email-1email-2email-3…
…12345some@domain.comanother@domain.com…
…12312avocado@food.com…
…99887lawyer@job.compersonal@domain.comfamily@domain.com…
For address fields, they work as a group: if you provide 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
For information about the result file, see this.

​
Validation

This endpoint validates access to the provided Facility ID (or that there’s only one if omitted). It will return a 404 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 a PUT request like so: 
curl --location --request PUT '<UPLOAD-URL>' \
--header 'Content-Type: text/csv' \
--header 'x-api-key: <YOUR-API-KEY>' \
--data-binary '@/local-to-your/file.csv'

​
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 is processing. 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

​
facilityId
string
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.
​
dryRun
boolean
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

​
requestId
string
required
The ID that represents this bulk patient create.
​
status
string
required
The status of the bulk bulk patient create. Always waiting. See all the possible values here.
​
uploadUrl
string
required
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
Coming soon.
{
  "requestId": "00000000-00000000-00000000-00000000",
  "status": "waiting",
  "uploadUrl": "<presigned-upload-url>"
}