API Documentation

ePrescription Extraction Service - Client Interface v3.4

Quick Start

1Get sandbox credentials in the tab

2Exchange for a Bearer token via POST /v1/auth/token

3Add Authorization: Bearer <token> to all requests

4Upload your catalog, then submit prescriptions

Base URL
https://your-deployment.up.railway.app
TLS 1.2+ required | All endpoints prefixed /v1/
$ curl -X POST https://.../v1/auth/token \
-H "Content-Type: application/json" \
-d '{"grant_type":"client_credentials","client_id":"YOUR_ID","client_secret":"YOUR_SECRET"}'
< 2 min
Prescription processing
99.9%
Availability target
6-Axis
LOINC resolution
GDPR
Full audit trail

Authentication

All API requests (except /v1/health) require a Bearer token. Use the OAuth2 client_credentials flow to exchange your client_id and client_secret for a JWT access token. Tokens expire after 1 hour and must be refreshed by requesting a new one.

Catalog Management

The catalog is the laboratory's master list of test codes. Upload your catalog so the system can map extracted prescription items to your specific client codes. The system continues operating on the previous catalog while a new version is being validated.

Typical Workflow
  1. 1Upload a new catalog version via POST /v1/catalog/upload
  2. 2System validates the catalog asynchronously (JSON envelope is checked immediately; content validation happens in background)
  3. 3Poll status via GET /v1/catalog/status/{version} or wait for a webhook notification
  4. 4If PUBLISHED: new catalog is live. If REJECTED: fix the data issues described in the webhook and re-submit

Prescription Processing

Submit prescription images for AI-powered extraction, LOINC mapping, and lab order coding. Each API call represents one prescription. If a prescription spans multiple pages (front/back), include all pages in the same request. Processing must not exceed 2 minutes.

Typical Workflow
  1. 1Submit prescription image(s) via POST /v1/prescriptions/process -- receive a job_id
  2. 2Wait for webhook notification (recommended) or poll GET /v1/prescriptions/{job_id}/status
  3. 3Retrieve full result via GET /v1/prescriptions/{job_id} -- includes patient, orders, scores
  4. 4(Optional but recommended) Submit lab actuals via POST /v1/prescriptions/{job_id}/actuals for continuous improvement

Webhooks

Register a webhook URL to receive real-time push notifications instead of polling. The system sends POST requests to your URL when prescription processing completes or catalog status changes. All payloads are signed with HMAC-SHA256 for authenticity verification.

Typical Workflow
  1. 1Register your endpoint via POST /v1/settings/webhook with a URL and a signing secret
  2. 2The system sends POST requests to your URL when events occur
  3. 3Verify each webhook by computing HMAC-SHA256 of the body with your secret and comparing to X-Medicus-Signature
  4. 4Events: prescription.completed (PROCESSED or UNPROCESSABLE) and catalog.status_changed (PUBLISHED, REJECTED, SUPERSEDED)

System

Health check endpoint. No authentication required. Use this to verify connectivity and confirm the service is operational before starting integration work.

Audit & Compliance

GDPRFull traceability of all access to prescription data. All API requests logged with timestamp, client identity, endpoint, and response status.
CatalogAll submissions (accepted and rejected) are versioned and persisted for audit.
PrescriptionsEvery run record is persisted with the complete extraction, mapping, and coding trace including all intermediate scores.
VersioningAll endpoints prefixed /v1/. Breaking changes will result in /v2/. Non-breaking additions (new fields, new optional params) are added without version increment.