Integration Workflow

This page shows how the pieces of the BGT API fit together end-to-end, so you can picture the whole integration before diving into the individual REST endpoints and webhook events.

There are two flows to understand:

1. Referral ordering — you place an order, we create and issue the referral(s), and you retrieve the referral PDF.
2. Results delivery — the lab returns results over time, we notify you as the referral and results progress, and you pull the canonical result data.

Both flows follow the same pattern:

The golden rule

Webhooks are notifications, not data. Treat every webhook as a signal that something changed, then call the REST API to fetch the current, canonical state. Webhook payloads are intentionally minimal — the REST response is the source of truth.

Throughout, Integrator is your system and BGT is our API.

Referral ordering

You place an order over HTTP and receive an immediate confirmation. Once the referral has been issued (its PDF generated), we fire a webhook — that's your cue to fetch the referral and download the PDF.

Step by step:

1. Place the order. POST /v1/referrals with the patient and test details. This call can take up to ~10 seconds — allow for it before retrying so you don't create duplicate orders.
2. Read the synchronous response. The referral(s) come back immediately, typically with status CREATED. A single request can create more than one referral (for example a split bundle), so always handle an array.
3. Wait for referral.issued. When the referral PDF has been generated, we send the referral.issued webhook. (referral.created also fires — see edge cases for the branches you may see instead.)
4. Fetch the issued referral. GET /v1/referrals/{uuid} returns the current payload including referralAttachment — a time-limited signed URL to the referral PDF.
5. Deliver the PDF. Download it and/or email it to the patient so they can attend collection. Signed URLs expire, so re-fetch the referral if you need a fresh link.

Ordering edge cases

Not every order goes straight to ISSUED. Depending on the order, you may receive one of these instead of (or before) referral.issued:

Webhook / status	What it means	What to do
referral.pending_verification	The profile needs completing before the referral can be issued.	Complete verification; referral.issued follows.
referral.billing_failed	Billing for the API order could not be completed.	Fix the billing method and re-order.
referral.scheduled_reissue	A new PDF is being regenerated (e.g. after a PATCH).	Wait for the next referral.issued, then re-fetch.

See Referral statuses for the full lifecycle.

Results delivery

After collection, the lab returns results — sometimes partially, then in full. Each change fires a webhook. As always, the webhook is the signal; you then pull the full result from the REST API.

Step by step:

1. Referral state changes. As results arrive, the referral transitions to PARTIAL_RESULTS and then COMPLETE, firing referral.partial_results (which can fire multiple times) and finally referral.complete.
2. Result records change. In parallel, the result itself fires result.created and result.updated (and result.partial_results / result.complete) as biomarker data is populated and finalised.
3. Fetch the result. Use the resultsUuid from the referral (or the result UUID from the webhook) to call GET /v1/results/{uuid}.
4. Ingest the canonical data. Each response returns the full result set — all biomarkers known so far, plus a biomarkerSummary and a resultAttachment PDF URL — not just what changed. You can safely overwrite your stored copy with each fetch rather than trying to merge deltas.

Partial then complete

Because every fetch is the full snapshot, handling PARTIAL_RESULTS is simply a matter of re-fetching on each webhook. When COMPLETE arrives, the same endpoint returns the finalised set. Some organisations also review results before release (result.in_review) — those are held until reviewed.

Putting it together

Testing the full flow in staging

You don't need a real lab to exercise the results half of this flow. In staging only, PUT /v1/referrals/{uuid} generates dummy results for a referral, firing the same result webhooks your production integration will see. Add ?partial to generate a partial set first so you can test the PARTIAL_RESULTS → COMPLETE transition. See Simulate Results.

Next steps

• REST API — full endpoint reference for referrals and results
• Webhooks — event list, payloads, signatures, and retries
• Authentication — obtaining an access token