Create retrieval request
curl --request POST \
--url https://enterprise.tavrn.ai/v2/cases/{case_id}/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": []
}
],
"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/cases/{case_id}/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": []
}
],
"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: []
}
],
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/cases/{case_id}/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/cases/{case_id}/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' => [
]
]
],
'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/cases/{case_id}/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 \"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/cases/{case_id}/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 \"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/cases/{case_id}/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 \"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 request
Create a retrieval under the case in the URL using patient and requested_records, plus exactly one of facility_id from GET /v2/facilities or a manual facility object. An inline case is not accepted. Optionally select requestor_id or create an inline requestor; omitting both uses the default profile. Use an API key with retrievals:write for creation, plus requestors:write for an inline Requestor. Upload the authorization with POST /v2/retrieval-requests/sign-upload or the case sign-upload endpoint. Use POST /v2/retrieval-requests to create an inline case. Each successful POST with an inline Requestor creates a new profile; retain its ID for reuse.
POST
/
v2
/
cases
/
{case_id}
/
retrieval-requests
Create retrieval request
curl --request POST \
--url https://enterprise.tavrn.ai/v2/cases/{case_id}/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": []
}
],
"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/cases/{case_id}/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": []
}
],
"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: []
}
],
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/cases/{case_id}/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/cases/{case_id}/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' => [
]
]
],
'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/cases/{case_id}/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 \"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/cases/{case_id}/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 \"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/cases/{case_id}/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 \"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_...
Path Parameters
Case ID
Body
application/json
- Option 1
- Option 2
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
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.
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"