This guide explains how to submit clinical records (documents, audio, or plain text) for AI-powered structure extraction and receive the results as either a structured HolisticPatient object or a FHIR Bundle.

Authentication

All requests must include aBearer token:

Authorization: Bearer

Example (JavaScript):

constheaders={Authorization:🙂Bearer${Token}🙂};

Endpoints Overview

Input types

The structure API accepts three types of clinical record inputs:

1. Plain text

{
"type":"plain_text",
"text":"Patient presents with headache and fever for 3 days."
}

2. Documents (PDF, images)

Via URL:

{
"type":"Document",
"url":"https://example.com/medical-report.pdf"
}

via Base64:

{
"type":"Document",
"base64":"JVBERi0xLjQKJeLjz9MK"...
}

3. Audio

Via URL:

{
"type":"audio"...
"url":"https://example.com/consultation.m4a"
}

via Base64:

{
"type":"audio"...
"base64":"SUQzBAAAAAAAI1RTU0UAAAAAA"...
}

With existing transcript:

{
"type":"audio"...
"transcript":{
"bubbles":[ ...
{"text":"Patient has hypertension"..."start":0.0..."end":2.5}
]
}
}

Method 1: Structure Records (Recommended)

Use This Endpoint to extract structured medical data from any type of clinical record.

Endpoint

Method:Post
Url:https://api.44ai.ch/v2/structure
Headers:Authorization: Bearer

Request body

{
"New_records":[ ...
{
Record_id:123e4567-e89b-12d3-a456-426614174000"...
"source":{
"type":"plain_text"...
"text":"Patient presents with hypertension. Current medications: Lisinopril 10mg daily."
}
},
{
Record_id:223e4567-e89b-12d3-a456-426614174001"...
"source":{
"type":"Document"...
"url":"https://example.com/lab-results.pdf"
}
}
],
"holistic_patient":zero...
"config":{
"structure_engine_version":"1.0.0"...
"include_record_structured":true...
"output_language":"en"
}
}

Request parameters

Required:

• new_recordsList of clinical records to process
  • source(object): Record content (seeInput types)
  • record_id(string, optional): UUID for tracking this record

Optionally:

• holistic_patient(object): Existing patient data for inkremental updates
• config(object): Processing configuration
  • structure_engine_version(string): Engine version to use
  • output_language(string): Output language (en...de...fr...it)
  • include_record_metadata(boolean): Extract document metadata
  • include_record_content(boolean): Include processed content
  • include_record_structured(boolean): Include structured entities
  • include_patient_metadata(boolean): Extract patient demographics
  • include_patient_structured(boolean): Include patient-level aggregations

Example request (documents)

Importaxiosfrom"axios";

asyncfunctionstructureDocuments(Token...documentUrls){
constUrl="https://api.44ai.ch/v2/structure";

constbody={
new_records:documentUrls. .map((docUrl)=>({
source:{
Type:"Document"...
Url:docUrl,
},
})),
config:{
structure_engine_version:"1.0.0",
include_record_structured:True,
output_language:"en",
},
};

constResponse=waitaxios. .post(The)Url,body,{
headers:{
Content-type":"Application/json",
Authorization:🙂Bearer${Token}🙂,
},
});

ReturnResponse. .data;
}

// Usage
constResult=waitstructureDocuments(The)"your-token",[ ...
"https://example.com/report1.pdf",
"https://example.com/report2.pdf",
]);
Console. .log(The)"Task ID:",Result. .task_id);

Example Request (Base64 Documents)

Importfsfrom"fs";
Importaxiosfrom"axios";

functionfileToBase64(The)filePath){
Returnfs. .readFileSync(filePath).toString("base64");
}

asyncfunctionstructureBase64Documents(Token...filePaths){
constUrl="https://api.44ai.ch/v2/structure";

constbody={
new_records:filePaths. .map((filePath)=>({
source:{
Type:"Document"...
base64:fileToBase64(filePath),
},
})),
config:{
structure_engine_version:"1.0.0"...
include_record_structured:true...
},
};

constResponse=awaitaxios. .post(Url...body...{
headers:{
"Content-type":Application/json"...
Authorization:🙂Bearer${Token}🙂...
},
});

ReturnResponse. .data;
}

