Integration Guide

Eligibility API Integration Examples

Example 1 :- Real Implementation from Reference Beneficiary Toaster Backend (Check eligibility for a given user from the list of benefits)

This example 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;
}

Input - 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',
  fatherName: '',
  gender: 'male',
  caste: 'sc',
  annualIncome: '400000',
  disabilityStatus: '',
  aadhaar: '',
  age: '25',
  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.

Input - 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.

Output - Response Structure

The Eligibility SDK returns results in this format:

const eligibilityResponse = {
  eligible: [
    {
      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"]
          }
        ]
      }
    }
  ],
  ineligible: [
    {
      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: []
};

Example 2: Real Implementation from Reference Provider Backend (Check eligible users for a given application)

This example shows the actual implementation of how the provider backend integrates with the Eligibility SDK to evaluate individual applications against specific benefit criteria.

Overview

The provider app uses the Eligibility SDK to check if individual applications qualify for specific benefit schemes. The integration happens in the ApplicationsService class and is used for:

• Real-time eligibility checking during application processing

• Batch processing of pending applications via cron jobs

Service Implementation

async checkApplicationEligibility(
  userInfo: object,
  eligibilityData: Array<any>,
  strictCheck: boolean,
): Promise<any> {
  try {
    let eligibilityApiEnd = 'check-users-eligibility'; // Default endpoint
    if (strictCheck) {
      eligibilityApiEnd = 'check-users-eligibility?strictChecking=true'; // Use strict checking endpoint
    }
    const eligibilityApiUrl = `${this.eligibility_base_uri}/${eligibilityApiEnd}`;
    const sdkResponse = await this.httpService.axiosRef.post(
      eligibilityApiUrl,
      {
        userProfiles: [userInfo],
        benefitSchema: { eligibility: eligibilityData },
      },
      {
        headers: {
          'Content-Type': 'application/json',
        },
      },
    );
    return sdkResponse.data;
  } catch (error) {
    throw new Error(`Error checking benefits eligibility: ${error.message}`);
  }
}

Input - 1. User Profile Data Structure

The provider app sends application data in this format:

const userProfile = {
  applicationId: 12345,
  firstName: 'Aman',
  lastName: 'Gupta',
  email: '[e-mail]',
  phoneNumber: '9999999999',
  dob: '1990-01-01',
  gender: 'male',
  caste: 'sc',
  annualIncome: '400000',
  disabilityStatus: '',
  aadhaar: '123456789012',
  age: '25',
  class: '9',
  currentSchoolName: 'ABC School',
  previousYearMarks: '75',
  disabilityType: '',
  state: 'Maharashtra',
  documentVerificationStatus: 'verified',
  // ... other fields from application.applicationData
};

Important Notes:

• The user object is flattened from the application's applicationData field

• Includes application-specific metadata like applicationId and documentVerificationStatus

• Fields are extracted from the application's stored data and benefit requirements

• The object structure adapts based on the specific benefit's data requirements

Input - 2. Benefit Schema Data Structure

The app processes benefit eligibility rules from Strapi CMS and formats them for the Eligibility SDK:

const benefitSchema = {
  eligibility: [
    {
      id: "B1",
      type: "userProfile",
      description: "The applicant must be from SC or ST or OBC castes",
      evidence: "caste",
      criteria: {
        id: "B1",
        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",
      evidence: "annualIncome",
      criteria: {
        id: "B2",
        name: "annualIncome", 
        condition: "lte",
        conditionValues: 270000
      }
    },
    {
      id: "B3",
      type: "userProfile", 
      description: "All documents must be verified",
      evidence: "verification status",
      criteria: {
        id: "B3",
        name: "documentVerificationStatus",
        condition: "equals",
        conditionValues: ["verified"]
      }
    }
  ]
};

Important Notes:

• Eligibility rules are defined in Strapi CMS for each benefit

• The provider automatically adds a document verification rule with auto-generated ID

• Rules are processed and formatted before sending to the SDK

• Each rule includes id, type, description, evidence, and criteria

Output - Response Structure

The Eligibility SDK returns results in this format:

const eligibilityResponse = {
  eligibleUsers: [
    {
      details: {
        applicationId: 12345,
        eligibilityPercentage: 66.67,
        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"]
          },
          {
            ruleKey: "B3",
            passed: true,
            description: "All documents must be verified", 
            reasons: []
          }
        ],
        reasons: ["Income 400000 exceeds the maximum limit of 270000"]
      }
    }
  ],
  ineligibleUsers: [],
  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