Upload Document

Creates a DocumentReference and returns its ID and a URL to use for a medical document upload to our servers.

POST /medical/v1/document/upload

Upload Document

cURL

curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/document/upload \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": {
    "text": "<string>",
    "coding": [
      {}
    ]
  },
  "description": "<string>",
  "context": [
    {
      "period": {},
      "facilityType": {
        "text": "<string>"
      }
    }
  ]
}
'

import requests

url = "https://api.sandbox.metriport.com/medical/v1/document/upload"

payload = {
    "type": {
        "text": "<string>",
        "coding": [{}]
    },
    "description": "<string>",
    "context": [
        {
            "period": {},
            "facilityType": { "text": "<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({
    type: {text: '<string>', coding: [{}]},
    description: '<string>',
    context: [{period: {}, facilityType: {text: '<string>'}}]
  })
};

fetch('https://api.sandbox.metriport.com/medical/v1/document/upload', 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/document/upload",
  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([
    'type' => [
        'text' => '<string>',
        'coding' => [
                [
                                
                ]
        ]
    ],
    'description' => '<string>',
    'context' => [
        [
                'period' => [
                                
                ],
                'facilityType' => [
                                'text' => '<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/document/upload"

	payload := strings.NewReader("{\n  \"type\": {\n    \"text\": \"<string>\",\n    \"coding\": [\n      {}\n    ]\n  },\n  \"description\": \"<string>\",\n  \"context\": [\n    {\n      \"period\": {},\n      \"facilityType\": {\n        \"text\": \"<string>\"\n      }\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/document/upload")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": {\n    \"text\": \"<string>\",\n    \"coding\": [\n      {}\n    ]\n  },\n  \"description\": \"<string>\",\n  \"context\": [\n    {\n      \"period\": {},\n      \"facilityType\": {\n        \"text\": \"<string>\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"type\": {\n    \"text\": \"<string>\",\n    \"coding\": [\n      {}\n    ]\n  },\n  \"description\": \"<string>\",\n  \"context\": [\n    {\n      \"period\": {},\n      \"facilityType\": {\n        \"text\": \"<string>\"\n      }\n    }\n  ]\n}"

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

Metriport SDK

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");
const docRef: Partial<DocumentReference> = {
  description: "Third degree wrist burn treatment",
  type: {
    text: "Burn management Hospital Progress note",
    coding: [
      {
        code: "100556-0",
        system: "http://loinc.org",
        display: "Burn management Hospital Progress note",
      },
    ],
  },
  context: {
    period: {
      start: "2023-10-10T14:14:17Z",
    },
    facilityType: {
      text: "My Clinic Name - Acute Care",
    },
  },
};

const resp = await metriport.createDocumentReference("018a80c4-292a-7486-a1234-76yuhe23yu14", docRef);

// Upload the document using this url in a PUT request, something along these lines for a PDF:

// const fileContent = <medical-document-document-contents>;
// await axios.put(resp.uploadUrl, fileContent, {
//     headers: {
//         "Content-Length": <size-in-bytes>,
//         "Content-Type": "application/pdf",
//     },
// });

This endpoint returns the DocumentReference ID and a URL to enable you to upload your patients’ medical documents, making them available to other HIEs.

Overview

To use this endpoint, you will need to follow these steps:

1. Create a DocumentReference to describe the document that’s being uploaded (see sections below for details on the expected fields and format).

2. Execute the endpoint and receive a URL to use for the document upload.

3. Upload the document by executing a PUT request using the URL with a Content-Length header specifying the size of the document.

Uploads are limited to 50MB per file.

Query Params

patientId · string · required

The ID of the Patient.

Body

A FHIR DocumentReference.

type · CodeableConcept · required

A CodeableConcept of the document type.

Show Type properties

text · string · required

Plain text representation of the document kind - for example Burn management Hospital Progress note

coding · Coding[]

A Coding property, which is a reference to a code defined by a terminology system (such as LOINC) - for example [{ code: "100556-0", system: "http://loinc.org", display: "Burn management Hospital Progress note"}]

description · string · required

A brief description of the document - for example Discharge Summary.

context · DocumentReferenceContext[] · required

Context of the document content.

Show Context properties

period · Period · required

A time Period property including ISO 8601 timestamp(s) - for example { start: "2023-10-10T14:14:17Z" },

facilityType · CodeableConcept

An object that represents the facility type.

Show Facility type properties

text · string

Plain text with the facility name and type - for example John Snow Clinic - Acute Care Centre.

Note that you do not need to include a Patient or Organization resource in the contained property, as those will be inferred on our end - if you do, they will be overwritten.

Example Payload:

{
  description: "Third degree wrist burn treatment",
  type: {
    text: "Burn management Hospital Progress note",
    coding: [
      {
        code: "100556-0",
        system: "http://loinc.org",
        display: "Burn management Hospital Progress note"
      },
    ],
  },
  context: {
    period: {
      start: "2023-10-10T14:14:17Z",
      end: "2023-10-10T15:30:30Z",
    },
    facilityType: {
      text: "John Snow Clinic - Acute Care Centre",
    },
  },
};

Response

The DocumentReference ID and a URL to be used for file upload.

{
  "documentReferenceId": "<DocumentReference-ID-string>",
  "uploadUrl": "<url-string>"
}

Metriport SDK

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");
const docRef: Partial<DocumentReference> = {
  description: "Third degree wrist burn treatment",
  type: {
    text: "Burn management Hospital Progress note",
    coding: [
      {
        code: "100556-0",
        system: "http://loinc.org",
        display: "Burn management Hospital Progress note",
      },
    ],
  },
  context: {
    period: {
      start: "2023-10-10T14:14:17Z",
    },
    facilityType: {
      text: "My Clinic Name - Acute Care",
    },
  },
};

const resp = await metriport.createDocumentReference("018a80c4-292a-7486-a1234-76yuhe23yu14", docRef);

// Upload the document using this url in a PUT request, something along these lines for a PDF:

// const fileContent = <medical-document-document-contents>;
// await axios.put(resp.uploadUrl, fileContent, {
//     headers: {
//         "Content-Length": <size-in-bytes>,
//         "Content-Type": "application/pdf",
//     },
// });