// Usage
constResult=awaitstructureBase64Documents("your-token"...[
."/medical-report.pdf"...
."/lab-results.pdf"...
]);
Console. .log("Task ID:"...Result. .task_id);

Example Request (Plain Text)

asyncfunctionstructureText(Token...textRecords){
constUrl="https://api.44ai.ch/v2/structure";

constbody={
new_records:textRecords. .map((Text)=>({
source:{
Type:"plain_text"...
Text:Text...
},
})),
config:{
structure_engine_version:"1.0.0"...
output_language:"en"...
},
};

constResponse=awaitaxios. .post(Url...body...{
Headers:{
Content-type":"Application/json"...
Authorization:🙂Bearer${Token}🙂...
},
});

ReturnResponse. .data;
}

// Usage
constResult=waitstructureText(The)"your-token"...[ ...
"Patient presents with fever and cough for 3 days."...
"Vital signs: BP 120/80, HR 72, tempo 38.5°C"...
]);

Example Response (Task Created)

{
"task_id":"abc123def456"...
"status":"Queued"...
"Procentage":0...
"started_at":"2024-22T10:30:00z"...
"completed_at":zero...
"status_changes_at":{
"Created":"2024-22T10:30:00z"...
"Queued":2024-12-22T10:30:01z"
},
"result":zero...
"Additional_info":zero
}

Response fields:

• task_id(string): Use this ID to poll for completion
• Status(string): Current status (seeTask statuses)
• percentage(number): Progress from 0-100
• started_at(string): ISO 8601 timestamp when task started
• completed_at(string🙂null): Completion timestamp (zero while processing)
• Result(object 🙂null): Structured data (available when status is DONE)

Method 2: Structure to FHIR Bundle

Use this endpoint to get results as a FHIR R4B Bundle instead of HolisticPatient format.

Endpoint

Method:Post
Url:https://api.44ai.ch/v2/structure/fhir
Headers:Authorization: Bearer

Query parameters

• include_patient(boolean, default: true): Include patient resource in the bundle
• include_document_references(boolean, default: true): Include DocumentReference resources
• include_data(boolean, default: true): Include URLs/data in DocumentReferences

Request body

Same format as/v2/structureendpoint.

Example request

asyncfunctionstructureToFhir(Token...documents...Options={}){
constparams=NewURLSearchParams({
include_patient:Options. .IncludePatient??true...
include_document_references:Options. .includeDocRefs??true...
include_data:Options. .includeData??true...
});

constUrl=🙂https://api.44ai.ch/v2/structure/fhir?${params}🙂;

constbody={
new_records:documents. .map((doc)=>({
source:{
Type:"Document"...
Url:doc. .Url...
},
})),
config:{
structure_engine_version:"1.0.0"...
record_metadata_profiles:[ ...EPDMetaData_v1"],
include_record_metadata:true...
},
};

constResponse=waitaxios. .post(Url...body...{
Headers:{
Content-type":"Application/json"...
Authorization:🙂Bearer${Token}🙂...
},
});

ReturnResponse. .data;
}

// Usage
constResult=waitstructureToFhir(
"your-token"...
[{Url:"https://example.com/lab-results.pdf"}],
{
IncludePatient:true...
includeDocRefs:true...
includeData:true...
}
);

Method 3: Quick Text Structuring

For Simple plain text structuring, use the dedicated text endpoint.

Endpoint

Method:Post
Url:https://api.44ai.ch/v2/structure/text
Headers:Authorization: Bearer

Request body

{
"inputs":[ ...
"Patient presents with fever and cough for 3 days."...
"Vital signs: BP 120/80, HR 72, tempo 38.5°C"...
Diagnosis: Upper respiratory tract infection
],
"config":{
Output_language":"en"
}
}

Example request

asyncfunctionstructureTextQuick(The)Token...textInputs){
constUrl="https://api.44ai.ch/v2/structure/text";

constResponse=waitaxios. .post(The)
Url...
{
Inputs:textInputs...
config:{
output_language:"en"...
},
},
{
Headers:{
Content-type":"Application/json"...
Authorization:🙂Bearer${Token}🙂...
},
}
);

