openSPP Eligibility → openIMIS Enrollment Implementation

Content

1 Purpose
2 Trigger
3 Workflow Overview
4 Diagram
5 Workflow Steps
6 Interaction Table
7 Resources Summary
- 7.1 Curl request
- 7.2 Example : openSPP registry response (native, pre-DCI format):
8 Known Gaps & Next Steps
9 Prototype in openIMIS

Properties

Reference	https://standards.spdci.org/standards/dci-standards/wip-social-registry-v1.0.0
Sector	Social Protection
Components
github

Purpose

In the openIMIS sandbox context, this workflow illustrates how a social protection eligibility decision made in openSPP can automatically trigger an enrollment or coverage update in openIMIS.

The goal is to demonstrate how digital social protection systems can interface with health insurance systems through standardized APIs, enabling automated beneficiary enrollment, improved targeting, and reduced manual workload for government agencies.

This scenario reflects how eligibility data from social registries can be used to seamlessly trigger insurance enrollment, ensuring that approved beneficiaries receive timely access to health services.

Key objectives:

Enable automated enrollment of eligible beneficiaries into openIMIS without manual data re-entry
Demonstrate Social Registry → SP-MIS interoperability per the DCI architecture
Establish a reusable pattern, to be migrated to a DCI-compliant exchange once openSPP exposes standardized DCI endpoints

ℹ️ Note on standards maturity: At the time of this implementation, openSPP did not yet expose a DCI-compliant API. The data exchange described below uses openSPP's native registry API format (given_name, family_name, reg_ids, etc.), not the standardized DCI schema. This page documents the point-to-point integration as actually implemented. Migration to full DCI compliance is tracked as a known gap (see below).

Trigger

An individual is registered or updated in openSPP's social registry, and is identified as eligible for health insurance enrollment.

Workflow Overview

Field	Value

Field

Value

Workflow Maturity

Implemented : tested end-to-end in sandbox.

Referenced Standards

DCI (Digital Convergence Initiative) — Social Registry / SP-MIS interoperability: https://spdci.org · openSPP Registry API (native format, pre-DCI, used in this implementation)

DCI Alignment

Partial direct point-to-point integration (no Data Exchange layer in this implementation). Architecture is SP-MIS (openSPP) → FIS-adjacent registry function (openIMIS Individual module).

Actors

Role	System	Description
Social Registry	openSPP	Holds individual/household records and runs the eligibility check. Determines which individuals qualify for a benefit/program. Exposes a registry API (search by ID, by name, or full dataset retrieval).
Integration Module	openIMIS Sandbox : internal module	Calls the openSPP API, retrieves individual records flagged as eligible, transforms the openSPP-native payload into openIMIS's `Individual` data structure. Acts as the de facto mediator in absence of a dedicated DCI exchange layer.
SP-MIS	openIMIS `Individual` module	Receives the transformed data and creates or updates the corresponding `Individual` record, from which enrollment/coverage can subsequently be processed.

Assumptions & Prerequisites

openSPP is deployed and its registry API is reachable from the openIMIS sandbox environment.
openSPP exposes individual records via GET /api/v1/registry/individual/{id} (or equivalent search by name / full dataset).
The eligibility check is performed entirely on the openSPP side : openIMIS receives individuals already determined eligible.
The openIMIS Individual module is available and can accept programmatic creation/update of records.
A user (operator) is available to review and select which eligible individuals retrieved from openSPP should be enrolled — enrollment is not fully automatic in the current prototype; it includes a manual selection step.
No DCI-standard schema validation is enforced on either side, since openSPP's API predates DCI adoption in this context.

Validations

Integration module must validate:

Successful response from the openSPP API (HTTP 200, well-formed JSON)
Presence of mandatory fields required by openIMIS's Individual model (e.g. given_name, family_name)
Absence of duplicate Individual records before creating a new one

openIMIS (Individual module, SP-MIS) must validate:

Data completeness against the Individual model's required fields
Uniqueness constraints on individual identity

