Beneficiary App Integration

This document is a guide for integrating Beneficiary Apps as network participants on the UBI Network. Beneficiaries are responsible for fetching benefits, sending applications to providers, validating them using eligibility and verification SDKs if needed, and showing the status of the applications.

Sequence of API Calls

  1. Search API (/search → /on_search) The BAP (Seeker) initiates a search request to discover available benefits or schemes. This request goes through the UBI Network to the BPPs (Providers). Each BPP responds with an /on_search call containing the list of benefits they offer, along with metadata such as title, description, eligibility, sponsoring entities, and required documents.

  2. Select API (/select → /on_select) When the user selects a benefit to view or apply, the BAP sends a /select call to the UBI Network. The BPP responds with an /on_select call that includes detailed benefit information and the form schema. This schema defines the form fields, types, validation rules, and required documents. Based on this schema, the BAP generates the application form dynamically (no iframe approach).

  3. Init API (/init → /on_init) Once the user confirms they want to apply for a particular benefit, the BAP first creates an application record in its own database. This record includes a newly generated bap_application_id, along with the transaction_id, benefit_id, and bpp_id. The BAP then sends an /init request containing the applicant’s profile data (from Verifiable Credentials) and the generated bap_application_id. The BPP processes this request and returns an /on_init response, which includes a confirmation and a unique order_id generated on the BPP side. The BAP should update its application record with the returned order_id.

  4. Confirm API (/confirm → /on_confirm) After the user completes the form and attaches all required Verifiable Credentials (VCs), the BAP sends a /confirm request. The payload contains the user data, document data, and VC information. The BPP validates the received data and credentials using the Verification SDK, ensuring that the VCs are authentic and untampered. The BPP then responds with /on_confirm, acknowledging successful application submission and returning a bpp_application_id. The BAP updates its application record with this bpp_application_id and marks the status as “Submitted”.

  5. Status API (/status → /on_status) The BAP can periodically query the application status using the /status API. The request includes the transaction_id or bap_application_id for the given application. The BPP looks up the application on its end and responds with /on_status, containing the current state such as Pending, Approved, Rejected, or Needs Update. The BAP updates its local database and displays the current status to the user.

Integration Flow

  1. The user searches for benefits in the Beneficiary App (BAP). The BAP sends a /search request through the UBI Network, and each BPP responds with /on_search, listing available benefits.

  2. The user selects one benefit from the list. The BAP sends a /select call to retrieve detailed benefit information and the dynamic form schema from the BPP’s /on_select response.

  3. The BAP creates an application record locally before initiating the application. It generates a unique bap_application_id and associates it with the transaction_id, bpp_id, and benefit_id.

  4. The BAP calls /init to initialize the application on the BPP side. The BPP responds with /on_init, providing confirmation and an order_id, which the BAP stores in its record.

  5. The BAP sends the filled application data and Verifiable Credentials in the /confirm request. The BPP verifies the received credentials and application data using the Verification SDK, then responds with /on_confirm, returning the bpp_application_id.

  6. The BAP stores this bpp_application_id and marks the application as “Submitted”. Any further modifications or updates to the application can be done through an /update API (if supported).

  7. To track application progress, the BAP periodically sends /status requests. The BPP responds with /on_status, returning the latest application state and remarks. The BAP updates the local record and reflects the current status in the UI.

Flow Diagram

API Integration Details

1. Search API - Find Available Benefits

Endpoint: POST https://dev-bap.ubi.com/client/search

Purpose: Search for available benefits on the UBI network

Request Structure:

Sample Request

You will get the response to this as:

Sample Response

⚠️ Important Note on transaction_id and message_id Usage

In all transaction APIs across the UBI Network (e.g., search, select, init, confirm, status), both transaction_id and message_id are critical for ensuring traceability and uniqueness of requests.

  • message_id

    • Must be unique for every individual API call.

    • Used to track and identify each message/request independently.

    • Helps in debugging and ensuring idempotency at the network level.

  • transaction_id

    • Represents the entire lifecycle of a single application or transaction.

    • Generated by the Seeker (BAP) after a successful select response from the Provider (BPP).

    • Must remain constant across all subsequent API calls related to that transaction — i.e. init, confirm, and status.

    • Enables both BAP and BPP to track, resubmit, or update the same application consistently.

