Quickstart
Upload a lab report, check status, and retrieve structured biomarker data in three steps.
Prerequisites
A Terra developer account with a
dev-idandx-api-key(get these from the Terra Dashboard)A webhook destination configured in the dashboard (optional but recommended)
A lab report file to upload (PDF, PNG, JPEG, GIF, WebP, or HEIC)
Upload a report
curl -X POST "https://access.tryterra.co/api/v2/reports" \
-H "dev-id: YOUR_DEV_ID" \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@/path/to/blood-test.pdf"You can optionally tag the upload with your own identifier:
curl -X POST "https://access.tryterra.co/api/v2/reports?reference_id=patient_456" \
-H "dev-id: YOUR_DEV_ID" \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@/path/to/blood-test.pdf"If the report was photographed page by page, send every page in the same upload, in page order. One upload is one report.
curl -X POST "https://access.tryterra.co/api/v2/reports?reference_id=patient_456" \
-H "dev-id: YOUR_DEV_ID" \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@/path/to/page-1.jpg" \
-F "file=@/path/to/page-2.jpg"Response (202 Accepted):
Wait for processing
The report moves through several statuses before results are ready:
Option A: Webhook (recommended): Terra delivers a lab_report.completed event, with the report under data, to your configured webhook endpoint when processing finishes. If the report can't be processed, you get a lab_report.failed event with the reason instead. No polling needed. See Failure webhook.
Option B: Poll the session: Check status by retrieving the session:
Processing typically takes 3 to 5 minutes, depending on report complexity and load.
Retrieve results
Once the session status is sent (or standardized or later), the results are available:
Response (200 OK):
What's next?
Core concepts: Understand the full session lifecycle and data model
Webhook payload: Set up automatic delivery of results
Biomarker reference: Browse the standardized biomarker catalog
Last updated
Was this helpful?