Skip to main content
A referral is another practice asking this clinic to see a patient: “please assess this patient for a cardiology opinion”. This page covers the referrals a clinic receives. It is not the clinic referral programme (the way clinics invite other clinics to the platform), not a “referred by” marketing source, and not the antenatal or postnatal referral recorded in the maternity module. Reading the list is immediate. Writing is different: a referral you send is held for the clinic to review, and only a member of the clinic’s staff putting it on the clinic’s referral list makes it real. Read Reviewing outside submissions first if you have not already, because everything about sending builds on it. Your request never accepts, declines, books or completes a referral. Those are the clinic’s decisions, made by its staff, and no permission lets a key make them. What you can do is send a referral, correct what you sent while the clinic has not yet acted on it, take it back, and read what became of it. The patient must be one your key is allowed to see. A patient the clinic has restricted, or a record that does not exist, returns 404 with code: "not_found". The two are never told apart. See Errors.

​
What one looks like

A referral you sent that is still waiting has "id": null and "status": null: it is not on the clinic’s list yet. Use submission_id to follow it.

​
Codes

A code is a system and a code together, or absent. For service, system is snomed-ct (digits only) or local (your own code, up to 64 characters). For reason, system is icd-10-cm, icd-10, snomed-ct or local. An ICD-10 code is checked against a verified list, and one that is not a real ICD-10 code is refused with invalid_request. A code is stored in its standard form. Send the reason as text only if you are unsure of the code.

​
Status

The clinic moves a referral through these words. You can read them; you can never set them. A finished referral (completed, declined, cancelled) is never reopened, and one marked entered_in_error never changes.

​
List referrals

  • confirmed is every referral on the patient’s record at the clinic, including those other senders made and those the clinic recorded itself.
  • pending is the referrals your own key or organization sent that are waiting for a decision, plus those declined, each with its review_status. You never see another party’s submissions.
  • all is both together.
An item with review_status other than confirmed is not on the clinic’s list. An empty list does not mean the patient has no referrals. It means none has been confirmed.

​
Send a referral

A field not listed here is refused with invalid_request, naming it. status, recipient, direction and any decision field are not accepted on a new referral. A referral always starts as received, once the clinic accepts it. Idempotency-Key is required on POST (optional on PATCH). See Retries and duplicates.

​
The answer is 202, not 201

The body is the submission, showing "status": "pending". A 202 is a receipt. It is not a referral on the clinic’s list.

​
After you send one

  • pending: waiting for the clinic.
  • confirmed: the clinic added it to its referral list as received. Read the referral to follow its status from there.
  • rejected: the clinic declined to add it, with the reason. Do not resend it unchanged.
  • withdrawn: you took it back while it was pending.
Only the key or organization that sent a submission can read it. Anyone else gets 404. Being added to the list is not the same as being accepted: a confirmed submission is a received referral, and the clinic’s decision to see the patient comes later, as status.

​
Change or take back a referral

Send only the fields that change: any of priority, needed_by, reason, clinical_summary, requester. The service cannot be changed: a different service is a new referral. The answer is 202 Accepted and the change waits for the clinic’s review. To take a referral back as sent in error, send { "status": "entered_in_error" } on its own. That is the only status a request can send. Only until the clinic acts on it. A change or a take-back is possible only while the referral is still received. Once the clinic has accepted, declined, booked or finished it, a change is refused with 400 invalid_request, saying the clinic has already actioned the referral. You cannot cancel it either: cancelling is the clinic’s decision. Ask the clinic. A clinic can also choose to accept new referrals without review. Then the answer to your send already shows review_status: "confirmed" and accepted_automatically: true, and the referral lands as received with accepted_by: "automatic". Accepting, declining and booking it stay with the clinic’s team, and reviewed_at and reviewed_by_staff_id are null until a clinician marks it reviewed. See Automatic acceptance.

​
Who sees a reason

When the clinic declines or cancels a referral it writes a reason. That reason may carry sensitive wording, so it is shown only to the key or organization that sent the referral. Every other key reads decision_reason: null. On a rejected submission, decision_reason is the reason the clinic gave for not adding it to its list.

​
FHIR

Send Accept: application/fhir+json to read a referral as a ServiceRequest (intent: "order", with the SNOMED CT “Patient referral” category). The status words map as received, accepted and scheduled to active, completed to completed, declined and cancelled to revoked, and entered_in_error to entered-in-error. A submission still waiting for review reads as draft, and only when you ask for pending or all. FHIR is not accepted as input: send and change referrals with the JSON routes above. A FHIR body is refused with an OperationOutcome. See FHIR R4.

​
A worked example

  1. A referring practice’s system sends POST …/referrals for a cardiology consultation, with an Idempotency-Key. The answer is 202, with a Location header.
  2. GET …/referrals?patient_id=… does not show it. It is not on the clinic’s list.
  3. A member of the clinic’s staff opens Review outside data, reads it and selects Accept. You read the submission and it is confirmed.
  4. GET …/referrals?patient_id=… now returns it with status: "received" and source: "api". The clinic’s Referrals to action list and the patient’s Referrals section show it.
  5. The clinic accepts it, books an appointment and later marks it completed. Each time you read it, status has moved on (accepted, scheduled, completed). You did not do any of it, and could not.
  6. Had you needed to correct the priority, you could have while status was still received. After the clinic accepts it (step 5), a change is refused.
A test key reaches only your workspace’s sandbox, which holds an invented received referral for each invented patient, so you can try the requests above without touching a real chart. A referral you send there is never actioned.