API documentation

Endpoints, examples and error codes for outside systems. Read only, taken from the signed-off scoping spec.

Acceptance criteria

US-27a API Endpoints: First Family (Reception/Eligibility) HIGHEST NEW SCREEN

As a client integration, I want the first prioritized endpoint family exposed, so that we validate the build approach before scaling to other families.

First prioritized family works per documented push/pull direction.
Valid scoped credential → response matches spec exactly.
Invalid push payload → clear validation error, not a 500.

US-27b API Endpoints: Remaining Families (Finance, Diagnosis) HIGHEST NEW SCREEN

As a client integration, I want the remaining endpoint families exposed, so that clients have full API coverage.

Finance/payment/claim + diagnosis endpoints follow the US-27a pattern.
Consistent behavior/error-handling across all endpoints.
Full API documentation finalized for a pilot client.

US-17 API Discovery & Scoping MEDIUM

As the PM, I want a documented API scoping spec from workshops with the team, so Production API build has clear requirements.

Workshops with Tech Leader to produce a spec: push vs. pull, target entities, auth model, rate limits, per the 3 named families (reception/eligibility, finance/payment/claim, diagnosis/doctor).
Spec explicitly confirms whether endpoints beyond the 3 named families are required.
Signed off by CEO before Production API build begins.

OverviewAuthenticationReceptionFinanceDiagnosisErrors

Overview

The API lets an outside system read from and write to RaneemHCP over HTTPS and JSON. Calls are scoped per endpoint family. Every client sees only the families it was given.

Base URL: https://api.alraneem-hospital.example/v1
Format: JSON, UTF-8
Versioning: In the path, version 1 today
Rate limit: Per client, set when the client is created. Over the limit returns 429.

API scoping spec

Direction (push or pull), target entities, auth model and rate limits for the three families come from the signed-off scoping spec. This page is generated from that contract and does not change it.

Spec v1.2Signed offWhether endpoints beyond the three families are needed is confirmed in the spec, section 4.

Get a token

API access

Add a client on the API access screen and keep the secret. Exchange it for a short lived token, then send the token on every call.

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=cl_wecare_4f19
&client_secret=<your secret>
&scope=reception.read diagnosis.write

200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "reception.read diagnosis.write"
}

GET /v1/eligibility/EL-30551
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Scopes

Scope	Allows
`reception.read`	Read patients and eligibility results
`reception.write`	Start eligibility checks
`finance.read`	Read claims, batches and payment notices
`diagnosis.write`	Push diagnoses for a visit
`diagnosis.read`	Read diagnoses and care team

Reception and eligibility

GET/v1/patients/{nationalId}Find a patient

POST/v1/eligibilityStart an eligibility check

GET/v1/eligibility/{id}Read the result

Example: start an eligibility check

POST /v1/eligibility
Authorization: Bearer <token>

{
  "patientId": "1087654321",
  "payer": "Bupa Arabia",
  "serviceDate": "2026-10-05",
  "purpose": ["benefits", "validation"]
}

202 Accepted
{
  "id": "EL-30551",
  "status": "Pending",
  "pollUrl": "/v1/eligibility/EL-30551"
}

Finance, payment and claim

GET/v1/claims/{id}Read a claim and its outcome

GET/v1/batches/{id}Read a batch

GET/v1/paymentsList payment notices

GET/v1/payments/{id}Read one notice

Example: read a claim

GET /v1/claims/CL-20418
Authorization: Bearer <token>

200 OK
{
  "id": "CL-20418",
  "status": "Rejected",
  "payer": "Bupa Arabia",
  "total": { "value": 950.00, "currency": "SAR" },
  "reason": "Member not covered"
}

Diagnosis and doctor

POST/v1/diagnosesPush a diagnosis from a clinical system

GET/v1/diagnoses/{visitId}Read diagnoses of a visit

GET/v1/doctors/{id}Read a care team member

Used by the Diagnoses step of a claim. Failed validations go to Quarantined responses

Example: push a diagnosis

POST /v1/diagnoses
Authorization: Bearer <token>

{
  "resourceType": "Condition",
  "subject": { "reference": "Patient/1087654321" },
  "encounter": { "reference": "Encounter/V-77120" },
  "code": { "coding": [{ "system": "http://hl7.org/fhir/sid/icd-10-am", "code": "J02.9" }] }
}

201 Created
{ "id": "DX-5521", "status": "Accepted" }

Error codes

Status	Code	Meaning	What to do
400	`invalid_request`	The request is not valid JSON or misses a field	Fix the payload. The body lists each field.
401	`invalid_token`	Missing, expired or revoked credentials	Get a new token. If revoked, ask the administrator.
403	`out_of_scope`	Valid credentials, family not granted	Ask the administrator to add the scope.
404	`not_found`	No record with that id	Check the id.
422	`validation_failed`	A pushed payload broke a rule	Fix the fields named in the response. Nothing is saved.
429	`rate_limited`	Over the client rate limit	Wait for the seconds in Retry-After.
503	`unavailable`	NPHIES or RaneemHCP is not reachable	Retry with a delay.

Example: validation error

422 Unprocessable Entity
{
  "code": "validation_failed",
  "message": "The diagnosis could not be accepted.",
  "errors": [
    { "field": "code.coding[0].code", "issue": "Unknown ICD-10-AM code J02.99" }
  ],
  "requestId": "req_7f31c2"
}