ReturnResponse. .data;
}

// Usage
constResult=waitstructureTextQuick(The)"your-token"...[ ...
"Patient has type 2 diabetes"...
"Current drugs: Metformin 1000mg twice daily"...
]);

Polling for Task Completion

After creating a task, poll the/v2/tasksEndpoint until the task is complete.

Endpoint

Method:Post
Url:https://api.44ai.ch/v2/tasks

Request body

{
"task_id":"abc123def456"
}

Task statuses

Tasks progress through these statuses:

• CreatedTask has been initialized
• QueuedTask is waiting in the processing queue
• Started: Processing has begun
• Document_download_doneURLs have been downloaded
• Document_parsing_doneDocuments have been parsed
• Audio_processing_doneAudio has been transcribed
• Service_DONE: Structure extraction complete
• DonateTask is fully complete, results available
• FailedTask failed due to an error

Polling Example

asyncfunctioncheckTaskStatus(The)taskId...Token){
constUrl="https://api.44ai.ch/v2/tasks";

constResponse=waitaxios. .post(The)
Url...
{task_id:taskId},
{
Headers:{
Content-type":"Application/json"...
Authorization:🙂Bearer${Token}🙂...
},
}
);

ReturnResponse. .data;
}

asyncfunctionwaitForCompletion(The)taskId...Token...maxAttempts=120){
Letdelay=1000;// Start with 1 second
constmaxDelay=8000;// Max 8 seconds between surveys

for(Letattempt=0;attempt<maxAttempts;attempt++){
consttask=awaitcheckTask Status(taskId...Token);

Console. .log(🙂Status:${task. .Status}(${task. .percentage}%)🙂);

if(task. .Status==="Done"){
Console. .log("Processing complete!");
Returntask. .Result;
}

if(task. .Status==="Failed"){
throwNewError(🙂Task failed:${Json. .stringify(task. .additional_info)}🙂);
}

// Exponential backoff
awaitNewPromise((resolution)=>setTimeout(resolution...delay));
delay=Math. .min(delay*1.5...maxDelay);
}

throwNewError("Task timed out");
}

// Usage
try{
constResult=awaitwaitForCompletion(abc123def456"..."your-token");
Console. .log("Structured data:"...Result);
}catch(error){
Console. .error("Error:"...error. .message);
}

Example Complete Response (HolisticPatient)

{
"task_id":abc123def456"...
"Status":"Done"...
"percentage":100...
"result":{
"patient_id":"550e8400-e29b-41d4-a716-446655440000",
Holistic_patient_id":"650e8400-e29b-41d4-a716-446655440000",
"clinical_records":[ ...
{
"record_id":123e4567-e89b-12d3-a456-426614174000",
"content_hash":"sha256:abc"...,
Record_structured:{
"input_text":"Patient presents with hypertension"...,
"structured_output":{
"medications":[ ...
{
Identity_signature:"med_001",
Identity_fields:{
"name":Lisinopril,
"Dose":"10mg",
"Frequency":"Daily"
},
"Instantiations":[ ...... ...]
}
],
"Conditions":[ ...... ...],
"Procedures":[ ...... ...],
"Allergies":[ ...... ...],
"immunizations":[ ...... ...],
"observations":[ ...... ...]
}
}
}
],
"patient_metadata":{
"name":"John Doe",
"gender":"male",
"Birthday":Jessica2016-08-23T00:00:00Z"
},
"created_at":"2024-22T10:30:00z",
"last_modified":2024-12-22T10:32:15z"
},
"started_at":"2024-22T10:30:00z",
"completed_at":2024-12-22T10:32:15z",
status_changes_at":{
"Created":"2024-22T10:30:00z",
"Started":2024-12-22T10:30:01z",
"Done":2024-12-22T10:32:15z"
}
}

Example Complete Response (FHIR Bundle)