⚠️ Current sandbox limitation: Field-level mapping between openSPP's schema and openIMIS's Individual model is manual/hardcoded in the current prototype, not config-driven.

Diagram

Workflow Steps

Step 1 — Eligibility Check in openSPP

An individual (or household member) registered in openSPP's Social Registry is evaluated against program eligibility criteria. openSPP determines the individual is eligible for enrollment.

Step 2 — Integration Module Queries openSPP

The openIMIS sandbox integration module queries the openSPP registry API to retrieve eligible individual records. Three query modes are supported:

By individual ID
By individual name (case-sensitive)
Full dataset retrieval (no filter)

Transaction: GET /api/v1/registry/individual/{id} (Integration module → openSPP)

Step 3 — Operator Reviews & Selects Individuals

The retrieved individual data is surfaced in openIMIS's Individual module UI. A human operator reviews the dataset and selects which eligible individuals should be enrolled.

Step 4 — Data Transformation

The integration module transforms the selected openSPP-native payload (given_name, addl_name, family_name, reg_ids, phone_number_ids, etc.) into the structure expected by openIMIS's Individual model.

Step 5 — Individual Creation/Update in openIMIS (SP-MIS)

The transformed data is submitted to create or update the corresponding Individual record in openIMIS, from which subsequent enrollment or coverage workflows can proceed.

Transaction: Internal — Individual module create/update (Integration module → openIMIS)

Interaction Table

#	Interaction	From	To	FHIR Resource / Action	Reference

#	Interaction	From	To	FHIR Resource / Action	Reference
1	Eligibility check	openSPP	openSPP	Internal — eligibility decision on registered individual	Eligibility logic runs entirely on Social Registry side
2	Query individual registry	Integration module	openSPP (Social Registry)	`GET /api/v1/registry/individual/{id}`	By ID, by name, or full dataset
3	Return individual data	openSPP (Social Registry)	Integration module	openSPP-native JSON payload	Pre-DCI schema
4	Review & select individuals	Operator	openIMIS (`Individual` UI)	Internal — manual selection	Not fully automated
5	Transform payload	Integration module	Integration module	Internal — field mapping openSPP → openIMIS	Manual/hardcoded mapping
6	Create/update Individual	Integration module	openIMIS (SP-MIS, `Individual` module)	Internal — `Individual` create/update

Resources Summary

Resource / Object	System	Purpose

Resource / Object	System	Purpose
openSPP `individual` registry record	openSPP (Social Registry)	Source record: demographics, registration date, identifiers, contact info, eligibility outcome
openIMIS `Individual`	openIMIS (SP-MIS)	Target record: pivot object for subsequent enrollment, eligibility, and coverage workflows

Curl request

curl -X 'GET' \
  'http://<openspp_server_url>/api/v1/registry/individual/66' \
  -H 'accept: application/json'

Example : openSPP registry response (native, pre-DCI format):

{
  "id": 66,
  "name": "DEEPESH, BANIYA DIPESH BANIYA",
  "reg_ids": [],
  "is_group": false,
  "registration_date": "2025-04-28",
  "phone_number_ids": [],
  "email": null,
  "address": null,
  "given_name": "Baniya",
  "addl_name": null,
  "family_name": "Deepesh",
  "gender": null,
  "birthdate": null,
  "birth_place": null
}

Known Gaps & Next Steps

Gap	Priority	Owner

Gap	Priority	Owner
Migrate to DCI-compliant exchange once openSPP exposes a DCI endpoint	High	Community / Sandbox team
Automate enrollment trigger (remove manual operator selection step)	Medium	Sandbox team
Replace hardcoded field mapping with a configurable mapping layer	Medium	Sandbox team
Add duplicate-detection / matching logic before `Individual` creation	Low	Sandbox team

(a) Creating simple module within openIMIS itself as part of sandbox project to trigger interoperability

Prototype in openIMIS

User can check and select which individual data can be enrolled in “Individual” module. openSPP provides DCI apis , each individual can be searched by

id of individual
name of individual (case sensitive)
or without id or name it will grab whole data.