BIS – State Scheme Integration

BIS State/UTs Schemes

Data Integration Approach

JAN, 2020

Version Control Table

pg. 1
 BIS – State Scheme Integration

Sr No. Version Change Brief Updated Remarks

Date (if any)
1 V1.0 Initial Version 18 July 2018

2 V1.1 family_mem_guid_id, family_mem_id have been 23 July 2018

moved under “family” object
3 V1.2 error_msg parameter added in response 12-Dec-2019
4 V1.3 State code parameter in the request body 30-jan-2020

pg. 2
 BIS – State Scheme Integration

Overview
The purpose of this document is to provide an understanding of the State RSBY/Ration Card Beneficiary
database data exchange to BIS Application on regular basis.

Objective
To share the individual Beneficiary Family data from State RSBY/Ration Card Beneficiary database, data
format has been defined.

Data Exchange Format

To show the Beneficiary Family data of State/UTs, below mentioned format has been defined.
States/Ut’s need to expose an API for data exchange. Central BIS application will call the API using
Post Method.

# Data Field Type Description

Request Description
1. ID_Type String Since this is generic JSON format for all types of data
sources for BIS, therefore this field will define ID like
1=RSBY, 2 for PDS etc.
2. ID_Number String Based on the ID Type, ID number will be mentioned here
like RSBY URN or Ration Card Number.
3. Token String Token will be shared by the owner of the API
4. state_code String State code lgd
Response Description
5. ID_Type* String This will return the ID_Type as provided in Request
6. ID_Number* String This will return the ID_Number as provided in Request
7. error_code* String This will return the error Code. It returns
“0” – in case of No Error
“1” – in case of Error with Invalid Credentials ie Token
Expired
“2” – in case of Invalid Request Format
“3”- in case of service not available/ Scheduled
Downtime
“99” – in case no records are found as per
“100”- Multiple Families found
8. error_msg String Error description
9. family_guid* String Family unique identifier within state. Incase family_id is
unique across state then value of family_id need to be
shared in this field.
pg. 3
 BIS – State Scheme Integration

10. family_id* String Family identifier eg. Ration Card , MSBY card number
11. family_mem_guid_id* String Family member unique identifier across different family or
within a State. Incase family_mem_id is unique across
state then value of family_mem_id need to be shared in
this field.
12. family_mem_id* String family member identifier unique across in same family

13. SECC_HHD String If the state database is linked to SECC data, the SECC
HHID must be populated.

14. state_lgd_code* String State LGD code

15. district_lgd_code String District LGD code
16. subdistrict_lgd_code String Sub District LGD code
17. village_town_lgd_code String Village/Town LGD Code
18. pincode String Area pin code
19. member_name_eng* String Name of the family member in English
20. member_name_regional String Name of the family member in Regional Language
21. mother_name_eng String mother name of the member in English
22. mother_name_regional String mother name of the member in Regional Language
23. father_name_eng String Father name of the member in English
24. father_name_regional String Father name of the member in Regional Language
25. spouse_name_eng String Spouse name of the member in English
26. spouse_name_regional String Spouse name of the member in Regional Language
27. year_of_birth String Year of Birth of the member (YYYY)
28. mobile_number String Mobile Number of the member
29. relation_name String Relation of the member with head of the family
30. gender String Gender of the member
31. address String Address of the member
32. AHL_TIN String If the state database is linked to SECC data, the SECC
AHL_TIN of the member must be populated.
33. remarks String Remarks if any regarding Family
32. rural_urban String “R” in case of Rural, “U” in case of Urban
33. field1 String For Future Use
34. field2 String For Future Use

Note: *(asterisk marked) cells are mandatory to provide minimum information.

pg. 4
 BIS – State Scheme Integration

BIS application will call a Web service exposed by the State/UTs by passing ID_Type (alphanumeric
number - generated through BIS application), ID_Number, Token as request parameter Scheme
will send back the following details in Response:

