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
Search → Fetch list of benefits from UBI network.
Select → User selects a benefit to apply.
Init → Initialize application with user profile (from VCs).
Confirm → Confirm the application.
Integration Flow
1. Search Benefits → 2. Select Benefit → 3. Initiate Application → 4. Confirm ApplicationFlow 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
{
"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": {}
}
}
}
}You will get the response to this 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. Select API - Get Benefit Details
Endpoint: POST https://your-bap.client.com/api/select
Purpose: Get detailed information about a specific benefit
Headers:
Authorization: Bearer API-AUTH-TOKEN
Content-Type: application/jsonRequest Structure:
Sample Request
{
"context": {
"domain": "ubi:financial-support",
"action": "select",
"timestamp": "2025-08-01T12:10:22.026Z",
"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": "1f750d37-8111-4d06-b929-c3148987d78c",
"message_id": "4aa1f187-92b6-4e93-818e-5321ce82d84a",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
}
},
"message": {
"order": {
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u"
}
],
"provider": {
"id": "uuzx97qeybdwjjwj02vmda7u"
}
}
}
}You will get the response to this as:
Sample Response
{
"context": {
"domain": "ubi:financial-support",
"action": "on_select",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.provider.com",
"bpp_uri": "https://dev-uba-bpp.provider.com/",
"bap_id": "dev-uba-bap.provider.com",
"bap_uri": "https://dev-uba-bap.provider.com/",
"transaction_id": "1f750d37-8111-4d06-b929-c3148987d78c",
"message_id": "4aa1f187-92b6-4e93-818e-5321ce82d84a",
"timestamp": "2025-08-01T12:10:35.394Z",
"ttl": "PT10M",
"location": {
"country": { "name": "India", "code": "IND" },
"city": { "name": "Bangalore", "code": "std:080" }
}
},
"message": {
"order": {
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u",
"descriptor": {
"name": "Ekstep Disability Support Scheme - Test",
"long_desc": "This scheme supports students with disabilities."
},
"price": { "currency": "INR", "value": "0" }
}
],
"provider": { "id": "PROVIDER_UNIFIED", "descriptor": { "name": "Scholarlify" } }
}
}
}
3. Init API - Start Application Process
Endpoint: POST https://your-bap.client.com/api/init
Purpose: Initialize the application process and get the application form URL
Request Structure:
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": "0206a019-69c6-46ce-bc64-06cc605b37aa",
"message_id": "c9eff9ef-6502-4638-8f6e-801e77b243f1",
"ttl": "PT10M",
"timestamp": "2025-08-01T12:08:40.787Z"
},
"message": {
"order": {
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u"
}
]
}
}
}You will get the response to this as:
Sample Response
{
"context": {
"ttl": "PT10M",
"action": "init",
"timestamp": "2025-09-23T10:41:31.861Z",
"message_id": "a1cbd3e1-0fb1-4cd3-bec1-586adc652090",
"transaction_id": "89843fe7-ff96-4dfc-9dc9-c62565922a15",
"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": "89843fe7-ff96-4dfc-9dc9-c62565922a15",
"message_id": "a1cbd3e1-0fb1-4cd3-bec1-586adc652090",
"ttl": "PT10M",
"timestamp": "2025-09-23T10:39:00.034Z"
},
"message": {
"order": {
"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,
"tags": [
{
"display": true,
"descriptor": {
"code": "eligibility",
"name": "Eligibility"
},
"list": [
{
"descriptor": {
"code": "disabilityType",
"name": "Health - disabilityType",
"short_desc": "The applicant must have disability type as certified by competent medical authority"
},
"value": "{\"id\":312,\"evidence\":\"disabilityType\",\"type\":\"health\",\"description\":\"The applicant must have disability type as certified by competent medical authority\",\"allowedProofs\":[\"disabilityCertificate\"],\"criteria\":{\"id\":312,\"name\":\"disabilityType\",\"condition\":\"in\",\"conditionValues\":[\"acid_attack_victim\",\"autism_spectrum_disorder\",\"blindness\",\"cerebral_palsy\",\"chronic_neurological_conditions\",\"deaf\",\"dwarfism\",\"hard_of_hearing\",\"hearing_impairment\",\"hemophilia\",\"intellectual_disability\",\"leprosy_cured\",\"locomotor_disability\",\"low_vision\",\"mental_illness\",\"mental_retardation\",\"multiple_disabilities\",\"multiple_disabilities_including_deaf_blindness\",\"multiple_sclerosis\",\"muscular_dystrophy\",\"parkinson_s_disease\",\"sickle_cell_disease\",\"specific_learning_disability\",\"speech_and_language_disability\",\"thalassemia\"]}}",
"display": true
},
{
"descriptor": {
"code": "disabilityRange",
"name": "Health - disabilityRange",
"short_desc": "The applicant must have 40% or more disability as certified by competent medical authority"
},
"value": "{\"id\":313,\"evidence\":\"disabilityRange\",\"type\":\"health\",\"description\":\"The applicant must have 40% or more disability as certified by competent medical authority\",\"allowedProofs\":[\"disabilityCertificate\"],\"criteria\":{\"id\":313,\"name\":\"disabilityRange\",\"condition\":\"greater than equals\",\"conditionValues\":[\"40\"]}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "required-docs",
"name": "Required Documents"
},
"list": [
{
"descriptor": {
"code": "mandatory-doc",
"name": "Mandatory Document"
},
"value": "{\"id\":379,\"documentType\":\"disabilityProof\",\"isRequired\":true,\"allowedProofs\":[\"disabilityCertificate\"]}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "benefits",
"name": "Benefits"
},
"list": [
{
"descriptor": {
"code": "financial",
"name": "Disability Support Grant"
},
"value": "{\"__component\":\"benefit.financial-benefit\",\"id\":188,\"title\":\"Disability Support Grant\",\"type\":\"financial\",\"description\":\"Provides financial aid or services based on the type and severity of disability.\",\"description_md\":null,\"minValue\":\"100\",\"maxValue\":\"1500\"}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "sponsoringEntities",
"name": "Sponsoring Entities"
},
"list": [
{
"descriptor": {
"code": "sponsoringEntities",
"name": "Entities Sponsoring Benefits"
},
"value": "{\"id\":156,\"name\":\"Ministry of Social Justice and Empowerment\",\"type\":\"government\",\"department\":\"Ministry of Social Justice and Empowerment\",\"sponsorShare\":\"100\",\"address\":{\"id\":310,\"street\":\"5th Floor, Antyodaya Bhawan, CGO Complex, Lodhi Road\",\"city\":\"New Delhi\",\"state\":\"Delhi\",\"postalCode\":\"110003\"},\"contactInfo\":{\"id\":310,\"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\":1541,\"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": "{\"id\":1542,\"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": "{\"id\":1544,\"name\":\"gender\",\"type\":\"select\",\"label\":\"Gender\",\"required\":true,\"multiple\":null,\"options\":[{\"id\":1551,\"label\":\"Male\",\"value\":\"male\"},{\"id\":1552,\"label\":\"Female\",\"value\":\"female\"}],\"fieldsGroupName\":\"personalInfo\",\"fieldsGroupLabel\":\"Personal Info\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-disabilityType",
"name": "Application Form Field - Disability Type"
},
"value": "{\"id\":1545,\"name\":\"disabilityType\",\"type\":\"select\",\"label\":\"Disability Type\",\"required\":true,\"multiple\":null,\"options\":[{\"id\":1553,\"label\":\"Acid Attack Victim\",\"value\":\"acid_attack_victim\"},{\"id\":1554,\"label\":\"Autism Spectrum Disorder\",\"value\":\"autism_spectrum_disorder\"},{\"id\":1555,\"label\":\"Blindness\",\"value\":\"blindness\"},{\"id\":1556,\"label\":\"Cerebral Palsy\",\"value\":\"cerebral_palsy\"},{\"id\":1557,\"label\":\"Chronic Neurological Conditions\",\"value\":\"chronic_neurological_conditions\"},{\"id\":1558,\"label\":\"Deaf\",\"value\":\"deaf\"},{\"id\":1559,\"label\":\"Deafness\",\"value\":\"deafness\"},{\"id\":1560,\"label\":\"Dwarfism\",\"value\":\"dwarfism\"},{\"id\":1561,\"label\":\"Hard of Hearing\",\"value\":\"hard_of_hearing\"},{\"id\":1562,\"label\":\"Hearing Impairment\",\"value\":\"hearing_impairment\"},{\"id\":1563,\"label\":\"Hemophilia\",\"value\":\"hemophilia\"},{\"id\":1564,\"label\":\"Intellectual Disability\",\"value\":\"intellectual_disability\"},{\"id\":1565,\"label\":\"Leprosy Cured\",\"value\":\"leprosy_cured\"},{\"id\":1566,\"label\":\"Locomotor Disability\",\"value\":\"locomotor_disability\"},{\"id\":1567,\"label\":\"Low Vision\",\"value\":\"low_vision\"},{\"id\":1568,\"label\":\"Mental Illness\",\"value\":\"mental_illness\"},{\"id\":1569,\"label\":\"Multiple Disabilities\",\"value\":\"multiple_disabilities\"},{\"id\":1570,\"label\":\"Multiple Sclerosis\",\"value\":\"multiple_sclerosis\"},{\"id\":1571,\"label\":\"Muscular Dystrophy\",\"value\":\"muscular_dystrophy\"},{\"id\":1572,\"label\":\"Parkinsons Disease\",\"value\":\"parkinsons_disease\"},{\"id\":1573,\"label\":\"Sickle Cell Disease\",\"value\":\"sickle_cell_disease\"},{\"id\":1574,\"label\":\"Specific Learning Disability\",\"value\":\"specific_learning_disability\"},{\"id\":1575,\"label\":\"Speech and Language Disability\",\"value\":\"speech_language_disability\"},{\"id\":1576,\"label\":\"Thalassemia\",\"value\":\"thalassemia\"}],\"fieldsGroupName\":\"disabilityDetails\",\"fieldsGroupLabel\":\"Disability Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-disabilityRange",
"name": "Application Form Field - Disability Range"
},
"value": "{\"id\":1543,\"name\":\"disabilityRange\",\"type\":\"text\",\"label\":\"Disability Range\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"disabilityDetails\",\"fieldsGroupLabel\":\"Disability Details\"}",
"display": true
}
]
}
],
"xinput": {
"head": {
"descriptor": {
"name": "Application Form"
},
"index": {
"min": 0,
"cur": 0,
"max": 1
},
"headings": [
"Personal Details"
]
},
"form": {
"url": "https://dev-uba-provider.ubi.com/benefit/apply/vcb1o15kjqp1b71aqkzmxo7t",
"mime_type": "text/html",
"resubmit": false
},
"required": true
}
}
],
"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"
}
}
]
}
]
}
}
}
]
}In the response, you will get the form URL from the provider on the path given below, this URL is the application form URL, which needs to be loaded in the iframe on the seeker app for applying to the benefit.
const url = result.data.responses.[0].message.order.items.[0].xinput.form.url;Beneficiary app loads form URL in an
<iframe>.Sends the applicant’s formdata data (VCs + profile info) via the
nameattribute.Listens for messages (
postMessage) from the provider.On receiving an Order ID after submission, calls the Confirm API and creates the application record locally.
<iFrame
src={url}
name={JSON.stringify(formData)}
style={{ width: '100%' }}
title="Form UI"
/>4. Confirm API - Submit Application
Endpoint: POST https://your-bap.client.com/api/confirm
Purpose: Submit the completed application with VCs
Request Structure:
Sample Request
{
"context": {
"domain": "ubi:financial-support",
"location": {
"country": {
"name": "India",
"code": "IND"
},
"city": {
"name": "Bangalore",
"code": "std:080"
}
},
"action": "confirm",
"timestamp": "2025-08-01T12:34:30.384Z",
"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": "3cd091cb-b77e-468a-82de-e4eedae7efc3",
"transaction_id": "d0a2b884-e1b3-42da-a296-03f286c4fc28"
},
"message": {
"order": {
"provider": {
"id": ""
},
"items": [
{
"id": "55"
}
],
"billing": {
"name": "Manjunath",
"organization": {},
"address": "No 27, XYZ Lane, etc",
"phone": "+91-9999999999"
},
"fulfillments": [
{
"customer": {},
"tags": [
{
"descriptor": {},
"value": "PNB"
}
]
}
],
"payment": [
{
"params": {}
}
]
}
}
}You will get the response to this as:
Sample Response
{
"context": {
"domain": "ubi:financial-support",
"action": "on_confirm",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.provider.com",
"bpp_uri": "https://dev-uba-bpp.provider.com/",
"bap_id": "dev-uba-bap.provider.com",
"bap_uri": "https://dev-uba-bap.provider.com/",
"transaction_id": "cb63b4a2-122d-40e6-bc0c-0a3fd3ec9c11",
"message_id": "7f01a16a-0d3f-4a9a-9324-9ea11eafaa82",
"timestamp": "2025-09-15T11:35:42.510Z",
"ttl": "PT10M",
"location": {
"country": { "name": "India", "code": "IND" },
"city": { "name": "Bangalore", "code": "std:080" }
}
},
"message": {
"order": {
"id": "ORDER_123456",
"status": "CONFIRMED",
"provider": {
"id": "PROVIDER_UNIFIED",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Scholarship and welfare schemes"
}
},
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u",
"descriptor": {
"name": "Ekstep Disability Support Scheme - Test",
"long_desc": "This scheme supports students with disabilities."
},
"price": { "currency": "INR", "value": "0" }
}
],
"fulfillments": [
{
"id": "FULFILLMENT_123",
"type": "Application",
"state": { "descriptor": { "code": "submitted", "name": "Submitted" } },
"customer": {
"person": {
"name": "Aman Gupta",
"gender": "male",
"dob": "1990-01-01"
},
"contact": { "phone": "9999999999", "email": "user@example.com" }
}
}
]
}
}
}
5. 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
{
"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"
}
}You will get the response to this 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.ubi.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,
"tags": [
{
"display": true,
"descriptor": {
"code": "eligibility",
"name": "Eligibility"
},
"list": [
{
"descriptor": {
"code": "disabilityType",
"name": "Health - disabilityType",
"short_desc": "The applicant must have disability type as certified by competent medical authority"
},
"value": "{\"id\":312,\"evidence\":\"disabilityType\",\"type\":\"health\",\"description\":\"The applicant must have disability type as certified by competent medical authority\",\"allowedProofs\":[\"disabilityCertificate\"],\"criteria\":{\"id\":312,\"name\":\"disabilityType\",\"condition\":\"in\",\"conditionValues\":[\"acid_attack_victim\",\"autism_spectrum_disorder\",\"blindness\",\"cerebral_palsy\",\"chronic_neurological_conditions\",\"deaf\",\"dwarfism\",\"hard_of_hearing\",\"hearing_impairment\",\"hemophilia\",\"intellectual_disability\",\"leprosy_cured\",\"locomotor_disability\",\"low_vision\",\"mental_illness\",\"mental_retardation\",\"multiple_disabilities\",\"multiple_disabilities_including_deaf_blindness\",\"multiple_sclerosis\",\"muscular_dystrophy\",\"parkinson_s_disease\",\"sickle_cell_disease\",\"specific_learning_disability\",\"speech_and_language_disability\",\"thalassemia\"]}}",
"display": true
},
{
"descriptor": {
"code": "disabilityRange",
"name": "Health - disabilityRange",
"short_desc": "The applicant must have 40% or more disability as certified by competent medical authority"
},
"value": "{\"id\":313,\"evidence\":\"disabilityRange\",\"type\":\"health\",\"description\":\"The applicant must have 40% or more disability as certified by competent medical authority\",\"allowedProofs\":[\"disabilityCertificate\"],\"criteria\":{\"id\":313,\"name\":\"disabilityRange\",\"condition\":\"greater than equals\",\"conditionValues\":[\"40\"]}}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "required-docs",
"name": "Required Documents"
},
"list": [
{
"descriptor": {
"code": "mandatory-doc",
"name": "Mandatory Document"
},
"value": "{\"id\":379,\"documentType\":\"disabilityProof\",\"isRequired\":true,\"allowedProofs\":[\"disabilityCertificate\"]}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "benefits",
"name": "Benefits"
},
"list": [
{
"descriptor": {
"code": "financial",
"name": "Disability Support Grant"
},
"value": "{\"__component\":\"benefit.financial-benefit\",\"id\":188,\"title\":\"Disability Support Grant\",\"type\":\"financial\",\"description\":\"Provides financial aid or services based on the type and severity of disability.\",\"description_md\":null,\"minValue\":\"100\",\"maxValue\":\"1500\"}",
"display": true
}
]
},
{
"display": true,
"descriptor": {
"code": "sponsoringEntities",
"name": "Sponsoring Entities"
},
"list": [
{
"descriptor": {
"code": "sponsoringEntities",
"name": "Entities Sponsoring Benefits"
},
"value": "{\"id\":156,\"name\":\"Ministry of Social Justice and Empowerment\",\"type\":\"government\",\"department\":\"Ministry of Social Justice and Empowerment\",\"sponsorShare\":\"100\",\"address\":{\"id\":310,\"street\":\"5th Floor, Antyodaya Bhawan, CGO Complex, Lodhi Road\",\"city\":\"New Delhi\",\"state\":\"Delhi\",\"postalCode\":\"110003\"},\"contactInfo\":{\"id\":310,\"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\":1541,\"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": "{\"id\":1542,\"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": "{\"id\":1544,\"name\":\"gender\",\"type\":\"select\",\"label\":\"Gender\",\"required\":true,\"multiple\":null,\"options\":[{\"id\":1551,\"label\":\"Male\",\"value\":\"male\"},{\"id\":1552,\"label\":\"Female\",\"value\":\"female\"}],\"fieldsGroupName\":\"personalInfo\",\"fieldsGroupLabel\":\"Personal Info\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-disabilityType",
"name": "Application Form Field - Disability Type"
},
"value": "{\"id\":1545,\"name\":\"disabilityType\",\"type\":\"select\",\"label\":\"Disability Type\",\"required\":true,\"multiple\":null,\"options\":[{\"id\":1553,\"label\":\"Acid Attack Victim\",\"value\":\"acid_attack_victim\"},{\"id\":1554,\"label\":\"Autism Spectrum Disorder\",\"value\":\"autism_spectrum_disorder\"},{\"id\":1555,\"label\":\"Blindness\",\"value\":\"blindness\"},{\"id\":1556,\"label\":\"Cerebral Palsy\",\"value\":\"cerebral_palsy\"},{\"id\":1557,\"label\":\"Chronic Neurological Conditions\",\"value\":\"chronic_neurological_conditions\"},{\"id\":1558,\"label\":\"Deaf\",\"value\":\"deaf\"},{\"id\":1559,\"label\":\"Deafness\",\"value\":\"deafness\"},{\"id\":1560,\"label\":\"Dwarfism\",\"value\":\"dwarfism\"},{\"id\":1561,\"label\":\"Hard of Hearing\",\"value\":\"hard_of_hearing\"},{\"id\":1562,\"label\":\"Hearing Impairment\",\"value\":\"hearing_impairment\"},{\"id\":1563,\"label\":\"Hemophilia\",\"value\":\"hemophilia\"},{\"id\":1564,\"label\":\"Intellectual Disability\",\"value\":\"intellectual_disability\"},{\"id\":1565,\"label\":\"Leprosy Cured\",\"value\":\"leprosy_cured\"},{\"id\":1566,\"label\":\"Locomotor Disability\",\"value\":\"locomotor_disability\"},{\"id\":1567,\"label\":\"Low Vision\",\"value\":\"low_vision\"},{\"id\":1568,\"label\":\"Mental Illness\",\"value\":\"mental_illness\"},{\"id\":1569,\"label\":\"Multiple Disabilities\",\"value\":\"multiple_disabilities\"},{\"id\":1570,\"label\":\"Multiple Sclerosis\",\"value\":\"multiple_sclerosis\"},{\"id\":1571,\"label\":\"Muscular Dystrophy\",\"value\":\"muscular_dystrophy\"},{\"id\":1572,\"label\":\"Parkinsons Disease\",\"value\":\"parkinsons_disease\"},{\"id\":1573,\"label\":\"Sickle Cell Disease\",\"value\":\"sickle_cell_disease\"},{\"id\":1574,\"label\":\"Specific Learning Disability\",\"value\":\"specific_learning_disability\"},{\"id\":1575,\"label\":\"Speech and Language Disability\",\"value\":\"speech_language_disability\"},{\"id\":1576,\"label\":\"Thalassemia\",\"value\":\"thalassemia\"}],\"fieldsGroupName\":\"disabilityDetails\",\"fieldsGroupLabel\":\"Disability Details\"}",
"display": true
},
{
"descriptor": {
"code": "applicationFormField-disabilityRange",
"name": "Application Form Field - Disability Range"
},
"value": "{\"id\":1543,\"name\":\"disabilityRange\",\"type\":\"text\",\"label\":\"Disability Range\",\"required\":true,\"multiple\":null,\"options\":[],\"fieldsGroupName\":\"disabilityDetails\",\"fieldsGroupLabel\":\"Disability Details\"}",
"display": true
}
]
}
]
}
],
"id": "TLEXP_BE0E180D_1758547273958",
"billing": {
"name": "N/A",
"phone": "N/A",
"email": "dummyemail@dummydomain.com",
"address": "N/A",
"organization": {
"descriptor": {
"name": "Onest",
"code": "onest.com"
},
"contact": {
"phone": "+91-8888888888",
"email": "scholarships@nammayatri.in"
}
}
},
"payments": [
{
"params": {
"bank_code": "ICICI",
"bank_account_number": "123456789012",
"bank_account_name": "John Doe"
},
"type": "PRE-ORDER",
"status": "PAID",
"collected_by": "bpp"
}
],
"fulfillments": [
{
"id": "FULFILL_UNIFIED",
"type": "APPLICATION",
"tracking": false,
"state": {
"descriptor": {
"code": "APPLICATION-PENDING",
"name": "{\"status\":\"Application Pending\",\"comment\":\"\"}"
},
"updated_at": "2025-09-24T05:18:01.674Z"
},
"agent": {
"person": {
"name": "Ekstep Foundation SPoc"
},
"contact": {
"email": "ekstepsupport@ekstep.com"
}
},
"customer": {
"id": "aadhaar:798677675565",
"person": {
"name": "Jane Doe",
"age": "13",
"gender": "female"
},
"contact": {
"phone": "+91-9663088848",
"email": "jane.doe@example.com"
}
}
}
],
"quote": {
"price": {
"currency": "INR",
"value": "123"
},
"breakup": [
{
"title": "Tuition Fee",
"price": {
"currency": "INR",
"value": "123"
}
}
]
}
}
},
"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"
}
}
]
}This integration guide provides everything needed to successfully integrate beneficiary applications with the UBI network, following the 4-step process: Search → Select → Init → Confirm.
Last updated