> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinikehr.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a referral > **Permission:** `referrals:read` Get one referral from the clinic's list. Only a confirmed referral is fetchable by id. With `Accept: application/fhir+json` the answer is a FHIR R4 ServiceRequest. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml get /v1/clinics/{clinic_id}/referrals/{referral_id} openapi: 3.1.0 info: title: ClinikEHR API version: 1.0.0 description: >- Server-to-server REST API for a clinic's own data, reached with a key the clinic (or a developer workspace) creates in the developer portal. Authenticate every request with `Authorization: Bearer `. Test keys reach only your workspace's own synthetic sandbox; live keys reach the clinic that created them. Lists wrap their rows as `{ data, has_more, next_cursor }`; single resources are returned directly. Errors are `application/problem+json` (RFC 9457) with a stable `code`. Write requests accept an `Idempotency-Key` header so a retry never repeats a change. See the guides for authentication, permissions, pagination, rate limits and retries. servers: - url: https://api.clinikehr.com security: - ApiKey: [] paths: /v1/clinics/{clinic_id}/referrals/{referral_id}: get: tags: - Referrals summary: Get a referral description: >- **Permission:** `referrals:read` Get one referral from the clinic's list. Only a confirmed referral is fetchable by id. With `Accept: application/fhir+json` the answer is a FHIR R4 ServiceRequest. operationId: getReferral parameters: - name: clinic_id in: path required: true schema: type: string format: uuid - name: referral_id in: path required: true schema: type: string format: uuid responses: '200': description: OK. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Referral' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' security: - ApiKey: [] components: schemas: Referral: type: object description: >- A clinical referral: another provider or service asks this clinic to see a patient. It is NOT the clinic referral programme (clinic-to-clinic credits for recommending ClinikEHR), the marketing "referred by" source on a client, or an antenatal or postnatal referral note. The exposed-field allow-list, field by field. `review_status` says where the record stands: `confirmed` is on the clinic's referral list; `pending` is an outside submission still waiting for clinic staff; `rejected` and `withdrawn` are this key's own submissions that did not become a referral. For a confirmed referral `status` is the clinic's workflow: it lands `received`, and only the clinic accepts, declines, schedules, completes or cancels it. A sender can never change `status`, `recipient` or `scheduled_appointment_id`. `decision_reason` on a confirmed referral (the clinic's reason for declining or cancelling) is shown only to the key or organization that sent it; everyone else sees null. required: - id - patient_id - direction - status - service - reason - review_status properties: id: type: - string - 'null' format: uuid description: >- The referral's id once confirmed; null for a pending create (use `submission_id`). A pending update or retraction carries the id of the referral it targets. patient_id: type: string format: uuid direction: type: - string - 'null' enum: - incoming - outgoing - null description: >- `incoming` is a referral to this clinic. Only `incoming` is written today. status: type: - string - 'null' enum: - received - accepted - scheduled - completed - declined - cancelled - entered_in_error - null description: The clinic's workflow state. Null for a pending submission. priority: type: - string - 'null' enum: - routine - urgent - asap - stat - null service: $ref: '#/components/schemas/ReferralService' reason: $ref: '#/components/schemas/ReferralReason' clinical_summary: type: - string - 'null' requester: $ref: '#/components/schemas/ReferralRequester' recipient: $ref: '#/components/schemas/ReferralRecipient' requested_at: type: - string - 'null' format: date-time needed_by: type: - string - 'null' format: date scheduled_appointment_id: type: - string - 'null' format: uuid source: type: - string - 'null' enum: - clinic - api - null origin_assistant_name: type: - string - 'null' accepted_by: type: - string - 'null' enum: - clinic - automatic - null description: >- Who put this record on the chart: `clinic` (the clinic's own team, or a clinician who confirmed it) or `automatic` (the clinic chose to accept this kind of item from this key or connection without review; the record is on the chart but no clinician has reviewed it, so `verification_status` reads `unconfirmed` until one does). Null while the item is still a pending submission. reviewed_at: type: - string - 'null' format: date-time description: >- Set when a clinician marked an automatically accepted item reviewed; null otherwise. reviewed_by_staff_id: type: - string - 'null' format: uuid description: >- clinic_staff.id of the clinician who marked an automatically accepted item reviewed; null otherwise. review_status: type: string enum: - confirmed - pending - rejected - withdrawn submission_id: type: - string - 'null' format: uuid decision_reason: type: - string - 'null' description: >- On a rejected submission, why clinic staff rejected it. On a confirmed referral, the clinic's reason for declining or cancelling - shown only to the key or organization that sent it. created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time ReferralService: type: object required: - text properties: text: type: - string - 'null' description: What is being asked for, as the sender states it. code: oneOf: - $ref: '#/components/schemas/ReferralServiceCode' - type: 'null' ReferralReason: type: object required: - text properties: text: type: - string - 'null' description: Why the patient is being referred, as the sender states it. code: oneOf: - $ref: '#/components/schemas/ReferralReasonCode' - type: 'null' ReferralRequester: type: object description: >- Who sent the referral, as the sender states it. Nothing here is checked against a directory. properties: name: type: - string - 'null' organization: type: - string - 'null' npi: type: - string - 'null' description: Ten digits. ReferralRecipient: type: object description: >- Who at the clinic will see the patient. Set by clinic staff when they accept the referral; never by a sender. properties: provider_id: type: - string - 'null' format: uuid description: A provider `id` from `listProviders`. department_id: type: - string - 'null' format: uuid Problem: type: object description: RFC 9457 application/problem+json. required: - type - title - status - code - request_id properties: type: type: string format: uri title: type: string status: type: integer detail: type: string code: type: string request_id: type: string errors: type: array items: type: object required: - pointer - message properties: pointer: type: string message: type: string ReferralServiceCode: type: object description: >- A coded service. `system` is `snomed-ct` (a SNOMED CT concept id, 6 to 18 digits; the platform holds no SNOMED corpus, so only its shape is checked) or `local` (your own code, never mapped to a standard). required: - system - code properties: system: type: string enum: - snomed-ct - local code: type: string ReferralReasonCode: type: object description: >- A coded reason. `system` is `icd-10-cm` or `icd-10` (checked against the platform's own diagnosis codes and stored in canonical form; an unrecognised code is refused), `snomed-ct` (6 to 18 digits, shape only) or `local` (your own code, never mapped to a standard). required: - system - code properties: system: type: string enum: - icd-10-cm - icd-10 - snomed-ct - local code: type: string responses: BadRequest: description: >- The request failed validation (unknown query parameter, limit out of range, malformed body). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: >- Missing, malformed, unknown, revoked or expired key, or the wrong secret. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: >- The key or connection lacks the required scope, the plan does not include this resource, the request came from an address this key's IP allow-list does not permit, a TEST-environment workspace key asked for a clinic_id other than its own workspace's sandbox (`sandbox_only`), or a LIVE workspace key asked for a real clinic while its workspace's verification has lapsed (`not_verified`) — the response never names which addresses ARE allowed, nor which clinic actually is the sandbox. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' NotFound: description: The record is absent, or out of the key's scope — one message for both. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' TooManyRequests: description: Rate limited. See the Retry-After header. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: ehr_live__ or ehr_test__ ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.