Developers

API Reference

Integrate Vita directly into your lab information system or clinic software. Send medical results to patients programmatically — Vita handles the encryption, delivery, and access control.

Overview

The Vita API is a REST API. All endpoints are available at:

https://vitawallet.eu/api/v1

All requests and responses use JSON, except for POST /deliveries which uses multipart/form-data to accept file uploads.

POST

/api/v1/deliveries

Send a result to a patient

GET

/api/v1/deliveries

List your deliveries

GET

/api/v1/deliveries/{id}

Get a single delivery and its status

DELETE

/api/v1/deliveries/{id}

Revoke a delivery link

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer vita_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API key is included in your welcome email when you register. Keep it secret — it grants full access to send documents on behalf of your organisation.

Don't have an API key yet? Email hello@vitawallet.eu to get access.

Send a result

POST/api/v1/deliveries

Upload a document and send the patient a secure, time-limited link by email. Vita encrypts the file, stores it privately, and emails the patient a link that expires after expires_in_days days.

The request must be multipart/form-data.

Request fields

Field	Type	Description
`result_file`*	file	PDF, JPEG, PNG or WebP. Max 20 MB.
`patient_email`*	string	Patient's email address. Deleted from our servers after the email is sent.
`patient_name`	string	Patient's name for the email greeting. Deleted after send.
`test_type`	string	e.g. Blood Test, MRI, ECG, Prescription
`test_date`	string	ISO 8601 date: 2026-04-05
`doctor_name`	string	Requesting doctor's name
`note`	string	Optional message shown to the patient
`expires_in_days`	integer	Link validity in days. Default: 30. Max: 90.

Response 201 Created

{
  "delivery_id": "d1e2f3a4-...",
  "token": "a1b2c3d4-...",
  "secure_url": "https://vitawallet.eu/r/a1b2c3d4-...",
  "expires_at": "2026-05-05T00:00:00.000Z",
  "email_status": "sent"
}

Example — cURL

curl -X POST https://vitawallet.eu/api/v1/deliveries \
  -H "Authorization: Bearer vita_live_xxxx" \
  -F "result_file=@/path/to/result.pdf" \
  -F "patient_email=patient@example.com" \
  -F "patient_name=Maria Papadopoulou" \
  -F "test_type=Blood Test" \
  -F "test_date=2026-04-05" \
  -F "expires_in_days=30"

List deliveries

GET/api/v1/deliveries

Returns a paginated list of all deliveries for your organisation, newest first.

Query parameters

Param	Type	Description
`limit`	integer	Records per page. Default: 20. Max: 100.
`offset`	integer	Pagination offset. Default: 0.
`status`	string	Filter by status: PENDING, SENT, VIEWED, EXPIRED, REVOKED

Response

{
  "deliveries": [
    {
      "id": "d1e2f3a4-...",
      "testType": "Blood Test",
      "testDate": "2026-04-05T00:00:00.000Z",
      "status": "VIEWED",
      "smsSentAt": "2026-04-05T09:12:00.000Z",
      "firstViewedAt": "2026-04-05T14:32:00.000Z",
      "viewCount": 2,
      "expiresAt": "2026-05-05T00:00:00.000Z",
      "createdAt": "2026-04-05T09:10:00.000Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get a delivery

GET/api/v1/deliveries/{id}

Returns full details and current status for a single delivery.

{
  "id": "d1e2f3a4-...",
  "token": "a1b2c3d4-...",
  "secure_url": "https://vitawallet.eu/r/a1b2c3d4-...",
  "testType": "Blood Test",
  "testDate": "2026-04-05T00:00:00.000Z",
  "status": "VIEWED",
  "viewCount": 2,
  "firstViewedAt": "2026-04-05T14:32:00.000Z",
  "expiresAt": "2026-05-05T00:00:00.000Z",
  "revokedAt": null,
  "patient_saved_to_wallet": true,
  "createdAt": "2026-04-05T09:10:00.000Z"
}

The patient_saved_to_wallet field tells you whether the patient has saved this document to their Vita Wallet.

Revoke a delivery

DELETE/api/v1/deliveries/{id}

Immediately invalidates the secure link and deletes the document from Vita's storage. This cannot be undone.

{
  "revoked": true,
  "revoked_at": "2026-04-05T15:00:00.000Z"
}

Errors

All errors return JSON with an error field.

Status	Meaning
`400`	Bad request — missing or invalid field
`401`	Missing or invalid API key
`402`	Monthly quota exceeded
`404`	Delivery not found (or belongs to another account)
`409`	Delivery already revoked
`413`	File too large (max 20 MB)
`429`	Too many requests — slow down
`500`	Internal server error — contact hello@vitawallet.eu

Code examples

Python

import requests

API_KEY = "vita_live_xxxx"
BASE_URL = "https://vitawallet.eu/api/v1"

with open("result.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/deliveries",
        headers={"Authorization": f"Bearer {API_KEY}"},
        data={
            "patient_email": "patient@example.com",
            "patient_name": "Maria Papadopoulou",
            "test_type": "Blood Test",
            "test_date": "2026-04-05",
            "expires_in_days": "30",
        },
        files={"result_file": ("result.pdf", f, "application/pdf")},
    )

data = response.json()
print(data["secure_url"])  # https://vitawallet.eu/r/...

Node.js

import FormData from 'form-data'
import fetch from 'node-fetch'
import fs from 'fs'

const form = new FormData()
form.append('result_file', fs.createReadStream('result.pdf'), 'result.pdf')
form.append('patient_email', 'patient@example.com')
form.append('patient_name', 'Maria Papadopoulou')
form.append('test_type', 'Blood Test')
form.append('test_date', '2026-04-05')
form.append('expires_in_days', '30')

const res = await fetch('https://vitawallet.eu/api/v1/deliveries', {
  method: 'POST',
  headers: { Authorization: 'Bearer vita_live_xxxx', ...form.getHeaders() },
  body: form,
})

const data = await res.json()
console.log(data.secure_url)

Check if patient viewed

# Poll delivery status after sending
curl https://vitawallet.eu/api/v1/deliveries/d1e2f3a4 \
  -H "Authorization: Bearer vita_live_xxxx"

# Returns "status": "VIEWED" and "firstViewedAt" once opened

Need help integrating?

Email us at hello@vitawallet.eu — we can walk you through the integration or build a custom connector for your LIS.