Migrating from the legacy API

Move from the legacy report upload endpoint to /v2/reports. Endpoint, auth, payload and webhook changes, with a field-by-field mapping.

If you upload reports to api.tryterra.co/v2/lab-reports (or /v2/reports/upload), you are on the legacy stack. This guide moves you to /v2/reports.

Nothing breaks while you migrate. Both stacks run in parallel, and you can switch one environment at a time.

Not sure which you're on? If your upload URL starts with https://api.tryterra.co you are on the legacy stack. If it starts with https://access.tryterra.co/api/v2 you are already migrated.

Why move

• DEXA and DXA scans. The new endpoint takes body-composition and bone-density scans as well as blood panels, and tells you which it received. The legacy endpoint is lab-only.

• Results you can act on without parsing prose. LOINC codes, panel grouping, a normalised flag alongside the report's own wording, and reference ranges that carry both the lab's exact label and a coded type.

• Delivery you can see. A per-destination delivery record, a stable event_id to deduplicate on, and an explicit failure event.

• Filtering and retrieval. List by reference, report type or date range, and fetch a session's input files.

Before you start

You need the Lab Reports capability on your account. If your uploads return 403 lab reports is not enabled for this account, enable it in the dashboard or talk to your account contact. It is a subscription flag, not an API change.

Check that you have a destination configured for the environment you are migrating. Reports are delivered to the destinations set up on your dev-id, and a report with none configured still finishes as sent, with nothing sent anywhere. If your first migrated upload completes but no webhook arrives, this is almost always why.

Your billing does not change. Both stacks meter the same unit, one per extracted result row, onto the same meter. A mid-migration month bills exactly as before.

1. Change the endpoint and auth

Authentication moves from a single key to a key plus your dev-id.

Legacy

curl -X POST "https://api.tryterra.co/v2/lab-reports" \
  -H "x-api-key: $TERRA_API_KEY" \
  -F "[email protected]"

New

curl -X POST "https://access.tryterra.co/api/v2/reports?reference_id=patient_456" \
  -H "x-api-key: $TERRA_API_KEY" \
  -H "dev-id: $TERRA_DEV_ID" \
  -F "[email protected]"

Legacy	New
POST /v2/lab-reports · POST /v2/reports/upload	POST /v2/reports
DELETE /v2/lab-reports/{upload_id}	DELETE /v2/reports/{session_id}
None	GET /v2/reports, with filters
None	GET /v2/reports/{session_id}
None	GET /v2/reports/{session_id}/files
None	GET /v2/reports/{session_id}/deliveries

The new endpoint accepts one file per request, up to 20 MB: PDF, PNG, JPEG, GIF or WebP.

2. Learn the two identifiers

The legacy API had one id. The new API has two, and the distinction matters.

• upload_id: the handle for what you uploaded. You still get one back from the upload call.

• session_id: one extracted report. A single upload can produce more than one session (a multi-report PDF), so session_id is what identifies a result set, and what every other endpoint takes.

If your code stores the value returned by upload and later looks up results with it, that is the one change you cannot skip. Store upload_id, then learn the session_id(s) from the webhook, or from GET /v2/reports?upload_id=....

3. Update your webhook handler

The legacy webhook delivered one body per report:

{
  "upload_id": "upl_4a2b8c1d",
  "reference_id": "patient_456",
  "data": [{ "date": "2026-03-01", "time": "09:14", "results": [ … ] }]
}

The new webhook is an event envelope. Branch on type first:

{
  "type": "lab_report.completed",
  "event_id": "evt_01J9…",
  "occurred_at": "2026-03-01T09:20:11Z",
  "upload_id": "upl_4a2b8c1d",
  "data": {
    "session_id": "297405620317847552",
    "reference_id": "patient_456",
    "report_type": "lab",
    "report_date": "2026-03-01",
    "results_count": 42,
    "results": [ … ],
    "panels": [ … ]
  }
}

Three things to handle:

1. type is lab_report.completed or lab_report.failed. The legacy stack had no failure event: a failed report simply never arrived. Handle lab_report.failed so a bad upload surfaces in your product instead of hanging.

2. event_id is stable across redeliveries. Use it as your idempotency key.

3. data is an object, not an array. Where you looped over data[], you now read data.results[] for one session, and expect one event per session.

Check data.report_type to tell a lab panel (lab) from a DEXA scan (dexa). unspecified means Terra has not classified it.

4. Map the result fields

Every legacy field still exists; most moved into a layer that says what kind of thing it is. source is what the report literally said, biomarker is what Terra matched it to, measurement is the normalised value, and interpretation is the verdict.

Legacy field	New location	Notes
original_name	source.name	Verbatim from the report
display_name	biomarker.display_name
biomarker	biomarker.key	null when unmatched, as before
type	biomarker.specimen	blood, serum, urine…
value	measurement.numeric
value_bound.greater_than / .less_than	measurement.bounded	Now { "operator": ">", "value": 5 }
display_units	source.units	The report's own units
unit_code	measurement.ucum_code
units (structured object)	Removed	Use measurement.ucum_code
notes	source.notes
reference_ranges[].reference_lower_bound	reference_ranges[].lower
reference_ranges[].reference_upper_bound	reference_ranges[].upper
reference_ranges[].classification	reference_ranges[].label	Verbatim; type carries the coded value
reference_ranges[].context	reference_ranges[].context	Unchanged
New	measurement.qualitative / .text / .absent_reason	Non-numeric results are now typed
New	interpretation.flag / .flag_raw	Normalised flag, plus the report's own wording
New	interpretation.applied_range	The range the flag was judged against
New	biomarker.loinc_code, .panel_id, .panel_key
New	biomarker.region, source.region_name	DEXA: which anatomical site
New	source.collection_date / .collection_time	Per-result, when the report gives them

Reference ranges are bands, not one interval. A result can carry several. HbA1c arrives as <5.7, 5.7–6.4, ≥6.5. Read label for what each band means; do not assume the middle one is "normal". type is a coded version of label and is omitted when the report's wording doesn't map onto the enum.

5. Statuses

Most of the vocabulary carries over unchanged: processing, processed, standardizing, standardized, sending, sent, retry_scheduled, retrying, cancelled, failed and deleted all mean what they did.

Two differences to handle if you branch on status:

• partially_sent is new. A report can now be delivered to several destinations independently, so this means some succeeded and some failed. Treat it as terminal, and read GET /v2/reports/{session_id}/deliveries to see which is which.

• received, queued, dequeued and dead_lettered are not part of the new set. If you have a branch on any of them, it becomes dead code.

What does not carry over

• Your existing reports stay where they are. History is not copied to the new API. Keep reading it from your own store, or from the dashboard, which shows both.

• Reprocess. POST /v2/reports/{session_id}/reprocess is not yet available. If you rely on reprocessing, re-upload the file for now and speak to your account contact.

Migrating in practice

1. Enable the capability and confirm a test upload returns 202.

2. Point one non-production environment at /v2/reports.

3. Update your webhook handler for the envelope: branch on type, read data.results[], dedupe on event_id.

4. Compare one real report through both stacks and diff the output.

5. Switch production. Nothing needs to happen at once. Both endpoints keep working.

Stuck on a field that doesn't map cleanly? Send us the report and the shape you need; that is usually a catalogue fix on our side, not work on yours.