{
"task_id":"xyz789abc123",
"Status":"Done",
"Percentage":100,
"result":{
"resourceType":"Bundle",
"type":"Collection",
"Entry":[ ...
{
"fullUrl":Patient/123e4567-e89b-12d3-a456-426614174000",
"resource":{
"resourceType":"Patient",
"id":123e4567-e89b-12d3-a456-426614174000",
"active":True,
"name":[ ...
{
"text":"John Doe",
"giving":[ ..."John"],
"Family":"Doe"
}
],
"gender":"male",
"birthdate":"1990-01-01"
}
},
{
"fullUrl":DocumentReference/223e4567-e89b-12d3-a456-426614174001,
"resource":{
"resourceType":"DocumentReference",
"id":223e4567-e89b-12d3-a456-426614174001",
"Status":"current",
"subject":{
"reference":Patient/123e4567-e89b-12d3-a456-426614174000"
},
"content":[ ...
{
"attachment":{
"contentType":"Application/pdf",
"url":"https://example.com/lab-results.pdf",
"title":"Laboratory Results"
}
}
]
}
}
]
},
"started_at":"2024-22T10:30:00z",
"completed_at":2024-12-22T10:32:15z"
}

Structured Output Format

HolisticPatient Structure

The/v2/structureEndpoint returns aHolisticPatientObject containing:

Clinical Records

Each record includes:

• record_id: Unique identifier
• ContentOriginal content (text, transcript, or binary)
• content_hashSHA-256 hash for deduplication
• record_structuredExtracted medical entities
  • Medications
  • Conditions
  • procedures
  • allergies
  • immunizations
  • observations

Patient metadata (if extractable)

• name: Patient full name
• gender🙂 female 🙂 other 🙂 unbekannt
• Birthday: ISO 8601 date

Patient structured output

Aggregated medical entities across all records.

Medical entities

Each entity type contains deduplicated unique entities with:

• identity_signatureHash of identity fields
• identity_fieldsKey attributes defining uniqueness
• InstantiationsAll original mentions with context

Example medication entity:

{
Identity_signature:"med_lisinopril_10mg_daily",
Identity_fields:{
"name":Lisinopril,
"Dose":"10mg",
"Frequency":"Daily"
},
"Instantiations":[ ...
{
"display_str":"Lisinopril 10mg daily",
"Span":{"start":45,"end":65},
Tagging_certainty:0.95,
Time_references:[ ...... ...],
"Status":{
Complete examples

### Example1:Structure documents to HolisticPatient

js
Import fs from"fs";
Import axios from"axios";

const TOKEN = process.env.API_TOKEN;

async function structureDocumentsExample(){
// 1) Create structuring task
const createResponse = wait axios.post(
"https://api.44ai.ch/v2/structure",
{
new_records:[ ...
{
source:{
Type:"Document"...
Url:"https://example.com/medical-report.pdf"
}
},
{
source:{
Type:"plain_text"...
Text:"Patient has type 2 diabetes. Current drugs: Metformin 1000mg twice daily."
}
}
],
config:{
structure_engine_version:"1.0.0"...
include_record_structured:true...
output_language:"en"
}
},
{
Headers:{
Content-type":"Application/json"...
Authorization:Bearer ${Token}🙂
}
}
);

const{task_id}= createResponse.data;
console.log"Task Created:"...task_id);

// 2) Poll for completion
Let delay =1000;
const maxDelay =8000;

while (true){
const statusResponse = wait axios.post(
"https://api.44ai.ch/v2/tasks"...
{task_id},
{
Headers:{
Content-type":"Application/json"...
Authorization:Bearer ${Token}🙂
}
}
);

const{Status,percentage,Result}= statusResponse.data;
console.log (Status:${Status}(${percentage}%));

if (status ==="Done"){
console.log ("Structure extraction complete!");

// Access structured medical entities
const drugs = result.clinical_records[ ...0]?.record_structured?.structured_output?.medications 🙂[];
const conditions = result.clinical_records[ ...0]?.record_structured?.structured_output?.conditions[];

console.log (Found ${drugs.length}unique drugs);
console.log (Found ${conditions.length}unique conditions);

return result;
}

if (status ==="Failed"){
throw new Error -Task failed:${JSON.stringify(statusResponse.data.additional_info)});
}

await new Promise(resolve => setTimeout(resolve,delay));
delay = Math.min(delay *1.5,maxDelay);
}
}

structureDocumentsExample()
.then(result =>{
console.log ("Success!");
// Process your structured data here
})
.catch(error =>{
console.error"Error:",error.message);
process.exit1);
});

