Provider App Integration

This document is a guide for integrating Provider Apps as network participants on the UBI Network. Providers are responsible for publishing benefits, receiving applications from seekers, validating them using eligibility and verification SDKs, and confirming or rejecting applications.

Sequence of API Calls

  1. on_search → Respond to beneficiary search with available benefits.

  2. on_select → Confirm selected benefit details.

  3. on_init → Verify eligibility and initialize application.

  4. on_update → Update application if needed.

  5. on_confirm → Approve or reject application.

  6. on_status → Check application status.

Integration Flow

  1. Receive Search Request (from Seeker via UBI Network).

  2. Respond with Benefit Catalog (on_search).

  3. Handle Selection (on_select) → return details.

  4. Initialize Application (on_init) → validate user + eligibility + docs.

  5. Update Application (on_update) → update or resubmit the application.

  6. Confirm Application (on_confirm) → finalize approval/rejection.

  7. Application Status (on_status) → return application status.

Let’s walk through how a Provider App Participant (BPP) integrates with the UBI network using the standard API flow. In this use case, the BPP is offering benefit schemes.

API References

1. on_search API – Return Available Benefits

When a beneficiary searches for benefits in their Beneficiary App (BAP), the BAP sends a /search request on the network. The BPP receives this request and responds with /on_search, providing a list of benefits or schemes offered by the provider.

Purpose

Respond to seeker’s search query with available benefits.

Input

Search payload received from seeker (BAP).

Processing

The BPP queries its benefit catalog and prepares a list of benefits with metadata such as eligibility criteria, documents required, sponsoring entities, etc.

Output

A structured list of available benefits with details:

  • Benefit title, description, and validity

  • Eligibility criteria

  • Required documents

  • Sponsoring entities

Endpoint

POST https://<BAP-URI>/on_search

Sample Request

To which you need to respond as:

Sample Response

2. on_select API – Return Benefit Details

When the beneficiary selects a specific benefit, the BAP sends a /select call to the network. The BPP processes this and responds using /on_select, returning detailed information for the selected benefit.

Purpose

Provide full details of a specific selected benefit.

Input

Seeker’s selected benefit_id.

Processing

  • Fetch the full benefit schema (including form fields, eligibility, required docs).

  • Structure this as a JSON schema for the BAP to render its internal form.

  • Include metadata for each field (name, label, required/optional, validation rules, etc.).

  • Attach eligibility rules and document proof requirements.

Output

  • Detailed benefit information (title, description, duration, eligibility)

  • JSON-based form schema (field definitions, validation, document proofs)

  • No iframe/form URL required — form is dynamically built by the BAP using this schema.

Endpoint

POST https://<BAP-URI>/on_select

Sample Request

To which you need to respond as:

Sample Response

3. on_init API – Initialize Application

When the beneficiary decides to apply, the BAP sends a /init request to initialize the application. Before sending the request, the BAP:

  • Creates an application record in its DB.

  • Generates a unique bap_application_id.

  • Associates the record with transaction_id, bpp_id, and benefit_id.

The BPP receives this /init call and processes it.

Purpose

Initialize and register a new application session between BAP and BPP.

Input

  • bap_application_id

  • transaction_id

  • Benefit ID

  • User profile data (may include derived fields from Verifiable Credentials)

Processing

  1. BPP stores the bap_application_id, transaction_id, bap_id, and user_id in its DB.

  2. Creates an internal application record (status: initiated).

  3. Optionally uses Eligibility SDK to pre-check if user satisfies eligibility rules.

Output

  • order_id generated by BPP.

  • Initial acknowledgment and metadata for the next step in application submission.

Endpoint

POST https://<BAP-URI>/on_init

Sample Request

To which you need to respond as:

Sample Response

4. on_confirm API – Finalize Application

Once the user has filled out the form on the BAP side, the BAP sends the completed application data — including Verifiable Credentials (VCs) — directly in the /confirm API call. The BPP validates the incoming data and finalizes the application.

Purpose

Confirm and persist a completed benefit application.

Input

  • Completed application payload:

    • User details

    • Application data (form fields)

    • vc_documents (array of VCs and proofs)

    • bap_application_id, transaction_id

Processing

  1. Verify VCs using Verification SDK to ensure authenticity and integrity.

  2. Store the application data in BPP’s system (status: received).

  3. Optionally trigger internal verification, approval, or workflow processes.

Output

  • Acknowledgment with a unique bpp_application_id (generated by BPP).

  • Application acceptance confirmation and remarks if any.

Endpoint

POST https://<BAP-URI>/on_confirm

Sample Request

To which you need to respond as:

Sample Response

5. on_update API – Update Application

If the beneficiary modifies or resubmits the application (for example, after corrections), the BAP uses the /update API. This allows seamless update of application data without restarting the whole process.

Purpose

Handle application resubmission or data modification.

Input

  • Updated application payload (fields, documents, or corrected details)

  • transaction_id (same as initial transaction)

  • bap_application_id

Processing

  • BPP locates the corresponding application record using transaction_id.

  • Updates the stored application data.

  • Retains linkage to bap_application_id and bpp_application_id.

Output

  • Acknowledgment of successful update.

  • Optional remarks or next steps.

Endpoint

POST https://<BAP-URI>/on_update

Sample Request

To which you need to respond as:

Sample Response

6. on_status API – Application Status Tracking

The BAP periodically queries the application’s current state using /status. The BPP responds using /on_status, reporting the current progress.

Purpose

Provide real-time status of an application.

Input

  • transaction_id or bap_application_id

  • Optional user or application reference data

Processing

  • Fetch the current state of the application in the BPP DB.

  • Append remarks or last update details.

Output

  • Application status (e.g., in-progress, approved, rejected, needs-correction)

  • Application identifiers (bap_application_id, bpp_application_id, order_id)

  • Remarks, timestamps, and tracking information.

Endpoint

POST https://<BAP-URI>/on_status

Sample Request

To which you need to respond as:

Sample Response

🔑 Important Implementation Notes

  • Unique message_id per request: Every network call must have a new message_id. Example: /search, /select, /init, /confirm, and /status each use a distinct one.

  • Consistent transaction_id per application: For all subsequent API calls (init, confirm, update, status), reuse the same transaction_id received in the /select response. This enables consistent application tracking.

  • Application Tracking on BAP & BPP:

    • BAP stores: bap_application_id, bpp_id, benefit_id, transaction_id, and bpp_application_id (when received).

    • BPP stores: bap_application_id, transaction_id, bap_id, user_id, and bpp_application_id.

PreviousEnable Telemetry in Protocol Servers (BAP & BPP)NextSuggested Form Structure for xInput

Last updated