Create retrieval with case and Requestor
curl --request POST \
--url https://enterprise.tavrn.ai/v2/retrieval-requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"patient": {
"name": "Jane Doe",
"date_of_birth": "1989-04-12",
"address": "123 Main St, Austin, TX 78701",
"phone": "+1-512-555-0101",
"email": "jane@example.com",
"gender": "F",
"ssn": "<string>"
},
"facility": {
"name": "Example General Hospital",
"address_line1": "100 Example Ave",
"city": "Springfield",
"state": "PA",
"zip_code": "00000",
"address_line2": null,
"phone": "+1-555-010-2000",
"fax": "+1-555-010-1111"
},
"auth_form": {
"upload_id": "11111111-1111-4111-8111-111111111111",
"file_name": "jane_doe_hipaa.pdf",
"signer_name": "Mary Doe",
"signer_relationship": "Mother"
},
"requested_records": [
{
"type": "medical_records",
"custom_label": null,
"deliverable_format": null,
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"requirements": []
}
],
"case_id": "111111111111111111111111",
"facility_id": "facility_example",
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"notes": "Please include any radiology read reports",
"submitter_email": "jane.smith@example.com",
"attachments": [],
"requestor_id": "111111111111111111111111",
"allow_duplicate": true
}
'import requests
url = "https://enterprise.tavrn.ai/v2/retrieval-requests"
payload = {
"patient": {
"name": "Jane Doe",
"date_of_birth": "1989-04-12",
"address": "123 Main St, Austin, TX 78701",
"phone": "+1-512-555-0101",
"email": "jane@example.com",
"gender": "F",
"ssn": "<string>"
},
"facility": {
"name": "Example General Hospital",
"address_line1": "100 Example Ave",
"city": "Springfield",
"state": "PA",
"zip_code": "00000",
"address_line2": None,
"phone": "+1-555-010-2000",
"fax": "+1-555-010-1111"
},
"auth_form": {
"upload_id": "11111111-1111-4111-8111-111111111111",
"file_name": "jane_doe_hipaa.pdf",
"signer_name": "Mary Doe",
"signer_relationship": "Mother"
},
"requested_records": [
{
"type": "medical_records",
"custom_label": None,
"deliverable_format": None,
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"requirements": []
}
],
"case_id": "111111111111111111111111",
"facility_id": "facility_example",
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"notes": "Please include any radiology read reports",
"submitter_email": "jane.smith@example.com",
"attachments": [],
"requestor_id": "111111111111111111111111",
"allow_duplicate": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
patient: {
name: 'Jane Doe',
date_of_birth: '1989-04-12',
address: '123 Main St, Austin, TX 78701',
phone: '+1-512-555-0101',
email: 'jane@example.com',
gender: 'F',
ssn: '<string>'
},
facility: {
name: 'Example General Hospital',
address_line1: '100 Example Ave',
city: 'Springfield',
state: 'PA',
zip_code: '00000',
address_line2: null,
phone: '+1-555-010-2000',
fax: '+1-555-010-1111'
},
auth_form: {
upload_id: '11111111-1111-4111-8111-111111111111',
file_name: 'jane_doe_hipaa.pdf',
signer_name: 'Mary Doe',
signer_relationship: 'Mother'
},
requested_records: [
{
type: 'medical_records',
custom_label: null,
deliverable_format: null,
service_start_date: '2024-03-15',
service_end_date: '2024-09-30',
requirements: []
}
],
case_id: '111111111111111111111111',
facility_id: 'facility_example',
service_start_date: '2024-03-15',
service_end_date: '2024-09-30',
notes: 'Please include any radiology read reports',
submitter_email: 'jane.smith@example.com',
attachments: [],
requestor_id: '111111111111111111111111',
allow_duplicate: true
})
};
fetch('https://enterprise.tavrn.ai/v2/retrieval-requests', 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://enterprise.tavrn.ai/v2/retrieval-requests",
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([
'patient' => [
'name' => 'Jane Doe',
'date_of_birth' => '1989-04-12',
'address' => '123 Main St, Austin, TX 78701',
'phone' => '+1-512-555-0101',
'email' => 'jane@example.com',
'gender' => 'F',
'ssn' => '<string>'
],
'facility' => [
'name' => 'Example General Hospital',
'address_line1' => '100 Example Ave',
'city' => 'Springfield',
'state' => 'PA',
'zip_code' => '00000',
'address_line2' => null,
'phone' => '+1-555-010-2000',
'fax' => '+1-555-010-1111'
],
'auth_form' => [
'upload_id' => '11111111-1111-4111-8111-111111111111',
'file_name' => 'jane_doe_hipaa.pdf',
'signer_name' => 'Mary Doe',
'signer_relationship' => 'Mother'
],
'requested_records' => [
[
'type' => 'medical_records',
'custom_label' => null,
'deliverable_format' => null,
'service_start_date' => '2024-03-15',
'service_end_date' => '2024-09-30',
'requirements' => [
]
]
],
'case_id' => '111111111111111111111111',
'facility_id' => 'facility_example',
'service_start_date' => '2024-03-15',
'service_end_date' => '2024-09-30',
'notes' => 'Please include any radiology read reports',
'submitter_email' => 'jane.smith@example.com',
'attachments' => [
],
'requestor_id' => '111111111111111111111111',
'allow_duplicate' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://enterprise.tavrn.ai/v2/retrieval-requests"
payload := strings.NewReader("{\n \"patient\": {\n \"name\": \"Jane Doe\",\n \"date_of_birth\": \"1989-04-12\",\n \"address\": \"123 Main St, Austin, TX 78701\",\n \"phone\": \"+1-512-555-0101\",\n \"email\": \"jane@example.com\",\n \"gender\": \"F\",\n \"ssn\": \"<string>\"\n },\n \"facility\": {\n \"name\": \"Example General Hospital\",\n \"address_line1\": \"100 Example Ave\",\n \"city\": \"Springfield\",\n \"state\": \"PA\",\n \"zip_code\": \"00000\",\n \"address_line2\": null,\n \"phone\": \"+1-555-010-2000\",\n \"fax\": \"+1-555-010-1111\"\n },\n \"auth_form\": {\n \"upload_id\": \"11111111-1111-4111-8111-111111111111\",\n \"file_name\": \"jane_doe_hipaa.pdf\",\n \"signer_name\": \"Mary Doe\",\n \"signer_relationship\": \"Mother\"\n },\n \"requested_records\": [\n {\n \"type\": \"medical_records\",\n \"custom_label\": null,\n \"deliverable_format\": null,\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"requirements\": []\n }\n ],\n \"case_id\": \"111111111111111111111111\",\n \"facility_id\": \"facility_example\",\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"notes\": \"Please include any radiology read reports\",\n \"submitter_email\": \"jane.smith@example.com\",\n \"attachments\": [],\n \"requestor_id\": \"111111111111111111111111\",\n \"allow_duplicate\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://enterprise.tavrn.ai/v2/retrieval-requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"patient\": {\n \"name\": \"Jane Doe\",\n \"date_of_birth\": \"1989-04-12\",\n \"address\": \"123 Main St, Austin, TX 78701\",\n \"phone\": \"+1-512-555-0101\",\n \"email\": \"jane@example.com\",\n \"gender\": \"F\",\n \"ssn\": \"<string>\"\n },\n \"facility\": {\n \"name\": \"Example General Hospital\",\n \"address_line1\": \"100 Example Ave\",\n \"city\": \"Springfield\",\n \"state\": \"PA\",\n \"zip_code\": \"00000\",\n \"address_line2\": null,\n \"phone\": \"+1-555-010-2000\",\n \"fax\": \"+1-555-010-1111\"\n },\n \"auth_form\": {\n \"upload_id\": \"11111111-1111-4111-8111-111111111111\",\n \"file_name\": \"jane_doe_hipaa.pdf\",\n \"signer_name\": \"Mary Doe\",\n \"signer_relationship\": \"Mother\"\n },\n \"requested_records\": [\n {\n \"type\": \"medical_records\",\n \"custom_label\": null,\n \"deliverable_format\": null,\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"requirements\": []\n }\n ],\n \"case_id\": \"111111111111111111111111\",\n \"facility_id\": \"facility_example\",\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"notes\": \"Please include any radiology read reports\",\n \"submitter_email\": \"jane.smith@example.com\",\n \"attachments\": [],\n \"requestor_id\": \"111111111111111111111111\",\n \"allow_duplicate\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://enterprise.tavrn.ai/v2/retrieval-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"patient\": {\n \"name\": \"Jane Doe\",\n \"date_of_birth\": \"1989-04-12\",\n \"address\": \"123 Main St, Austin, TX 78701\",\n \"phone\": \"+1-512-555-0101\",\n \"email\": \"jane@example.com\",\n \"gender\": \"F\",\n \"ssn\": \"<string>\"\n },\n \"facility\": {\n \"name\": \"Example General Hospital\",\n \"address_line1\": \"100 Example Ave\",\n \"city\": \"Springfield\",\n \"state\": \"PA\",\n \"zip_code\": \"00000\",\n \"address_line2\": null,\n \"phone\": \"+1-555-010-2000\",\n \"fax\": \"+1-555-010-1111\"\n },\n \"auth_form\": {\n \"upload_id\": \"11111111-1111-4111-8111-111111111111\",\n \"file_name\": \"jane_doe_hipaa.pdf\",\n \"signer_name\": \"Mary Doe\",\n \"signer_relationship\": \"Mother\"\n },\n \"requested_records\": [\n {\n \"type\": \"medical_records\",\n \"custom_label\": null,\n \"deliverable_format\": null,\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"requirements\": []\n }\n ],\n \"case_id\": \"111111111111111111111111\",\n \"facility_id\": \"facility_example\",\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"notes\": \"Please include any radiology read reports\",\n \"submitter_email\": \"jane.smith@example.com\",\n \"attachments\": [],\n \"requestor_id\": \"111111111111111111111111\",\n \"allow_duplicate\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "rr_abc123",
"order_number": "T-ABC-12345",
"case_id": "case_abc123",
"status": "received",
"created_at": "2025-02-01T12:50:00Z",
"updated_at": "2025-02-01T12:50:00Z",
"requestor_id": "111111111111111111111111"
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "duplicate_request_detected",
"message": "<string>"
},
"duplicates": [
{
"id": "<string>",
"order_number": "<string>",
"classification": "EXACT",
"overlapping_record_types": [
"<string>"
],
"cross_case": true
}
]
}Retrieval Requests
Create retrieval with case and Requestor
Create a retrieval using patient and requested_records, plus exactly one of facility_id from GET /v2/facilities or a manual facility object. Provide either case_id or an inline case. Use requestor_id for an existing profile, an inline requestor to create one, or neither to use the organization default. Inline case and requestor objects can be created together with the retrieval. Upload authorization forms and attachments through POST /v2/retrieval-requests/sign-upload, and Requestor profile documents through POST /v2/requestors/sign-upload, before creating the retrieval. Requires retrievals:write, plus cases:write for an inline case and requestors:write for an inline Requestor. Each successful POST with an inline case or Requestor creates a new one; retain the returned IDs for reuse.
POST
/
v2
/
retrieval-requests
Create retrieval with case and Requestor
curl --request POST \
--url https://enterprise.tavrn.ai/v2/retrieval-requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"patient": {
"name": "Jane Doe",
"date_of_birth": "1989-04-12",
"address": "123 Main St, Austin, TX 78701",
"phone": "+1-512-555-0101",
"email": "jane@example.com",
"gender": "F",
"ssn": "<string>"
},
"facility": {
"name": "Example General Hospital",
"address_line1": "100 Example Ave",
"city": "Springfield",
"state": "PA",
"zip_code": "00000",
"address_line2": null,
"phone": "+1-555-010-2000",
"fax": "+1-555-010-1111"
},
"auth_form": {
"upload_id": "11111111-1111-4111-8111-111111111111",
"file_name": "jane_doe_hipaa.pdf",
"signer_name": "Mary Doe",
"signer_relationship": "Mother"
},
"requested_records": [
{
"type": "medical_records",
"custom_label": null,
"deliverable_format": null,
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"requirements": []
}
],
"case_id": "111111111111111111111111",
"facility_id": "facility_example",
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"notes": "Please include any radiology read reports",
"submitter_email": "jane.smith@example.com",
"attachments": [],
"requestor_id": "111111111111111111111111",
"allow_duplicate": true
}
'import requests
url = "https://enterprise.tavrn.ai/v2/retrieval-requests"
payload = {
"patient": {
"name": "Jane Doe",
"date_of_birth": "1989-04-12",
"address": "123 Main St, Austin, TX 78701",
"phone": "+1-512-555-0101",
"email": "jane@example.com",
"gender": "F",
"ssn": "<string>"
},
"facility": {
"name": "Example General Hospital",
"address_line1": "100 Example Ave",
"city": "Springfield",
"state": "PA",
"zip_code": "00000",
"address_line2": None,
"phone": "+1-555-010-2000",
"fax": "+1-555-010-1111"
},
"auth_form": {
"upload_id": "11111111-1111-4111-8111-111111111111",
"file_name": "jane_doe_hipaa.pdf",
"signer_name": "Mary Doe",
"signer_relationship": "Mother"
},
"requested_records": [
{
"type": "medical_records",
"custom_label": None,
"deliverable_format": None,
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"requirements": []
}
],
"case_id": "111111111111111111111111",
"facility_id": "facility_example",
"service_start_date": "2024-03-15",
"service_end_date": "2024-09-30",
"notes": "Please include any radiology read reports",
"submitter_email": "jane.smith@example.com",
"attachments": [],
"requestor_id": "111111111111111111111111",
"allow_duplicate": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
patient: {
name: 'Jane Doe',
date_of_birth: '1989-04-12',
address: '123 Main St, Austin, TX 78701',
phone: '+1-512-555-0101',
email: 'jane@example.com',
gender: 'F',
ssn: '<string>'
},
facility: {
name: 'Example General Hospital',
address_line1: '100 Example Ave',
city: 'Springfield',
state: 'PA',
zip_code: '00000',
address_line2: null,
phone: '+1-555-010-2000',
fax: '+1-555-010-1111'
},
auth_form: {
upload_id: '11111111-1111-4111-8111-111111111111',
file_name: 'jane_doe_hipaa.pdf',
signer_name: 'Mary Doe',
signer_relationship: 'Mother'
},
requested_records: [
{
type: 'medical_records',
custom_label: null,
deliverable_format: null,
service_start_date: '2024-03-15',
service_end_date: '2024-09-30',
requirements: []
}
],
case_id: '111111111111111111111111',
facility_id: 'facility_example',
service_start_date: '2024-03-15',
service_end_date: '2024-09-30',
notes: 'Please include any radiology read reports',
submitter_email: 'jane.smith@example.com',
attachments: [],
requestor_id: '111111111111111111111111',
allow_duplicate: true
})
};
fetch('https://enterprise.tavrn.ai/v2/retrieval-requests', 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://enterprise.tavrn.ai/v2/retrieval-requests",
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([
'patient' => [
'name' => 'Jane Doe',
'date_of_birth' => '1989-04-12',
'address' => '123 Main St, Austin, TX 78701',
'phone' => '+1-512-555-0101',
'email' => 'jane@example.com',
'gender' => 'F',
'ssn' => '<string>'
],
'facility' => [
'name' => 'Example General Hospital',
'address_line1' => '100 Example Ave',
'city' => 'Springfield',
'state' => 'PA',
'zip_code' => '00000',
'address_line2' => null,
'phone' => '+1-555-010-2000',
'fax' => '+1-555-010-1111'
],
'auth_form' => [
'upload_id' => '11111111-1111-4111-8111-111111111111',
'file_name' => 'jane_doe_hipaa.pdf',
'signer_name' => 'Mary Doe',
'signer_relationship' => 'Mother'
],
'requested_records' => [
[
'type' => 'medical_records',
'custom_label' => null,
'deliverable_format' => null,
'service_start_date' => '2024-03-15',
'service_end_date' => '2024-09-30',
'requirements' => [
]
]
],
'case_id' => '111111111111111111111111',
'facility_id' => 'facility_example',
'service_start_date' => '2024-03-15',
'service_end_date' => '2024-09-30',
'notes' => 'Please include any radiology read reports',
'submitter_email' => 'jane.smith@example.com',
'attachments' => [
],
'requestor_id' => '111111111111111111111111',
'allow_duplicate' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://enterprise.tavrn.ai/v2/retrieval-requests"
payload := strings.NewReader("{\n \"patient\": {\n \"name\": \"Jane Doe\",\n \"date_of_birth\": \"1989-04-12\",\n \"address\": \"123 Main St, Austin, TX 78701\",\n \"phone\": \"+1-512-555-0101\",\n \"email\": \"jane@example.com\",\n \"gender\": \"F\",\n \"ssn\": \"<string>\"\n },\n \"facility\": {\n \"name\": \"Example General Hospital\",\n \"address_line1\": \"100 Example Ave\",\n \"city\": \"Springfield\",\n \"state\": \"PA\",\n \"zip_code\": \"00000\",\n \"address_line2\": null,\n \"phone\": \"+1-555-010-2000\",\n \"fax\": \"+1-555-010-1111\"\n },\n \"auth_form\": {\n \"upload_id\": \"11111111-1111-4111-8111-111111111111\",\n \"file_name\": \"jane_doe_hipaa.pdf\",\n \"signer_name\": \"Mary Doe\",\n \"signer_relationship\": \"Mother\"\n },\n \"requested_records\": [\n {\n \"type\": \"medical_records\",\n \"custom_label\": null,\n \"deliverable_format\": null,\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"requirements\": []\n }\n ],\n \"case_id\": \"111111111111111111111111\",\n \"facility_id\": \"facility_example\",\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"notes\": \"Please include any radiology read reports\",\n \"submitter_email\": \"jane.smith@example.com\",\n \"attachments\": [],\n \"requestor_id\": \"111111111111111111111111\",\n \"allow_duplicate\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://enterprise.tavrn.ai/v2/retrieval-requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"patient\": {\n \"name\": \"Jane Doe\",\n \"date_of_birth\": \"1989-04-12\",\n \"address\": \"123 Main St, Austin, TX 78701\",\n \"phone\": \"+1-512-555-0101\",\n \"email\": \"jane@example.com\",\n \"gender\": \"F\",\n \"ssn\": \"<string>\"\n },\n \"facility\": {\n \"name\": \"Example General Hospital\",\n \"address_line1\": \"100 Example Ave\",\n \"city\": \"Springfield\",\n \"state\": \"PA\",\n \"zip_code\": \"00000\",\n \"address_line2\": null,\n \"phone\": \"+1-555-010-2000\",\n \"fax\": \"+1-555-010-1111\"\n },\n \"auth_form\": {\n \"upload_id\": \"11111111-1111-4111-8111-111111111111\",\n \"file_name\": \"jane_doe_hipaa.pdf\",\n \"signer_name\": \"Mary Doe\",\n \"signer_relationship\": \"Mother\"\n },\n \"requested_records\": [\n {\n \"type\": \"medical_records\",\n \"custom_label\": null,\n \"deliverable_format\": null,\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"requirements\": []\n }\n ],\n \"case_id\": \"111111111111111111111111\",\n \"facility_id\": \"facility_example\",\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"notes\": \"Please include any radiology read reports\",\n \"submitter_email\": \"jane.smith@example.com\",\n \"attachments\": [],\n \"requestor_id\": \"111111111111111111111111\",\n \"allow_duplicate\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://enterprise.tavrn.ai/v2/retrieval-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"patient\": {\n \"name\": \"Jane Doe\",\n \"date_of_birth\": \"1989-04-12\",\n \"address\": \"123 Main St, Austin, TX 78701\",\n \"phone\": \"+1-512-555-0101\",\n \"email\": \"jane@example.com\",\n \"gender\": \"F\",\n \"ssn\": \"<string>\"\n },\n \"facility\": {\n \"name\": \"Example General Hospital\",\n \"address_line1\": \"100 Example Ave\",\n \"city\": \"Springfield\",\n \"state\": \"PA\",\n \"zip_code\": \"00000\",\n \"address_line2\": null,\n \"phone\": \"+1-555-010-2000\",\n \"fax\": \"+1-555-010-1111\"\n },\n \"auth_form\": {\n \"upload_id\": \"11111111-1111-4111-8111-111111111111\",\n \"file_name\": \"jane_doe_hipaa.pdf\",\n \"signer_name\": \"Mary Doe\",\n \"signer_relationship\": \"Mother\"\n },\n \"requested_records\": [\n {\n \"type\": \"medical_records\",\n \"custom_label\": null,\n \"deliverable_format\": null,\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"requirements\": []\n }\n ],\n \"case_id\": \"111111111111111111111111\",\n \"facility_id\": \"facility_example\",\n \"service_start_date\": \"2024-03-15\",\n \"service_end_date\": \"2024-09-30\",\n \"notes\": \"Please include any radiology read reports\",\n \"submitter_email\": \"jane.smith@example.com\",\n \"attachments\": [],\n \"requestor_id\": \"111111111111111111111111\",\n \"allow_duplicate\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "rr_abc123",
"order_number": "T-ABC-12345",
"case_id": "case_abc123",
"status": "received",
"created_at": "2025-02-01T12:50:00Z",
"updated_at": "2025-02-01T12:50:00Z",
"requestor_id": "111111111111111111111111"
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "validation_error",
"message": "The patient.date_of_birth field is required"
}
}{
"error": {
"code": "duplicate_request_detected",
"message": "<string>"
},
"duplicates": [
{
"id": "<string>",
"order_number": "<string>",
"classification": "EXACT",
"overlapping_record_types": [
"<string>"
],
"cross_case": true
}
]
}Authorizations
API key authentication. Use format: Authorization: Bearer tavrn_sk_live_...
Body
application/json
- Option 1
- Option 2
- Option 3
- Option 4
Patient details. Supply as much as you know — many facilities verify identity against DOB, SSN last-4, or address before releasing records.
Show child attributes
Show child attributes
Facility name and address when creating a request manually. Provide this object or a top-level facility_id. Optional phone and fax contacts may be absent on read.
Show child attributes
Show child attributes
The signed HIPAA authorization PDF. Required.
Show child attributes
Show child attributes
One or more record lines to request. Each line carries its own type, dates, requirements, and (for billing) deliverable format.
Minimum array length:
1Show child attributes
Show child attributes
Existing case in your organization; mutually exclusive with case.
Pattern:
^[a-fA-F0-9]{24}$Example:
"111111111111111111111111"
Facility ID from GET /v2/facilities. Provide exactly one of facility_id or facility.
Minimum string length:
1Example:
"facility_example"
Default start of the service date range (YYYY-MM-DD). Inherited by any requested_records[] line that omits its own service_start_date.
Example:
"2024-03-15"
Default end of the service date range (YYYY-MM-DD). Inherited by any requested_records[] line that omits its own. Set to null for ongoing care.
Example:
"2024-09-30"
Free-text instructions for the team handling this request
Example:
"Please include any radiology read reports"
Email of a user in your organization to attribute the request to. That user receives retrieval notifications for the request. Must match an existing user in your organization or the request is rejected with a 400 validation_error. If omitted, the request is attributed to the creator of the API key.
Example:
"jane.smith@example.com"
Optional supporting documents for the request — e.g., cover letters, patient ID copies, prior-auth attachments. Each entry references an uploaded file by upload_id.
Show child attributes
Show child attributes
Existing profile in your organization. Mutually exclusive with requestor. Omit both to keep the organization default.
Pattern:
^[a-fA-F0-9]{24}$Example:
"111111111111111111111111"
Create a Requestor profile with this retrieval. Requires requestors:write and cannot be combined with requestor_id.
Show child attributes
Show child attributes
When duplicate detection is enabled, retry with true after reviewing a 409 duplicate_request_detected response to create despite the blocking matches. Omission or null does not override the check.
Create a case with this retrieval. Requires cases:write and cannot be combined with case_id.
Show child attributes
Show child attributes
Response
Retrieval request created
Example:
"rr_abc123"
Example:
"T-ABC-12345"
Example:
"case_abc123"
Available options:
received, processing, action_required, completed, cancelled Example:
"received"
Example:
"2025-02-01T12:50:00Z"
Example:
"2025-02-01T12:50:00Z"
Selected Requestor profile ID.
Pattern:
^[a-fA-F0-9]{24}$Example:
"111111111111111111111111"