Integration Guide

Eligibility API Integration Example

Real Implementation from Beneficiary Backend

This document shows the actual implementation of how the beneficiary backend integrates with the Eligibility SDK

Overview

The beneficiary app uses the Eligibility SDK to check if users qualify for various benefit schemes. The integration happens in the ContentService class and is used throughout the application for:

1. Real-time eligibility checking during benefit application

2. Batch processing of user eligibility

3. Form validation and user feedback

4. Benefit recommendation based on user profile

Service Implementation

ContentService Integration

async checkBenefitsEligibility(userInfo: object, eligibilityData: Array<any>, strictCheck: boolean) {
  const url = `${this.eligibility_base_uri}/check-eligibility?strictChecking=${strictCheck}`;
  
  const response = await this.httpService.axiosRef.post(url, {
    userProfile: userInfo,
    benefitsList: eligibilityData,
  }, {
    headers: { 'Content-Type': 'application/json' }
  });

  return response.data;
}

1. User Profile Data Structure

The beneficiary app sends user data in this format:

const userProfile = {
  user_id: '3884735a-8ffe-4ad0-bb5c-741d010fbe34',
  firstName: 'Aman',
  middleName: '',
  lastName: 'Gupta',
  email: '[e-mail]',
  phoneNumber: '9999999999',
  dob: '1990-01-01',
  sso_provider: 'keycloak',
  sso_id: '435020b0-99de-48ac-81eb-c617b9664854',
  image: '',
  fieldsVerified: 'false',
  fieldsVerifiedAt: 'Mon Sep 15 2025 14:40:16 GMT+0530 (India Standard Time)',
  walletToken: 'e5003b22-dd9b-4da4-827d-2bdc319c8235',
  created_at: 'Wed Jul 16 2025 09:57:05 GMT+0530 (India Standard Time)',
  updated_at: 'Mon Sep 15 2025 14:40:16 GMT+0530 (India Standard Time)',
  docs: '',
  fatherName: '',
  gender: 'male',
  caste: 'sc',
  annualIncome: '400000',
  disabilityStatus: '',
  aadhaar: '',
  age: '25',
  nspOtr: '',
  studentType: '',
  udid: '',
  class: '9',
  currentSchoolName: '',
  previousYearMarks: '75',
  disabilityType: '',
  disabilityRange: '',
  bankAccountHolderName: '',
  bankName: '',
  branchCode: '',
  bankAccountNumber: '',
  bankIfscCode: '',
  bankAddress: '',
  tuitionAndAdminFeePaid: '',
  miscFeePaid: '',
  state: 'Maharashtra',
  acres: ''
};

Important Notes:

• The user object must be flat (no deeply nested structures).

• The fields may vary depending on the user profile in your application, but the SDK always expects a flat object for userProfile.

• This is sample data from the reference Beneficiary App — adapt it to your application’s schema.

2. Benefit Schema Data Structure

The app processes benefit data from Hasura and formats it for the Eligibility SDK:

const benefitsList = [
  {
    id: 29677,
    eligibility: [
      {
        id: "B1",
        type: "userProfile",
        description: "The applicant must be from SC or ST or OBC castes",
        criteria: {
          name: "caste",
          condition: "in",
          conditionValues: ["sc", "st", "obc"]
        }
      },
      {
        id: "B2",
        type: "userProfile",
        description: "The Total Annual income must not exceed ₹2.7 Lakh per Annum",
        criteria: {
          name: "annualIncome",
          condition: "lte",
          conditionValues: 270000
        }
      }
    ],
    eligibilityEvaluationLogic: "(B1 && B2)"
  },
  {
    id: 29682,
    eligibility: [
      {
        id: "C1",
        type: "userProfile",
        description: "Age must be between 16 and 25 years",
        criteria: {
          name: "age",
          condition: "between",
          conditionValues: [16, 25]
        }
      }
    ],
    eligibilityEvaluationLogic: "C1"
  }
  // ... more benefit schemas
];

Important Note:

• The eligibility criteria in your system may be defined in a different format (e.g. database schema, JSON rules, policy configs). In reference Beneficiary App we are using Strapi to define the benefit schemes, and we format the benefit into the required format and send it to the eligibility SDK.

• You must translate your eligibility rules into this standardized format before passing them to the SDK so they can be processed.

• The examples above are taken from the reference Beneficiary App.

3. API Response Structure

The Eligibility SDK returns results in this format:

const eligibilityResponse = {
  eligible: [],
  ineligible: [
    {
      schemaId: 29677,
      details: {
        isEligible: false,
        reasons: ["Income 400000 exceeds the maximum limit of 270000"],
        evaluationResults: {
          B1: true,
          B2: false
        },
        criteriaResults: [
          {
            ruleKey: "B1",
            passed: true,
            description: "The applicant must be from SC or ST or OBC castes",
            reasons: []
          },
          {
            ruleKey: "B2",
            passed: false,
            description: "The Total Annual income must not exceed ₹2.7 Lakh per Annum",
            reasons: ["Income 400000 exceeds the maximum limit of 270000"]
          }
        ]
      }
    },
    {
      schemaId: 29682,
      details: {
        isEligible: false,
        reasons: ["Age 25 is not between 16 and 25"],
        evaluationResults: {
          C1: false
        },
        criteriaResults: [
          {
            ruleKey: "C1",
            passed: false,
            description: "Age must be between 16 and 25 years",
            reasons: ["Age 25 is not between 16 and 25"]
          }
        ]
      }
    }
    // ... more ineligible benefits
  ],
  errors: []
};

You can also refer to the Postman collection of the available APIs on the link given below

https://github.com/PSMRI/ubi-eligibility-sdk/blob/main/docs/Benefit_Eligibility_SDK.postman_collection.json