The Seeker app should:

  • Capture and persist the transaction_id received post-select API response.

  • Store it in the local database along with relevant application metadata.

  • Reuse the same transaction_id for subsequent API calls related to that benefit application.

This ensures the entire flow — from initiation to confirmation and status tracking — can be reliably linked and managed across the network.

2. Select API - Get Benefit Details

Endpoint: POST https://your-bap.client.com/api/select

Purpose: Get detailed information about a specific benefit

Headers:

Request Structure:

Sample Request

You will get the response to this as:

Sample Response

3. Init API – Start Application Process

Endpoint: POST https://your-bap.client.com/api/init

Purpose: Initialize the application process for a selected benefit and create a local application record on the BAP side before submitting data to the network.

Process Overview

When the user decides to apply for a selected benefit:

  1. The Beneficiary App (BAP) creates a new application record in its database.

    • Generates a unique bap_application_id.

    • Stores transaction_id, benefit_id, bpp_id, and user reference.

    • Sets the application state to initiated.

  2. The BAP sends an /init API request to the UBI network, which forwards it to the corresponding BPP.

  3. The BPP validates the request and returns an /on_init response with an order_id.

  4. The BAP updates its local record with this order_id.

Request Structure:

Sample Request

You will get the response to this as:

Sample Response

Notes

  • The bap_application_id generated by the BAP must be unique per application and stored for tracking.

  • The transaction_id must remain the same across all APIs (init, confirm, status, update) for that application.

  • The BPP will generate its own order_id or bpp_application_id, which should be updated in the BAP database once received.

4. Confirm API – Submit Application

Endpoint: POST https://your-bap.client.com/api/confirm

Purpose: Submit the completed application with user data and attached Verifiable Credentials (VCs) to the UBI network for provider verification and acknowledgment.

Process Overview

  1. Once the user completes the form, the BAP compiles all input data and associated VCs.

  2. The BAP sends this data using the /confirm API call.

  3. The BPP validates the submitted data and uses the Verification SDK to verify that all VCs are authentic and untampered.

  4. The BPP responds with /on_confirm, providing a confirmation acknowledgment and the generated bpp_application_id.

  5. The BAP updates its local record with the new ID and status.

Request Structure:

Sample Request

You will get the response to this as:

Sample Response

5. Update API – Modify / Resubmit Application

When to use Use /update when a beneficiary (or BAP) needs to modify an existing application (corrections, additional documents, resubmission after rejection, or to add missing VCs). The update flow avoids creating a new transaction; it updates the existing application tied to the same transaction_id.

Endpoint: POST https://your-bap.client.com/api/update

Purpose: Update an existing application record on the Provider side without restarting the application lifecycle.

Key Rules

  • Use the same transaction_id and bap_application_id as the original application.

  • message_id must be unique for this update request.

  • If the BPP re-runs verification/eligibility, it should mention that in its /on_update response.

  • BPP must merge or version the incoming updates and persist the changes.

BAP-side Process

  1. User edits application in BAP UI.

  2. BAP updates its local DB (optional draft) and calls /update with transaction_id + bap_application_id + updated fields + VCs.

  3. BPP receives /update, validates, updates its DB record, and responds with /on_update.

  4. BAP updates its local record based on /on_update.

Request Structure:

Sample Request

You will get the response to this as:

Sample Response

6. Status API – Track Application

Endpoint: POST https://your-bap.client.com/api/status

Purpose: The Status API allows the BAP to query the current state of a previously submitted application. This is typically used by the beneficiary app to check whether their application is pending, approved, rejected, or requires additional action.

Request Structure:

Sample Request

You will get the response to this as:

Sample Response

Notes

  • transaction_id remains the single linking identifier across init, confirm, update, status.

  • BAP should persist the returned bpp_application_id and order_id (from init) for later reconciliation.

PreviousBAP - Installing Protocol ServerNextBeneficiary Toaster

Last updated