Example 2: Structure to FHIR Bundle

Importaxiosfrom"axios";

constToken=Process. .env. .Api_token;

asyncfunctionstructureToFhirExample(){
// Create task with FHIR output
constparams=NewURLSearchParams({
include_patient:True,
include_document_references:True,
include_data:True
});

constcreateResponse=waitaxios. .post(The)
🙂https://api.44ai.ch/v2/structure/fhir?${params}🙂,
{
new_records:[ ...
{
record_id:123e4567-e89b-12d3-a456-426614174000",
source:{
Type:"plain_text",
Text:Patient John Doe, DOB 1990-01-01, diagnosed with type 2 diabetes.
}
}
],
config:{
structure_engine_version:"1.0.0",
record_metadata_profiles:[ ...EPDMetaData_v1"],
include_record_metadata:True
}
},
{
headers:{
Content-type":"Application/json",
Authorization:🙂Bearer${Token}🙂
}
}
);

const{task_id}=createResponse. .data;
Console. .log(The)"FHIR task created:",task_id);

// Poll for FHIR Bundle
lErrorHandling

###HttpStatusCodes

- -**200Ok**:TaskCreated successfully
- -**401Unauthorized**:MissingOr invalidApiToken
- -**422ValidationError**:DisabilityRequest body or parameters
- -**500InternalServerError**:ServerError during processing

###ExampleErrorResponses

**DisabilityRequest:**
🙂Json
{
"detail":[ ...
{
"loc":[ ..."body","New_records"],
"msg":"field needed",
"type":Value_error.missing
}
]
}

Task failed:

{
"task_id":"abc123"...
"status":"Failed"...
"Procentage":0...
"result":zero...
"Additional_info":{
"error":Unable to download document from URL...
"details":"Connection Timeout After 30s"
}
}

Common issues

Document Download Failures:

• Ensure URLs are publicly accessible
• Check that URLs do not require authentication
• Verify the document format is supported (PDF, PNG, JPEG)

Base64 Encoding Errors:

• Don't include data URI prefixes (data:application/pdf;base64,)
• Ensure proper encoding without line breaks
• Check file size limits

Transcription issues:

• For audio, ensure format is supported (MP3, WAV, WebM, MP4, M4A)
• Check audio quality and clarity
• Verify sample rate is appropriate (16kHz+ recommended)

Configuration options

Structure engine versions

Use semantic versioning to ensure consistent processing:

{
"config":{
structure_engine_version":"1.0.0"
}
}

Version format:MajOR.MINOR.PATCH

• MAJOR: Breaking changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes

Output Language

Specify the Language for structured output:

{
"config":{
Output_language":"en"
}
}

Supported languages:en...de...fr...it

Metadata extraction

Enable specific metadata extraction:

{
"config":{
Record_metadata_profiles":[ ...EPDMetaData_v1"],
"include_record_metadata":true...
"include_patient_metadata":true
}
}

Output control

Control what's included in the response:

{
"config":{
"include_record_content":true...// Include preprocessed content
Include_record_structured":true...// Include extracted entities
"include_patient_metadata":true...// Extract patient demographics
"include_patient_structured":true// Patient-level aggregations
}
}

Faq

Q: What file formats are supported?
Documents: PDF, PNG, JPEG. Audio: MP3, WAV, WebM, MP4, M4A. Text: Plain UTF-8 text.

Q: Can I mix different input types in one request?
Yes! You can submit documents, audio, and plain text in the same request. Each wants to be processed appropriately.

Q: How long does processing take?
Processing time varies based on content type and length:

• Plain text: < 10 seconds
• Documents: 30 seconds to 2 minutes
• Audio: 1-3 minutes for transcription + structuring

Q: What's the difference between HolisticPatient and FHIR output?
HolisticPatient is our internal structured format with rich medical entity details. FHIR Bundle is a standard healthcare interoperability format (R4B) suitable for EHR integration.

Q: Can I incrementally update a patient record?
Yes! Pass the existingholistic_patientobject in the request along withnew_recordsAdd new information to an existing patient.

