Integration API

Healthcare Integration API

Exposes clean JSON REST endpoints for syncing your local desktop clinic management systems with the OpsPort Web Portal database.


Authentication & Request Headers

To access the integration endpoints, you must include the security header `X-API-Key` in all HTTP POST requests. The API checks this header against configuration keys.

Default API Header Credentials
Header Name:X-API-Key
API Key:•••••••••••••••••••••••• (Log in to view key)
Login to Copy
You can configure this API key inside `appsettings.json` under `"HealthcareApi:ApiKey"` key.
Upsert Strategy (Avoid Duplicates)

The API handles intelligent upsert rules to maintain data integrity when syncing records:

  • Clinics: Looks up by `Code`. If found, updates the record; otherwise, creates a new clinic.
  • Doctors: Looks up by `Code` or `LicenseNumber`. If matching, updates the profile; otherwise, inserts.
  • Patients: Looks up by `PatientNo`, `NationalID`, or `Mobile` + `Name` matching to prevent double entries.
  • Appointments: Looks up by Patient, Date, and Start Time. If matching, updates status/details; otherwise, creates a new slot.

Clinics Sync API

Create or update clinic configurations in the portal database.

POST /api/healthcare/clinic Create/update a single clinic. Use `/api/healthcare/clinics` with a JSON array for bulk imports.
Request Body (JSON)
{
  "name": "General Pediatric Clinic",
  "code": "CLN-PED-01",
  "number": "104",
  "specialization": "Pediatrics",
  "clinicType": "Outpatient",
  "branch": "Riyadh Main",
  "floor": "1st Floor",
  "location": "Building A, West Wing",
  "accountNo": "GL-1200",
  "costCenterNo": "CC-901",
  "address": "Olaya Street, Riyadh",
  "phone": "+966500000000",
  "email": "pediatrics@hwadiclinic.com",
  "isActive": true
}

Doctors Sync API

Create/update physician profiles and map them to their respective clinics using code lookup identifiers.

POST /api/healthcare/doctor For bulk doctors import, POST a JSON array to `/api/healthcare/doctors`.
Request Body (JSON)
{
  "name": "Dr. Sarah Al-Otaibi",
  "aName": "د. سارة العتيبي",
  "code": "DOC-SARAH-04",
  "branch": "Riyadh Main",
  "gender": "Female",
  "dateOfBirth": "1985-05-12",
  "medicalRegNumber": "M-20412",
  "idNumber": "1098473521",
  "accountNo": "GL-3100",
  "costCenter": "CC-901",
  "description": "Consultant Pediatrician with 12+ years experience.",
  "email": "s.otaibi@hwadiclinic.com",
  "phone": "+966501111111",
  "specialization": "Pediatrics",
  "licenseNumber": "LIC-PED-9988",
  "isActive": true,
  "clinicCodes": ["CLN-PED-01"]
}

Patients Sync API

Create or update patient files. The `patientNo` and `nationalID` serve as primary identifiers for patient portal logins and declarations intake.

POST /api/healthcare/patient For bulk patients import, POST a JSON array to `/api/healthcare/patients`.
Request Body (JSON)
{
  "name": "Yousef Bin Khalid",
  "patientNo": "P-10928",
  "firstName": "Yousef",
  "secondName": "Bin",
  "lastName": "Khalid",
  "mobile": "+966502222222",
  "dateOfBirth": "1994-09-20",
  "gender": "Male",
  "nationalID": "1048291048",
  "email": "yousef.khalid@gmail.com",
  "phone": "+966502222222",
  "bloodType": "O+",
  "isActive": true
}

Appointments Sync API

Create or reschedule patient bookings. You can use desktop reference codes like `patientNo`, `doctorCode`, and `clinicCode` to dynamically map IDs without querying database keys first.

POST /api/healthcare/appointment For bulk appointments import, POST a JSON array to `/api/healthcare/appointments`.
Request Body (JSON)
{
  "patientNo": "P-10928",
  "doctorCode": "DOC-SARAH-04",
  "clinicCode": "CLN-PED-01",
  "date": "2026-06-15T00:00:00",
  "timeFrom": "10:30:00",
  "timeTo": "11:00:00",
  "status": "Confirmed",
  "notes": "Regular pediatric dental consult."
}

Integration Code Examples

Use these code blocks to implement the synchronization module directly inside your desktop application.

curl -X POST "http://localhost:5082/api/healthcare/appointment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "{
    \"patientNo\": \"P-10928\",
    \"doctorCode\": \"DOC-SARAH-04\",
    \"clinicCode\": \"CLN-PED-01\",
    \"date\": \"2026-06-15T00:00:00\",
    \"timeFrom\": \"10:30:00\",
    \"timeTo\": \"11:00:00\",
    \"status\": \"Confirmed\",
    \"notes\": \"Synced from desktop app.\"
  }"
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");

        var appointmentPayload = new
        {
            patientNo = "P-10928",
            doctorCode = "DOC-SARAH-04",
            clinicCode = "CLN-PED-01",
            date = DateTime.Parse("2026-06-15"),
            timeFrom = "10:30:00",
            timeTo = "11:00:00",
            status = "Confirmed",
            notes = "Synced from desktop app."
        };

        var json = JsonSerializer.Serialize(appointmentPayload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync("http://localhost:5082/api/healthcare/appointment", content);
        if (response.IsSuccessStatusCode)
        {
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Sync Success: " + result);
        }
        else
        {
            Console.WriteLine("Sync Error: " + response.StatusCode);
        }
    }
}
import requests

url = "http://localhost:5082/api/healthcare/appointment"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "patientNo": "P-10928",
    "doctorCode": "DOC-SARAH-04",
    "clinicCode": "CLN-PED-01",
    "date": "2026-06-15T00:00:00",
    "timeFrom": "10:30:00",
    "timeTo": "11:00:00",
    "status": "Confirmed",
    "notes": "Synced from desktop app."
}

response = requests.post(url, json=payload, headers=headers)
print("Response:", response.status_code, response.json())

API Interactive Sandbox

Test the sync API endpoints in real-time. Select an endpoint, adjust the JSON request body, input your API key, and submit the request to see the live server response.


You are not logged in. You can type a key or login to auto-fill the configured key.
Server Response
-
No request executed yet.