Connect API

The Connect API is OpesCare's primary REST interface for healthcare system integration. Use OAuth 2.0 client credentials to authenticate, then access patient records, consent, inventory, and operational data.

All Connect API endpoints require a Bearer token in the Authorization header. See Authentication for how to obtain one.

Base URL

https://opescare.test/api/v1/connect

Step 1 — Get a Token

POST /connect/auth/token

Issues an OAuth 2.0 Bearer token using client_credentials grant. See Authentication for full code examples and available scopes.

Health ID Resolution KEY ENDPOINT

The primary interoperability endpoint. Accepts a Health ID or patient demographics. Returns the existing Health ID if the patient is found, or auto-creates a new patient record and issues a fresh Health ID if they are not yet registered in OpesCare.

POST /connect/patients/resolve

Field	Type	Required	Description
`health_id`	string	Either/or	Known OpesCare Health ID to look up (e.g. `CM-HID-7KQ9-MP42-X8D1`)
`first_name`	string	Either/or	Patient first name (required when no health_id)
`last_name`	string	Either/or	Patient last name
`date_of_birth`	string	Either/or	ISO date `YYYY-MM-DD`
`country_code`	string	No	ISO 2-letter code, default `CM`
`sex`	string	No	`male` / `female` / `other`
`phone_number`	string	No	Patient phone (stored if creating)
`purpose`	string	No	Reason for lookup — logged in audit trail
`external_reference`	string	No	Your system's patient ID — logged for traceability

Response status values:

found — patient already registered; health_id returned
created — new patient registered; new health_id issued (HTTP 201)
not_found — health_id provided but not registered; supply demographics to register

# Case A — patient has no Health ID yet (auto-creates)
curl -X POST https://opescare.test/api/v1/connect/patients/resolve \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Marie",
    "last_name": "Fouda",
    "date_of_birth": "1990-07-22",
    "country_code": "CM",
    "sex": "female",
    "purpose": "his_registration",
    "external_reference": "HIS-PAT-00341"
  }'

# Case B — patient already has a Health ID (lookup only)
curl -X POST https://opescare.test/api/v1/connect/patients/resolve \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"health_id": "CM-HID-7KQ9-MP42-X8D1"}'

$response = Http::withToken($accessToken)
    ->post('https://opescare.test/api/v1/connect/patients/resolve', [
        'first_name'         => 'Marie',
        'last_name'          => 'Fouda',
        'date_of_birth'      => '1990-07-22',
        'country_code'       => 'CM',
        'sex'                => 'female',
        'purpose'            => 'his_registration',
        'external_reference' => 'HIS-PAT-00341',
    ])->json();

$healthId = $response['health_id'];  // use this for all future calls
$status   = $response['status'];     // 'found' or 'created'

const res = await fetch(
  'https://opescare.test/api/v1/connect/patients/resolve',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      first_name: 'Marie',
      last_name: 'Fouda',
      date_of_birth: '1990-07-22',
      country_code: 'CM',
      sex: 'female',
      purpose: 'his_registration',
      external_reference: 'HIS-PAT-00341',
    }),
  }
).then(r => r.json());

const healthId = res.health_id;
// status === 'found' → existing patient
// status === 'created' → new patient, store this health_id in your HIS

resp = requests.post(
    'https://opescare.test/api/v1/connect/patients/resolve',
    json={
        'first_name': 'Marie',
        'last_name': 'Fouda',
        'date_of_birth': '1990-07-22',
        'country_code': 'CM',
        'sex': 'female',
        'purpose': 'his_registration',
        'external_reference': 'HIS-PAT-00341',
    },
    headers={'Authorization': f'Bearer {access_token}'},
)
data = resp.json()
health_id = data['health_id']

Recommended flow for HIS integration: On every patient encounter, call /patients/resolve first. Store the returned health_id in your system. Use it for all subsequent record pushes. This ensures the patient exists in OpesCare before any clinical data is sent.

GET /connect/patients/verify/{health_id}

Validate a Health ID format (checksum) and confirm it is registered in OpesCare. Returns patient summary if valid.

curl "https://opescare.test/api/v1/connect/patients/verify/CM-HID-7KQ9-MP42-X8D1" \
  -H "Authorization: Bearer {access_token}"

Patient Search

GET /connect/patient/search?health_id={health_id}

Look up a patient by their OpesCare Health ID. Requires patient:profile:read scope.

Parameter	Type	Required	Description
`health_id`	string	Yes	OpesCare Health ID (e.g. `OPC-2024-XK7T9`)

curl "https://opescare.test/api/v1/connect/patient/search?health_id=OPC-2024-XK7T9" \
  -H "Authorization: Bearer {access_token}"

$patient = Http::withToken($accessToken)
    ->get('https://opescare.test/api/v1/connect/patient/search', [
        'health_id' => 'OPC-2024-XK7T9',
    ])->json();

const patient = await fetch(
  'https://opescare.test/api/v1/connect/patient/search?health_id=OPC-2024-XK7T9',
  { headers: { Authorization: `Bearer ${accessToken}` } }
).then(r => r.json());

patient = requests.get(
    'https://opescare.test/api/v1/connect/patient/search',
    params={'health_id': 'OPC-2024-XK7T9'},
    headers={'Authorization': f'Bearer {access_token}'}
).json()

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://opescare.test/api/v1/connect/patient/search?health_id=OPC-2024-XK7T9"))
    .header("Authorization", "Bearer " + accessToken)
    .GET().build();

GET /connect/patient/{health_id}/consent

Returns the patient's current consent status for your integration client. Check this before requesting records.

POST /connect/patient/{health_id}/consent/grant

Records that the patient has granted consent. The patient must be present or verified through another channel. This action is audited.

curl -X POST "https://opescare.test/api/v1/connect/patient/OPC-2024-XK7T9/consent/grant" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_type": "full_record",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Http::withToken($accessToken)
    ->post('https://opescare.test/api/v1/connect/patient/OPC-2024-XK7T9/consent/grant', [
        'consent_type' => 'full_record',
        'expires_at'   => '2026-12-31T23:59:59Z',
    ]);

requests.post(
    'https://opescare.test/api/v1/connect/patient/OPC-2024-XK7T9/consent/grant',
    headers={'Authorization': f'Bearer {access_token}'},
    json={'consent_type': 'full_record', 'expires_at': '2026-12-31T23:59:59Z'}
)

Records Endpoints

GET /connect/patient/{health_id}/records

Retrieve patient medical records. Requires active consent and patient:diagnostics:read scope.

Parameter	Values	Default
`type`	`diagnoses` `prescriptions` `lab_results` `vitals` `all`	`all`

Inventory Endpoints

GET /connect/inventory/pharmacy/{facility_id}

Pharmacy stock levels. Requires pharmacy:stock:read scope.

GET /connect/inventory/blood/{facility_id}

Blood bank inventory by blood group and component. Requires blood:inventory:read scope.

Blood and medicine availability shown via the API is indicative only and does not guarantee supply. Always confirm directly with the facility before making clinical decisions.

Webhook Subscription Endpoints

POST /connect/webhooks/subscriptions

Subscribe your endpoint to receive push events. See Webhooks for the full guide including signature verification.

GET /connect/webhooks/subscriptions

List your active webhook subscriptions.

DELETE /connect/webhooks/subscriptions/{id}

Unsubscribe an endpoint. Returns 204 No Content.

Reconciliation

GET /connect/reconciliation?date={date}

Retrieve payment reconciliation records for a specific date.

Try It

Use the Interactive Playground to try all 16 Connect API endpoints live in your browser with the full OpenAPI spec.

← Authentication SDK →