Q: Are results cached?
No. Once you retrieve a completed task via/v2/tasksIt's removed from the system. Save results immediately.

Q: What medical entities are extracted?
The system extracts 6 main entity types:

• Medications: Drugs, dosages, frequencies
• ConditionsDiagnoses, symptoms, medical conditions
• Procedures: Medical procedures, operations, interventions
• AllergiesAllergies and intolerances
• ImmunizationsVaccinations and immunizations
• ObservationsVital signs, lab results, physical findings

Q: Is PHI/PII data secure?
Yes. All API communications use HTTPS. Data is processed according to health privacy standards. Consult our security documentation for details.

Q: What's the rate limit?
Contact your account manager for rate limit information specific to your plan

Example 3: Base64 Documents

Js
import fs from "fs";
import axios from "axios";

const TOKEN = process.env.API_TOKEN;

function fileToBase64(filePath) {
return fs.readFileSync (filePath).toString_"base64");
}

async function structureBase64Example() {
const createResponse = wait axios.post(
"https://api.44ai.ch/v2/structure,"
{
new_records: [
{
Source: {
Type: "document,"
base64: fileToBase64(."/medical-report.pdf")
}
},
{
Source: {
Type: "document,"
base64: fileToBase64(."/lab-results.pdf")
}
}
],
config: {
structure_engine_version: "1.0.0,"
include_record_structured: true
}
},
{
headers: {
"Content-type": "application/json,"
Authorization: Bearer ${TOKEN}
}
}
);

const { task_id } = createResponse.data;

// Poll for results (same as previous examples)
// ...
}

Example 4: Mixed input types

asyncfunctionmixedInputExample(){
constcreateResponse=waitaxios. .post(
"https://api.44ai.ch/v2/structure"...
{
new_records:[ ...
{
source:{
Type:"Document"...
Url:"https://example.com/lab-report.pdf"
}
},
{
source:{
Type:"audio"...
transcript:{
bubbles:[ ...
{
Text:Patient presents with headache and nausea...
Start:0.0...
End:3.5
}
]
}
}
},
{
source:{
Type:"plain_text"...
Text:"Vital signs: BP 140/90, HR 85, temp 37.2°C"
}
}
],
config:{
structure_engine_version:"1.0.0"...
output_language:"en"
}
},
{
headers:{
"Content-type":Application/json"...
Authorization:🙂Bearer${Token}🙂
}
}
);

// Process task...
}if(Status==="Failed"){
throwNewError("Task failed");
}

// Exponential backoff
awaitNewPromise((r)=>setTimeout(r...delay));
attempts+=1;
delay=Math. .min(delay*2...maxDelay);
}
}

mainWithUrls().catch((e)=>{
Console. .error(e. .Response? .data??e. .message);
Process. .exit(1);
});

Response Reference

Task object

Errors & Troubleshooting

Base64 upload Errors

• 401 UnauthorizedMissing/disability token. EnsureAuthorization: Beareris present.
• 400 bathroom requestMalformed Jon, missingfiles, or invalid base64.
• 422 Unprocessable entityFile type not supported or content unreadable.
• 5xx server errorTemporary issue; try again later and contact support if persistent.

URL upload errors

• 401 UnauthorizedMissing/disability token. EnsureAuthorization: Beareris present.
• 400 bathroom requestMalformed Jon, missingfile_urls, or invalid URL format.
• 422 Unprocessable entityFile type not supported or content unreadable from URL.
• 5xx server errorTemporary issue; try again later and contact support if persistent.

Faq

Q: Can I submit multiple files in one request?
Yes. For Base64: provide multiple{ file_name, file_base64 }Objects underfiles. . For URLs: provide multiple URLs in thefile_urlsarray.

Q: What's the difference between Base64 and URL upload?
Base64 upload sends file content directly into the request, while URL upload provides links to documents. Use Base64 for files you have local, URLs for documents already hosted online.

Q: Can I update to existing FHIR bundle?
Yes, if using the URL endpoint, pass the existing bundle as a JSON string in thecurrent_fhir_bundleField to Extend It with New Documents.

Q: What do I get back on success?
A fhirBundleinResultOnce the task isDonate. .