1) Complete Dataset OR
2) No Data if No Records are found OR
3) Error Message if there was some issue.

Technology Details

• Technology: Restful web service / SOAP

• Response: JSON
• Request Method: POST
• Usage: This web service will provide beneficiary data to BIS Application.

Every time, Get Family Details API will provide the verified/ Final data to the BIS application

• JSON Request and Response Format

A sample JSON Request /Response have been attached for reference

• Request

{
"ID_Type": "",
"ID_Number": "",
"Token": "",
"state_code": "",
}

pg. 5
 BIS – State Scheme Integration

• Response

{
"Header": {
"ID_Type": "",
"ID_Number": "",
"error_code": "",
"error_msg": ""
},
"Details": [
{
"family_guid": "",
"family_id": "",
"SECC_HHD": "",
"state_lgd_code": "",
"district_lgd_code": "",
"subdistrict_lgd_code": "",
"village_town_lgd_code": "",
"pincode": "",
"rural_urban": "",
"family": [
{
"family_mem_guid_id": "",
"family_mem_id": "",
"member_name_eng": "",
"member_name_regional": "",
"mother_name_eng": "",
"mother_name_regional": "",
"father_name_eng": "",
"father_name_regional": "",
"spouse_name_eng": "",
"spouse_name_regional": "",
"year_of_birth": "",
"mobile_number": "",
"relation_name": "",
"gender": "",
"address": "",
"AHL_TIN": ""
}
],
"remarks": "",
"field1": "",
"field2": ""
}
]
}

pg. 6
 BIS – State Scheme Integration

SAMPLE
• REQUEST

{
"ID_Type": "PDS",
"ID_Number": "202006833406",
"Token": "xyzx@xyzxyzxy&zxyzxxyzyxyxz",
"state_code": "20",
}

• RESPONSE
{
"header": {
"error_code": "200",
"error_msg": "SUCCESS",
"id_Type": "PDS",
"id_Number": "202006833406"
},
"details": [
{
"family_guid": "57a47540-db2c-4ea5-b1a6-40e5c0a80129",
"family_id": "57a47540-db2c-4ea5-b1a6-40e5c0a80129",
"state_lgd_code": "13",
"district_lgd_code": "614",
"subdistrict_lgd_code": "",
"village_town_lgd_code": "",
"rural_urban": "R",
"pincode": "798611",
"family": [
{
"family_mem_guid_id": "182885871",
"family_mem_id": "e4d7619f-72cd-40fd-b15d-45a4df0b0946",
"member_name_eng": "AVIHOLI SUMI",
"member_name_regional": "",
"father_name_eng": "HEKHI",
"father_name_regional": "",
"spouse_name_eng": "AHETO SUMI",
"spouse_name_regional": "AHETO SUMI",
"mother_name_eng": "ZUGHOLI",
"mother_name_regional": "",
"relation_name": "WIFE",
"gender": "F",
"mobile_number": "",
"year_of_birth": "1962",
"address": " STATION Road, RANCHI, Jharkhand ",
"ahl_TIN": "211309001000000000300081002"
},

{
"family_mem_guid_id": "183282199",
"family_mem_id": "eb79b8ac-c5c1-4d38-94b3-32b4c6df1cbd",
pg. 7
 BIS – State Scheme Integration

"member_name_eng": "NISUKA SUMI",

"member_name_regional": "",
"father_name_eng": "AHETO SUMI",
"father_name_regional": "",
"spouse_name_eng": "",
"spouse_name_regional": "",
"mother_name_eng": "AVIHOLI SUMI",
"mother_name_regional": "",
"relation_name": "SON",
"gender": "M",
"mobile_number": "",
"year_of_birth": "1995-00-00",
"address": "STATION Road, RANCHI, Jharkhand ",
"ahl_TIN": "2113090004540000000300081005"
}
],
"field1": "",
"field2": "",
"remarks": "",
"secc_HHD": "130900100040000000300081"
}
]
}

pg. 8