Back to Documentation

Patient Upload API

Upload patient records directly into your Arkangel workspace via API

by Arkangel AI Team•2 min read

The Patient Upload API allows institutions to push patient records directly into their Arkangel workspace programmatically, without manual intervention. Once uploaded, files are processed automatically and results appear in your team's Pandora workspace.

Prerequisites

Contact Arkangel to receive:

  • API key — used to authenticate every request
  • Team ID — identifies your organization within Arkangel

Supported Formats

Format Description Notes
PDF Clinical histories, discharge summaries, lab reports 1 file = 1 patient
TXT Plain text clinical notes 1 file = 1 patient
CSV Structured patient or event data See CSV format below

Maximum file size: 3MB per file.

CSV Format

CSV files must have patient_id as the first column header. The second column header determines the file type:

Patient file (1 row = 1 patient)

The second column can be anything or absent.

patient_id,name,birth_date,diagnosis
p-001,Jane Doe,1980-03-12,EPOC
p-002,John Smith,1975-07-22,Asthma

Event file (many rows = 1 patient)

The second column must be event_id. All rows sharing the same patient_id are grouped into a single patient record.

patient_id,event_id,event_date,event_type,value,unit
p-001,e-001,2026-01-10,SpO2,94,%
p-001,e-002,2026-01-10,heart_rate,88,bpm
p-002,e-001,2026-01-11,SpO2,97,%

Uploading a File

Endpoint

POST /api/pandora/upload-v2/upload

Headers

Authorization: Bearer your_api_key

Form fields

Field Required Description
file Yes The file to upload (PDF, TXT, or CSV)
teamId Yes Your team ID
groupId Yes ID of the Pandora group to add patients to
anonymize No Set to true to anonymize records after extraction (default: false)

Request

curl -X POST https://api.arkangel.ai/api/pandora/upload-v2/upload \
  -H "Authorization: Bearer your_api_key" \
  -F "file=@patients.csv" \
  -F "teamId=your_team_id" \
  -F "groupId=your_group_id" \
  -F "anonymize=false"

JavaScript Example

const formData = new FormData();
formData.append('file', file);
formData.append('teamId', 'your_team_id');
formData.append('groupId', 'your_group_id');
formData.append('anonymize', 'false');

const response = await fetch('https://api.arkangel.ai/api/pandora/upload-v2/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key'
  },
  body: formData
});

const result = await response.json();

Response

{
  "success": true,
  "patientCount": 3
}

patientCount reflects the number of patients successfully ingested. For PDF and TXT this is always 1. For CSV it matches the number of rows (patient file) or unique patient_id values (event file).

If any patients could not be ingested due to a storage error, expectedCount is also returned so you can detect the discrepancy and re-submit the missing rows:

{
  "success": true,
  "patientCount": 2,
  "expectedCount": 3
}

Error Handling

Code Error Description
400 invalid_file_type File format not supported
400 file_too_large File exceeds 3MB limit
400 invalid_csv_format First column is not patient_id
400 missing_patient_id One or more rows have an empty patient_id
401 unauthorized Missing or invalid API key
403 forbidden API key does not have access to this team
413 payload_too_large Request body exceeds server limit
500 internal_error Unexpected server error — contact support

Result

No additional calls are needed. Once uploaded, patient data is processed and available in your team's Pandora workspace automatically.

Next Steps