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
on_search → Respond to beneficiary search with available benefits.
on_select → Confirm selected benefit details.
on_init → Verify eligibility and initialize application.
on_update → Update application if needed.
on_confirm → Approve or reject application.
on_status → Check application status.
Integration Flow
Receive Search Request (from Seeker via UBI Network).
Respond with Benefit Catalog (
on_search).Handle Selection (
on_select) → return details.Initialize Application (
on_init) → validate user + eligibility + docs.Update Application (
on_update) → update or resubmit the application.
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
{
"context": {
"domain": "ubi:financial-support",
"action": "search",
"version": "1.1.0",
"bap_id": "bap.client.com",
"bap_uri": "https://bap.client.com/",
"bpp_id": "bpp.client.com",
"bpp_uri": "https://bpp.client.com/",
"ttl": "PT10M",
"transaction_id": "unique-transaction-id",
"message_id": "unique-message-id",
"timestamp": "2025-09-15T10:31:53.234Z",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
}
},
"message": {
"intent": {
"item": {
"descriptor": {}
}
}
}
}To which you need to respond as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "search",
"timestamp": "2025-09-22T16:30:37.935Z",
"message_id": "c163c21a-399d-431c-adc0-de23e521e87c",
"transaction_id": "49a21db0-8359-4675-a991-ef588a8edc8d",
"domain": "ubi:financial-support",
"version": "1.1.0",
"bap_id": "dev-bap.ubi.com",
"bap_uri": "https://dev-bap.ubi.com",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bpp_id": "dev-bpp.ubi.com",
"bpp_uri": "https://dev-bpp.ubi.com"
},
"responses": [
{
"context": {
"domain": "ubi:financial-support",
"action": "on_search",
"version": "1.1.0",
"bpp_id": "dev-bpp.ubi.com",
"bpp_uri": "https://dev-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-bap.ubi.com",
"bap_uri": "https://dev-bap.ubi.com",
"transaction_id": "49a21db0-8359-4675-a991-ef588a8edc8d",
"message_id": "c163c21a-399d-431c-adc0-de23e521e87c",
"ttl": "PT10M",
"timestamp": "2025-09-22T16:30:40.501Z"
},
"message": {
"catalog": {
"descriptor": {
"name": "dev-bpp.ubi.com"
},
"providers": [
{
"id": "dev-bpp.ubi.com",
"descriptor": {
"name": "Scholarlify",
"short_desc": "Multiple scholarships offered",
"images": []
},
"categories": [
{
"id": "CAT_SCHOLARSHIP",
"descriptor": {
"code": "scholarship",
"name": "Scholarship"
}
}
],
"fulfillments": [
{
"id": "FULFILL_UNIFIED",
"tracking": false
}
],
"locations": [
{
"id": "L1",
"city": {
"name": "Pune",
"code": "std:020"
},
"state": {
"name": "Maharashtra",
"code": "MH"
}
}
],
"items": [
{
"id": "ju0flxeav1c9anqdfnoh2kje",
"descriptor": {
"name": "Arjuna JEE Scholarship",
"long_desc": "The scholarship intends to provide financial and academic assistance to students interested in appearing for JEE in 2026. This scholarship provides free program access to students who are meritorious and have financial barriers to access quality courses to support their learning."
},
"price": {
"currency": "INR",
"value": "0"
},
"time": {
"range": {
"start": "2025-06-01T00:00:00.000Z",
"end": "2025-10-31T00:00:00.000Z"
}
},
"rateable": false,
"tags": [
{
"display": true,
"descriptor": {
"code": "eligibility",
"name": "Eligibility"
},
"list": [
{
"descriptor": {
"code": "previousYearMarks",
"name": "Academic - previousYearMarks",
"short_desc": "The applicant must have 60% or more marks in previous class"
},
"value": "{\"id\":378,\"evidence\":\"previousYearMarks\",\"type\":\"academic\",\"description\":\"The applicant must have 60% or more marks in previous class\",\"allowedProofs\":[\"marksheet\"],\"criteria\":{\"id\":378,\"name\":\"previousYearMarks\",\"condition\":\"greater than equals\",\"conditionValues\":[\"60\"]}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "required-docs",
"name": "Required Documents"
},
"list": [
{
"descriptor": {
"code": "mandatory-doc",
"name": "Mandatory Document"
},
"value": "{\"id\":462,\"documentType\":\"marksProof\",\"isRequired\":true,\"allowedProofs\":[\"marksheet\"]}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "benefits",
"name": "Benefits"
},
"list": [
{
"descriptor": {
"code": "financial",
"name": "Free Program Access"
},
"value": "{\"__component\":\"benefit.non-monetary-benefit\",\"id\":72,\"title\":\"Free Program Access\",\"type\":\"non-monetary\",\"description\":\"This scholarship provides free program access to students who are meritorious and have financial barriers to access quality courses to support their learning.\",\"description_md\":null}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "sponsoringEntities",
"name": "Sponsoring Entities"
},
"list": [
{
"descriptor": {
"code": "sponsoringEntities",
"name": "Entities Sponsoring Benefits"
},
"value": "{\"id\":184,\"name\":\"XYZ Foundation\",\"type\":\"private\",\"department\":\"Private\",\"sponsorShare\":\"100\",\"address\":{\"id\":366,\"street\":\"Koramangala\",\"city\":\"Bangalore\",\"state\":\"Karnataka\",\"postalCode\":\"560099\"},\"contactInfo\":{\"id\":366,\"phoneNumber\":\"181894546\",\"email\":\"info@XYZ.in\"}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "applicationForm",
"name": "Application Form"
},
"list": [
{
"descriptor": {
"code": "applicationFormField-firstName",
"name": "Application Form Field - First Name"
},
"value": "{\"id\":1859,\"name\":\"firstName\",\"type\":\"text\",\"label\":\"First Name\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-middleName",
"name": "Application Form Field - MIddle Name"
},
"value": "{\"id\":1860,\"name\":\"middleName\",\"type\":\"text\",\"label\":\"MIddle Name\",\"required\":false,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-lastName",
"name": "Application Form Field - Last Name"
},
"value": "{\"id\":1861,\"name\":\"lastName\",\"type\":\"text\",\"label\":\"Last Name\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-class",
"name": "Application Form Field - Current Class"
},
"value": "{\"id\":1863,\"name\":\"class\",\"type\":\"select\",\"label\":\"Current Class\",\"required\":true,\"multiple\":null,\"options\":[{\"id\":1973,\"label\":\"9\",\"value\":\"9\"},{\"id\":1974,\"label\":\"10\",\"value\":\"10\"},{\"id\":1975,\"label\":\"11\",\"value\":\"11\"}],\"fieldsGroupName\":\"academicDetails\",\"fieldsGroupLabel\":\"Academic Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-previousYearMarks",
"name": "Application Form Field - Marks in Previous Class"
},
"value": "{\"id\":1862,\"name\":\"previousYearMarks\",\"type\":\"text\",\"label\":\"Marks in Previous Class\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"academicDetails\",\"fieldsGroupLabel\":\"Academic Details\"}",
"display": true
}
]
}
]
},
{
"id": "fju0zw9czj40ngmdarz3ufbc",
"descriptor": {
"name": "Pragati Balika Vidya Grant",
"long_desc": "This scheme aims to support girls from rural areas to continue their education by providing financial help"
},
"price": {
"currency": "INR",
"value": "1200"
},
"time": {
"range": {
"start": "2025-06-01T00:00:00.000Z",
"end": "2025-12-31T00:00:00.000Z"
}
},
"rateable": false,
"tags": [
{
"display": true,
"descriptor": {
"code": "eligibility",
"name": "Eligibility"
},
"list": [
{
"descriptor": {
"code": "annualIncome",
"name": "Economic - annualIncome",
"short_desc": "The Total Annual income of parents/guardians of the applicant must not exceed ₹1 Lakh per Annum"
},
"value": "{\"id\":206,\"evidence\":\"annualIncome\",\"type\":\"economic\",\"description\":\"The Total Annual income of parents/guardians of the applicant must not exceed ₹1 Lakh per Annum\",\"allowedProofs\":[\"incomeCertificate\"],\"criteria\":{\"id\":206,\"name\":\"annualIncome\",\"condition\":\"less than equals\",\"conditionValues\":[\"100000\"]}}",
"display": true
},
{
"descriptor": {
"code": "gender",
"name": "Health - gender",
"short_desc": "Only applicable for female genders."
},
"value": "{\"id\":207,\"evidence\":\"gender\",\"type\":\"health\",\"description\":\"Only applicable for female genders.\",\"allowedProofs\":[\"birthCertificate\"],\"criteria\":{\"id\":207,\"name\":\"gender\",\"condition\":\"equals\",\"conditionValues\":[\"female\",\"Female\"]}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "required-docs",
"name": "Required Documents"
},
"list": [
{
"descriptor": {
"code": "mandatory-doc",
"name": "Mandatory Document"
},
"value": "{\"id\":261,\"documentType\":\"incomeProof\",\"isRequired\":true,\"allowedProofs\":[\"incomeCertificate\"]}",
"display": true
},
{
"descriptor": {
"code": "mandatory-doc",
"name": "Mandatory Document"
},
"value": "{\"id\":262,\"documentType\":\"idProof\",\"isRequired\":true,\"allowedProofs\":[\"birthCertificate\"]}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "benefits",
"name": "Benefits"
},
"list": [
{
"descriptor": {
"code": "financial",
"name": "Scholarship Amount"
},
"value": "{\"__component\":\"benefit.financial-benefit\",\"id\":155,\"title\":\"Scholarship Amount\",\"type\":\"financial\",\"description\":\"₹1,200 per month for 8 months\",\"description_md\":null,\"minValue\":null,\"maxValue\":null}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "sponsoringEntities",
"name": "Sponsoring Entities"
},
"list": [
{
"descriptor": {
"code": "sponsoringEntities",
"name": "Entities Sponsoring Benefits"
},
"value": "{\"id\":91,\"name\":\"The Department of Women and Child Development\",\"type\":\"government\",\"department\":\"5th Floor, Antyodaya Bhawan, CGO Complex, Lodhi Road\",\"sponsorShare\":\"100\",\"address\":{\"id\":182,\"street\":\"5th Floor, Antyodaya Bhawan, CGO Complex, Lodhi Road\",\"city\":\"New Delhi\",\"state\":\"Delhi\",\"postalCode\":\"110003\"},\"contactInfo\":{\"id\":182,\"phoneNumber\":\"24365019\",\"email\":\"depwd@gov.in\"}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "applicationForm",
"name": "Application Form"
},
"list": [
{
"descriptor": {
"code": "applicationFormField-firstName",
"name": "Application Form Field - First Name"
},
"value": "{\"id\":1075,\"name\":\"firstName\",\"type\":\"text\",\"label\":\"First Name\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-middleName",
"name": "Application Form Field - Middle Name"
},
"value": "{\"id\":1076,\"name\":\"middleName\",\"type\":\"text\",\"label\":\"Middle Name\",\"required\":false,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-lastName",
"name": "Application Form Field - Last Name"
},
"value": "{\"id\":1077,\"name\":\"lastName\",\"type\":\"text\",\"label\":\"Last Name\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-gender",
"name": "Application Form Field - Gender"
},
"value": "{\"id\":1078,\"name\":\"gender\",\"type\":\"select\",\"label\":\"Gender\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalDetails\",\"fieldsGroupLabel\":\"Personal Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-annualIncome",
"name": "Application Form Field - Annual Income"
},
"value": "{\"id\":1079,\"name\":\"annualIncome\",\"type\":\"text\",\"label\":\"Annual Income\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"financialDetails\",\"fieldsGroupLabel\":\"Financial Details\"}",
"display": true
}
]
}
]
}
]
}
]
}
}
}
]
}
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
{
"context": {
"domain": "ubi:financial-support",
"action": "select",
"timestamp": "2023-08-02T07:21:58.448Z",
"ttl": "PT10M",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"bpp_id": "dev-uba-bpp.ubi.com",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "02dd2675-fa38-4617-8d6a-5b073d845f05",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
}
},
"message": {
"order": {
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u"
}
],
"provider": {
"id": "dev-uba-bpp.ubi.com"
}
}
}
}To which you need to respond as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "select",
"timestamp": "2025-10-14T09:44:05.640Z",
"message_id": "02dd2675-fa38-4617-8d6a-5b073d845f05",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"domain": "ubi:financial-support",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com"
},
"responses": [
{
"context": {
"domain": "ubi:financial-support",
"action": "on_select",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "02dd2675-fa38-4617-8d6a-5b073d845f05",
"ttl": "PT10M",
"timestamp": "2025-10-14T09:44:08.481Z"
},
"message": {
"catalog": {
"descriptor": {
"name": "dev-uba-bpp.ubi.com"
},
"providers": [
{
"id": "dev-uba-bpp.ubi.com",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Multiple scholarships offered",
"images": []
},
"categories": [
{
"id": "CAT_SCHOLARSHIP",
"descriptor": {
"code": "scholarship",
"name": "Scholarship"
}
}
],
"fulfillments": [
{
"id": "FULFILL_UNIFIED",
"tracking": false
}
],
"locations": [
{
"id": "L1",
"city": {
"name": "Pune",
"code": "std:020"
},
"state": {
"name": "Maharashtra",
"code": "MH"
}
}
],
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u",
"descriptor": {
"name": "[PM] Piramal Prematric scholarship",
"long_desc": "This scheme aims to financially assist girl students pursuing education in Class 9 & 10. It covers tuition, maintenance allowance, and additional grants to support education continuity and skill development"
},
"price": {
"currency": "INR",
"value": "5500"
},
"time": {
"range": {
"start": "2025-08-21T00:00:00.000Z",
"end": "2025-12-31T00:00:00.000Z"
}
},
"rateable": false,
"tags": [
{
"display": true,
"descriptor": {
"code": "eligibility",
"name": "Eligibility"
},
"list": [
{
"descriptor": {
"code": "class",
"name": "Academic - class",
"short_desc": "Must be pursuing pre-matric qualification (Class 9 & 10)"
},
"value": "{\"evidence\":\"class\",\"type\":\"academic\",\"description\":\"Must be pursuing pre-matric qualification (Class 9 & 10)\",\"allowedProofs\":[\"marksheet\",\"enrollmentCertificate\"],\"criteria\":{\"name\":\"class\",\"condition\":\"in\",\"conditionValues\":[\"9\",\"10\"]}}",
"display": true
},
{
"descriptor": {
"code": "annualIncome",
"name": "Economic - annualIncome",
"short_desc": "The Total Annual income of parents/guardians of the applicant must not exceed ₹2.5 Lakh per Annum"
},
"value": "{\"evidence\":\"annualIncome\",\"type\":\"economic\",\"description\":\"The Total Annual income of parents/guardians of the applicant must not exceed ₹2.5 Lakh per Annum\",\"allowedProofs\":[\"incomeCertificate\"],\"criteria\":{\"name\":\"annualIncome\",\"condition\":\"less than equals\",\"conditionValues\":[\"250000\"]}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "required-docs",
"name": "Required Documents"
},
"list": [
{
"descriptor": {
"code": "mandatory-doc",
"name": "Mandatory Document"
},
"value": "{\"documentType\":\"incomeProof\",\"isRequired\":true,\"allowedProofs\":[\"incomeCertificate\"]}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "benefits",
"name": "Benefits"
},
"list": [
{
"descriptor": {
"code": "financial",
"name": "Tuition Fee Support"
},
"value": "{\"title\":\"Tuition Fee Support\",\"type\":\"financial\",\"description\":\"₹5500 per year\",\"description_md\":null,\"minValue\":null,\"maxValue\":\"5500\"}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "sponsoringEntities",
"name": "Sponsoring Entities"
},
"list": [
{
"descriptor": {
"code": "sponsoringEntities",
"name": "Entities Sponsoring Benefits"
},
"value": "{\"name\":\"Piramal\",\"type\":\"private\",\"department\":\"Ministry\",\"sponsorShare\":\"100\",\"address\":{\"street\":\"12\",\"city\":\"Delhi\",\"state\":\"Delhi\",\"postalCode\":\"110000\"},\"contactInfo\":{\"phoneNumber\":\"06234567890\",\"email\":\"sudha.kothari@gandhifellowship.org\"}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "applicationForm",
"name": "Application Form"
},
"list": [
{
"descriptor": {
"code": "applicationFormField-annualIncome",
"name": "Application Form Field - Annual Income"
},
"value": "{\"name\":\"annualIncome\",\"type\":\"text\",\"label\":\"Annual Income\",\"required\":true,\"multiple\":false,\"options\":[],\"fieldsGroupName\":\"financialDetails\",\"fieldsGroupLabel\":\"Financial Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-firstName",
"name": "Application Form Field - First Name"
},
"value": "{\"name\":\"firstName\",\"type\":\"text\",\"label\":\"First Name\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalInfo \",\"fieldsGroupLabel\":\"Personal Info\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-lastName",
"name": "Application Form Field - Last Name"
},
"value": "{\"name\":\"lastName\",\"type\":\"text\",\"label\":\"Last Name\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"personalInfo \",\"fieldsGroupLabel\":\"Personal Info\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-gender",
"name": "Application Form Field - Gender"
},
"value": "{\"name\":\"gender\",\"type\":\"select\",\"label\":\"Gender\",\"required\":true,\"multiple\":null,\"options\":[{\"label\":\"Male\",\"value\":\"male\"},{\"label\":\"Female\",\"value\":\"female\"}],\"fieldsGroupName\":\"personalInfo \",\"fieldsGroupLabel\":\"Personal Info\"}",
"display": true
}
]
}
]
}
]
}
]
}
}
}
]
}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, andbenefit_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_idtransaction_idBenefit ID
User profile data (may include derived fields from Verifiable Credentials)
Processing
BPP stores the
bap_application_id,transaction_id,bap_id, anduser_idin its DB.Creates an internal application record (status: initiated).
Optionally uses Eligibility SDK to pre-check if user satisfies eligibility rules.
Output
order_idgenerated by BPP.Initial acknowledgment and metadata for the next step in application submission.
Endpoint
POST https://<BAP-URI>/on_init
Sample Request
{
"context": {
"domain": "ubi:financial-support",
"action": "init",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "02dd2675-fa38-4617-8d6a-5b073d845f05",
"ttl": "PT10M",
"timestamp": "2025-10-14T09:44:48.529Z"
},
"message": {
"order": {
"provider": {
"id": "dev-uba-bpp.ubi.com"
},
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u"
}
],
"fulfillments": [
{
"customer": {
"applicationData": {
"annualIncome": "50000",
"firstName": "Rajnish",
"lastName": "D",
"gender": "male",
"vc_documents": [
{
"document_submission_reason": "[\"class\"]",
"document_type": "marksProof",
"document_subtype": "marksheet",
"document_format": "json",
"document_imported_from": "QR Code",
"document_content": "base64, BASE64_CONTENT_FOR_VC"
},
{
"document_submission_reason": "[\"annualIncome\"]",
"document_type": "incomeProof",
"document_subtype": "incomeCertificate",
"document_format": "json",
"document_imported_from": "QR Code",
"document_content": "base64,BASE64_CONTENT_FOR_VC"
}
],
"bap_application_id": "46c791e0-51f3-4c86-9ade-c2fecfb609c2"
}
}
}
]
}
}
}To which you need to respond as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "init",
"timestamp": "2025-10-14T09:44:48.568Z",
"message_id": "02dd2675-fa38-4617-8d6a-5b073d845f05",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"domain": "ubi:financial-support",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com"
},
"responses": [
{
"context": {
"domain": "ubi:financial-support",
"action": "on_init",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "02dd2675-fa38-4617-8d6a-5b073d845f05",
"ttl": "PT10M",
"timestamp": "2025-10-14T09:44:51.438Z"
},
"message": {
"order": {
"providers": [
{
"id": "dev-uba-bpp.ubi.com",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Multiple scholarships offered",
"images": []
},
"locations": [
{
"id": "L1",
"city": {
"name": "Pune",
"code": "std:020"
},
"state": {
"name": "Maharashtra",
"code": "MH"
}
}
],
"categories": [
{
"id": "CAT_SCHOLARSHIP",
"descriptor": {
"code": "scholarship",
"name": "Scholarship"
}
}
]
}
],
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u",
"descriptor": {
"name": "[PM] Piramal Prematric scholarship",
"long_desc": "This scheme aims to financially assist girl students pursuing education in Class 9 & 10. It covers tuition, maintenance allowance, and additional grants to support education continuity and skill development"
},
"price": {
"currency": "INR",
"value": "5500"
},
"time": {
"range": {
"start": "2025-08-21T00:00:00.000Z",
"end": "2025-12-31T00:00:00.000Z"
}
},
"rateable": false,
"applicationId": 223,
"transactionId": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf"
}
]
}
}
}
]
}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
Verify VCs using Verification SDK to ensure authenticity and integrity.
Store the application data in BPP’s system (status: received).
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
{
"context": {
"domain": "ubi:financial-support",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"action": "confirm",
"timestamp": "2025-10-14T09:44:08.481Z",
"ttl": "PT10M",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"message_id": "dc14b7d6-1cd9-44ce-8d5e-f3d55bf61d04",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf"
},
"message": {
"order": {
"provider": {
"id": ""
},
"items": [
{
"id": "223"
}
],
"billing": {
"name": "Manjunath",
"organization": {},
"address": "No 27, XYZ Lane, etc",
"phone": "+91-9999999999"
},
"fulfillments": [
{
"customer": {},
"tags": [
{
"descriptor": {},
"value": "PNB"
}
]
}
],
"payment": [
{
"params": {}
}
]
}
}
}To which you need to respond as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "confirm",
"timestamp": "2025-10-14T09:44:53.255Z",
"message_id": "dc14b7d6-1cd9-44ce-8d5e-f3d55bf61d04",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"domain": "ubi:financial-support",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com"
},
"responses": [
{
"message": {
"order": {
"provider": {
"id": "dev-uba-bpp.tekdinext.com",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Multiple scholarships offered",
"images": []
},
"locations": [
{
"id": "L1",
"city": {
"name": "Pune",
"code": "std:020"
},
"state": {
"name": "Maharashtra",
"code": "MH"
}
}
]
},
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u",
"descriptor": {
"name": "[PM] Piramal Prematric scholarship",
"long_desc": "This scheme aims to financially assist girl students pursuing education in Class 9 & 10. It covers tuition, maintenance allowance, and additional grants to support education continuity and skill development"
},
"price": {
"currency": "INR",
"value": "5500"
},
"time": {
"range": {
"start": "2025-08-21T00:00:00.000Z",
"end": "2025-12-31T00:00:00.000Z"
}
},
"rateable": false
}
],
"id": "TLEXP_F0463B08_1760435094213"
}
},
"context": {
"domain": "ubi:financial-support",
"action": "on_confirm",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "dc14b7d6-1cd9-44ce-8d5e-f3d55bf61d04",
"ttl": "PT10M",
"timestamp": "2025-10-14T09:44:56.238Z"
}
}
]
}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_idandbpp_application_id.
Output
Acknowledgment of successful update.
Optional remarks or next steps.
Endpoint
POST https://<BAP-URI>/on_update
Sample Request
{
"context": {
"domain": "ubi:financial-support",
"action": "update",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "2a8de651-b7a8-4645-be6b-59e6ffed71b2",
"ttl": "PT10M",
"timestamp": "2025-10-14T09:46:55.719Z"
},
"message": {
"update_target": "fulfillments",
"order": {
"provider": {
"id": "dev-uba-bpp.ubi.com"
},
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u"
}
],
"fulfillments": [
{
"customer": {
"applicationData": {
"annualIncome": "50000",
"firstName": "Rajnish",
"lastName": "D",
"gender": "male",
"vc_documents": [
{
"document_submission_reason": "[\"class\"]",
"document_type": "marksProof",
"document_subtype": "marksheet",
"document_format": "json",
"document_imported_from": "QR Code",
"document_content": "base64, BASE_64_ENCODED_DOCUMENT_CONTENT"
},
{
"document_submission_reason": "[\"annualIncome\"]",
"document_type": "incomeProof",
"document_subtype": "incomeCertificate",
"document_format": "json",
"document_imported_from": "QR Code",
"document_content": "base64, BASE_64_ENCODED_DOCUMENT_CONTENT"
}
],
"orderId": "223"
}
}
}
]
}
}
}To which you need to respond as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "update",
"timestamp": "2025-10-14T09:46:55.760Z",
"message_id": "2a8de651-b7a8-4645-be6b-59e6ffed71b2",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"domain": "ubi:financial-support",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com"
},
"responses": [
{
"context": {
"domain": "ubi:financial-support",
"action": "on_update",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf",
"message_id": "2a8de651-b7a8-4645-be6b-59e6ffed71b2",
"ttl": "PT10M",
"timestamp": "2025-10-14T09:46:58.789Z"
},
"message": {
"order": {
"providers": [
{
"id": "dev-uba-bpp.ubi.com",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Multiple scholarships offered",
"images": []
},
"locations": [
{
"id": "L1",
"city": {
"name": "Pune",
"code": "std:020"
},
"state": {
"name": "Maharashtra",
"code": "MH"
}
}
],
"categories": [
{
"id": "CAT_SCHOLARSHIP",
"descriptor": {
"code": "scholarship",
"name": "Scholarship"
}
}
]
}
],
"items": [
{
"id": "fk89zirqlkcqd2pla5ldzz8u",
"descriptor": {
"name": "[PM] Piramal Prematric scholarship",
"long_desc": "This scheme aims to financially assist girl students pursuing education in Class 9 & 10. It covers tuition, maintenance allowance, and additional grants to support education continuity and skill development"
},
"price": {
"currency": "INR",
"value": "5500"
},
"time": {
"range": {
"start": "2025-08-21T00:00:00.000Z",
"end": "2025-12-31T00:00:00.000Z"
}
},
"rateable": false,
"applicationId": "223",
"transactionId": "3f5daa48-3c66-453b-b63a-c5aa052e7cdf"
}
]
}
}
}
]
}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_idorbap_application_idOptional 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
{
"context": {
"domain": "ubi:financial-support",
"action": "status",
"timestamp": "2025-09-24T05:18:01.207Z",
"ttl": "PT10M",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com/",
"transaction_id": "20bd48e9-153b-4653-a960-29a360232633",
"message_id": "bcaea789-370a-4287-8721-422ce6f63442",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
}
},
"message": {
"order_id": "TLEXP_BE0E180D_1758547273958"
}
}To which you need to respond as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "status",
"timestamp": "2025-09-24T05:24:47.748Z",
"message_id": "bcaea789-370a-4287-8721-422ce6f63442",
"transaction_id": "20bd48e9-153b-4653-a960-29a360232633",
"domain": "ubi:financial-support",
"version": "1.1.0",
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com/"
},
"responses": [
{
"message": {
"order": {
"provider": {
"id": "dev-uba-bpp.tekdinext.com",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Multiple scholarships offered",
"images": []
}
},
"items": [
{
"id": "vcb1o15kjqp1b71aqkzmxo7t",
"descriptor": {
"name": "[RM] [Scheme 1- Tekdi 10] Support Scheme for Persons with Disability (40% and above)",
"long_desc": "This scheme provides assistance to individuals with 40% or more disability to improve their quality of life."
},
"price": {
"currency": "INR",
"value": "0"
},
"time": {
"range": {
"start": "2025-07-01T00:00:00.000Z",
"end": "2025-10-31T00:00:00.000Z"
}
},
"rateable": false
}
],
"id": "TLEXP_BE0E180D_1758547273958",
"fulfillments": [
{
"id": "FULFILL_UNIFIED",
"type": "APPLICATION",
"tracking": false,
"state": {
"descriptor": {
"code": "APPLICATION-REJECTED",
"name": "{\"status\":\"Application Pending\",\"comment\":\"\"}"
},
"updated_at": "2025-10-15T07:02:29.153Z"
}
}
]
}
},
"context": {
"domain": "ubi:financial-support",
"action": "on_status",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.ubi.com",
"bpp_uri": "https://dev-uba-bpp.ubi.com/",
"country": "IND",
"city": "std:080",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"bap_id": "dev-uba-bap.ubi.com",
"bap_uri": "https://dev-uba-bap.ubi.com/",
"transaction_id": "20bd48e9-153b-4653-a960-29a360232633",
"message_id": "bcaea789-370a-4287-8721-422ce6f63442",
"ttl": "PT10M",
"timestamp": "2025-09-24T05:18:03.691Z"
}
}
]
}🔑 Important Implementation Notes
Unique
message_idper request: Every network call must have a newmessage_id. Example:/search,/select,/init,/confirm, and/statuseach use a distinct one.Consistent
transaction_idper application: For all subsequent API calls (init,confirm,update,status), reuse the sametransaction_idreceived in the/selectresponse. This enables consistent application tracking.Application Tracking on BAP & BPP:
BAP stores:
bap_application_id,bpp_id,benefit_id,transaction_id, andbpp_application_id(when received).BPP stores:
bap_application_id,transaction_id,bap_id,user_id, andbpp_application_id.
Last updated