0% found this document useful (0 votes)
11 views

BetterPlace API-Version2.1

Uploaded by

tezauction
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
11 views

BetterPlace API-Version2.1

Uploaded by

tezauction
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 48

API DOCUMENT (Version 2.

1)

Restful Web Services


The services we are providing in this document are RESTful Web Services.

RESTful Web Services are REST architecture-based web services. In REST Architecture
everything is a resource. RESTful web services are light weight, highly scalable and maintainable
and are very commonly used to create APIs for web-based applications.

API Description

Our APIs supports JSON format for sending and receiving of data.

For all API’s call, you need to pass following parameters in request header.

Parameter Possible Values Description


Accept application/json Response format
Content-Type application/json Request format
apiKey - Your BetterPlace API Key

Available APIs

Sl. No. API Name Page No.


1 Create/Update Profile 2-8
2 Get Profile Status 8 – 10
3 Upload Attachment 10 - 11
4 Get Verification Status 12 - 18
5 Get All AskMore Requests 19 – 20
6 Respond To AskMore Request 21
7 Download Verification Report 21 - 22
8 Upload Profile Pic 22 – 23
9 Update Employee Status 23– 25
10 Push Notification 25 – 26
11 Create Entity Profile 26 – 28
12 PAN Verification 29
13 Employee Export (Push to Customer’s API) 30 – 34
14 Get Employee Data 34 – 39
15 Set Employee ID 39- 40
16 Manage Organization Location 40 – 42
17 Re-Verify Individual 42- 43
18 Download attachment 43
19 Create onboarding record 44

Sl. No. Error Messages Page No.


1 API Error Messages 45 – 48

1
API DOCUMENT (Version 2.1)

APIs

1) Create/Update Profile:

This API is for creating/updating the employee/tenant profile.

Resource url:
https://hostname/VishwasAPI/api/public/v3/createProfile/{referenceType}?referenceId={referenc
eId}&clientRefId={clientRefId}"

URL Parameters:
Field Length Mandatory Possible Values Format Description
referenceType - Yes employee, tenant or [A-Z, a-z] Association type
the custom type with the person
provided by BPSS
referenceId 20 Yes, if client Id not Numeric String [0-9] BPSS reference Id
passed (In case of for Profile
Update only)
clientRefId - Yes, if referenceId Alphanumeric String [A-Z, a-z, Client Refrence Id
not passed (In case 0-9] for Profile
of Update only)
Note - Once the profile is created successfully then the response gives back the reference id. The id needs to be stored for
future use. If Client is calling Update Profile API, referenceId or clientRefId is mandatory otherwise there is no need of
referenceId/clientRefId.

Sample url to create Profile: https://hostname/VishwasAPI/api/public/v2/createProfile/employee

Sample url to update Profile:


https://hostname/VishwasAPI/api/public/v3/createProfile/employee?referenceId=11111111111111
111111

Method Type: POST

Request JSON:

{
"action": "",
"consentTaken": "",
"consentAttachment": "",
"fName": "",
"lName": "",
"fatherName": "",
"motherName": "",
"husbandName":"",
"dob": "",
"yob": "",
"bloodGroup": "",
"gender": "",
"married": "",
"profession": "",
"location": "",
"conectionId": "",
"startDate": "",
"endDate": "",
"email": "",
"mobile": "",
"subscriptionCategory" : "",
"employeeType":"",
"employeeStatus" : "",
"kitNumber":"",
"subVendorDetails " : {
"referenceId" : "",
"name" : "","",
"docType" : "",
"docNo" : "",

2
API DOCUMENT (Version 2.1)

"website" : "",
"agencyEmployeeId" : ""
},
"vendorDetails" : {
"referenceId" : "",
"name" : "",
"docType" : "",
"docNo" : "",
"website" : "",
"agencyEmployeeId" : ""
},
"uan" : "",
"pfNumber" : "",
"esic" : "",
"jobFunction" : "",
"jobRole" : "",
"defaultSiteCode" : "",
"education": [
{
"action": "",
"educationType": "",
"courseName": "",
"startDate": "",
"endDate": "",
"clientRefId": ""
"college": "",
"university": "",
"passingYear": "",
"cgpaYgpa": "",
"clientRefId": ""
}
],
"documents": [
{
"action": "",
"name":"",
"docType": "",
"docNo": "",
"state": "",
"address": "",
"pincode": "",
"clientRefId": ""
}
],
"addresses": [
{
"action": "",
"addressType": "",
"line1": "",
"line2": "",
"locality": "",
"poName": "",
"city": "",
"landMark": "",
"district": "",
"state": "",
"pincode": "",
"same": "",
"clientRefId": ""
}
],
"workHistory": [
{
"action": "",
"name": "",
"startDate": "",
"endDate": "",
"location": "",
"position": "",
"employeeId": "",
"clientRefId": ""
}
]
}

3
API DOCUMENT (Version 2.1)

Field Length Mandatory Possible Values Format Description


action - NO CREATE, UPDATE - Profile action: create
profile (CREATE) or
update existing profile
(UPDATE)
consentTaken - YES true, false - Consent taken
consentAttachment - NO PDF/Image File (In data:mimeType; Eg. (data:image/png;
Base64 format) base64String dfdf212eqsdasd24==)

fName - YES [A-Z,a-z, .] - First Name


lName - NO [A-Z,a-z, .] - Last Name
fatherName - NO [A-Z,a-z, .] - Father Name
motherName - NO [A-Z,a-z, .] - Mother Name
husbandName - NO [A-Z,a-z, .] - Husband Name
dob - NO - dd-mm-yyyy Date of birth
yob - NO - yyyy Year
bloodGroup - NO OP, ON, AP, AN, - Blood Group
ABP, ABN, BP, BN
gender - NO MALE, FEMALE, - Gender
OTHERS
profession - NO - - Profession
location - YES - - Office location of
employee or city of
tenant
conectionId - NO - - Employee ID or Tenant
ID
startDate - NO - dd-mm-yyyy Employee/Tenant
joined date
endDate - NO - dd-mm-yyyy Employee/Tenant left
date
email - NO - - E-mail
mobile 10 NO [0-9] - Mobile Number

married - NO UNKNOWN, - Marital Status


MARRIED, SINGLE,
DIVORCED,
SEPARATED,
WIDOW_WIDOWER
subscriptionCategory - NO - - Subscription Category
employeeType - NO CONTRACTOR or - Employee Type
SUB_CONTRACTOR
or EMP_PART_TIME
or EMP_FULL_TIME
kitNumber - NO - - Kit number of Bank
employeeStatus - NO HIRED, PRE_HIRE - Status of the employee

uan - NO - - UAN of the employee

pfNumber - NO - - PF number of the


employee
esic - NO - - ESIC of the employee

jobFunction - NO - - Maintained job


function for the
employee

4
API DOCUMENT (Version 2.1)

jobRole - NO - - Maintained job role for


the employee
additionalAddressCRC No Additional Add for CRC

defaultSiteCode - NO - - Default site code for


the employee
agencyDetails - NO - Refer the Agency details
agencyDetails
table below
education - NO - Refer the Education
education table
below
documents - NO - Refer the Documents
documents
table below
addresses - NO - Refer the Addresses
addresses table
below
workHistory - NO - Refer the Work Histories
workHistory
table below

documents
Field Length Mandatory Possible Values Format Description
action - NO CREATE, UPDATE, - Document action:
DELETE create document
(CREATE) or update
existing document
(UPDATE) or delete
existing document
(DELETE)
docType - YES PAN, - Document Type
DRIVING_LICENCE,
VOTER_ID,
AADHAR, RC,
BANK_ACCOUNT
docNo - YES [0-9, A-Z, a-z, .] - Document Number
name - NO - - Name on document
address Yes If pincode passed Address on Document
pincode Yes If address passed Pincode of the address
clientRefId - NO - - Unique Client
Reference Number
state - If docType is - - State for which
DRIVING_LICENCE/VOTER_I Document belongs
D then YES, else No
bankName - If docType is - - Name of the bank. This
BANK_ACCOUNT then YES field is only for
BANK_ACCOUNT
document
ifsc - If docType is - - IFSC code of the bank.
BANK_ACCOUNT then YES This field is only for
BANK_ACCOUNT
document

5
API DOCUMENT (Version 2.1)

addresses
Field Length Mandatory Possible Values Format Description
action - NO CREATE, - Address action: create
UPDATE, address (CREATE) or update
DELETE existing address (UPDATE)
or delete existing address
(DELETE)
addressType - YES PRESENT, - Address Type
PERMANENT
line1 - YES if same is false - - Address Line1
line2 - NO - - Address Line2
locality - NO - - Locality
poName - NO - - Post office Name
city - YES if same is false - - City
landMark - NO - - Landmark
district - NO - - District
state - YES if same is false - - State
pincode 6 YES if same is false [0-9] - Pincode/Zipcode
same * - NO true, false Same as current/permanent
address
latitude No Latitude Of address
longitude No Longitude Of address
clientRefId - NO _ _ Unique Client Reference
Number
*Note: If the current address is same as permanent address then in current address same field should be true and if the
permanent address is same as current address then in permanent address same field should be true. It doesn't allow you to
make the same field true in both addresses. And also, it doesn't allow you to pass the address with same fieldtrue if the
other address itself not there.

workHistory
Field Length Mandatory Possible Format Description
Values
action - NO CREATE, - Work History action: create
UPDATE, workHistory (CREATE) or update
DELETE existing workHistory (UPDATE) or
delete existing workHistory (DELETE)
name - YES [A-Z, a-z, .] - Employer Name
startDate - YES - dd-mm-yyyy Work Start Date
endDate - NO - dd-mm-yyyy Work End Date
location - YES - - Location of Work
position - YES - - Position of Work
employeeId - NO - - Employee ID
clientRefId - NO - - Unique Client Reference Number

education
Field Length Mandatory Possible Format Description
Values
action - NO CREATE, - Education action: create
UPDATE, education (CREATE) or
DELETE update existing education
(UPDATE) or delete existing
education (DELETE)

6
API DOCUMENT (Version 2.1)

educationType - YES TENTH, - Education Type


TWELVE,
GRADUATION,
PG, DIPLOMA,
PHD
courseName - YES - - Course Name
startDate - NO - dd-mm- Course Start Date
yyyy
endDate - NO - dd-mm- Couse End Date
yyyy
college - YES [A-Z, a-z, .] - College Name
university - YES [A-Z, a-z, .] - University Name
passingYear 4 NO - - Year of Passing
cgpaYgpa - NO - - CGPA/YGPA
clientRefId - NO - - Unique Client Reference
Number

agencyDetails
Field Length Mandatory Possible Values Format Description
referenceId - NO [A-Z, a-z, .] - Reference ID of
the agency which
is created as an
entity
name - YES if - - Name of the
referenceId agency
and document
info not passed
docType - NO PAN, TAN, TIN, - Document type of
LICENCE, ROC, the agency
BANK_ACCOUNT,
SERVICE_TAX
docNo - NO - - Document number
of the agency
website - YES if - - Website of the
referenceId agency
and document
info not passed
agencyEmployeeId - NO - - Employee ID of
the employee
associated to
agency

Response JSON:
{
"data": {
"name": "",
"referenceId": "",
"report": ""
},
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]

7
API DOCUMENT (Version 2.1)

Field Length Possible Values Format


Data - - Refer data table below
Messages - Array of messages Refer messages table below

data
Field Length Possible Values Format Description
name - - - Name of the employee/tenant
referenceId 20 [0-9, -] - Reference ID of the employee/tenant.
Client needs to store this ID for future
use (eg. Update Profile, Get
Verification Status, Upload Document
Attachment, Get Profile Status etc.)
report - - -

Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

2) Get profile status:

This API is for getting the profile status of your employee/tenant.

Resource Url:
https://hostname/VishwasAPI/api/public/v2/getProfileStatus/{referenceType}?refIdType={idType}

URL Parameters:
Field Length Mandatory Possible Values Format Description
referenceType - Yes employee, tenant or the A-Z Association type
custom type provided by with the person
BPSS
refIdType No client, bpss (default) Reference Id type

Sample url: https://hostname/VishwasAPI/api/public/v2/getProfileStatus/employee


Method Type: POST

[
{ "id": ""},
{ "id": ""}
]

Request JSON:

Field Length Mandatory Possible Values Format


id 20 YES [0-9, -] -

8
API DOCUMENT (Version 2.1)

Response JSON:

{
"data": [
{
"name": "",
"referenceId": "",
"report": {
"basic": "", "",
"education":
"address": "", "",
"documents":
"work": "",
"family": "",
"contact": "",
"social": "",
"health": "",
"basicVerified": "",
"addressVerified": "",
"educationVerified": "",
"documentsVerified": "",
"workVerified": "",
"familyVerified": "",
"contactVerified": "",
"socialVerified": "",
"healthVerified": ""
}
}
], "messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

Field Length Possible Values Format Description


name - [A-Z, a-z, .] - Name of
Employee/Tenant
referenceId 20 [0-9, -] - Reference ID of
Employee/Tenant
report - - Refer report Report
table below

Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

report
Field Length Possible Values Format Description
basic - true, false - Basic Profile Status
address - true, false - Address Available or Not
education - true, false - Education Available or Not
documents - true, false - Document Available or Not
work - true, false - Work History Available or Not
family - true, false - Family Available or Not
contact - true, false - Contact Available or Not
social - true, false - Social Profile Available or Not
health - true, false - Health Profile Available or Not

9
API DOCUMENT (Version 2.1)

basicVerified - Refer Verification - Profile Verification Status


Status below
addressVerified - Refer Verification - Address Verification Status
Status below
educationVerified - Refer Verification - Education Verification Status
Status below
documentsVerified - Refer Verification - Document Verification Status
Status below
workVerified - Refer Verification - Work History Verification Status
Status below
familyVerified - Refer Verification - Family Verification Status
Status below
contactVerified - Refer Verification - Contact Verification Status
Status below
socialVerified - Refer Verification - Social Profile Verification Status
Status below
healthVerified - Refer Verification - Health Verification Status
Status below

Verification Status:
• NOT_VERIFIED: Profile item not picked for verification.
• IN_PROCESS: Item picked for verification and it is in process.
• VERIFIED: Item verified successfully.
• RED_CASE: Item failed in verification because of discrepancy.
• PARTIALLY_VERIFIED: Item failed in verification because of discrepancy.
• NOT_VERIFIABLE: Item is not verifiable.
• CANCELLED: Item verification is cancelled.
• NO_RESPONSE: No response for police verification.

3) Upload Attachment :

This API is for uploading scanned document for your employee/tenant.

Resource url :
https://hostname/VishwasAPI/api/public/v2/uploadAttachment?referenceType={referenceType}&r
eferenceId={referenceId}&refIdType={refIdType}&docType={docType}&docNo={docNo}&clientRefNo
={clientRefNo}"

URL Parameters:

Url Variable Mandatory Possible values Description


referenceType YES employee, tenant, linkOrg Reference Type
(employee/tenant/linkOrg)
referenceId YES [0-9, -] Reference ID of the employee/tenant
refIdType No Client, bpss (default) ReferenceId type
docType YES if PAN, DRIVING_LICENCE, Type of the Document for which the
clientRefNo not VOTER_ID, AADHAR, RC attachment is for
passed
docNo YES if - Number of the Document for which
clientRefNo not the attachment is for
passed

10
API DOCUMENT (Version 2.1)

clientRefNo NO - Unique Client Reference Number


profile items (Document,Address,
ducaton.. etc)

Sample url :
https://hostname/VishwasAPI/api/public/v2/uploadAttachment?referenceType=employee&referen
ceId=5545858827148077&docType=PAN&docNo=111111145564&clientRefNo=12345
Method Type: POST

Javascript example:

var formData = new FormData();


var fileKey = 0;
$formObj.find("input[type='file']").each(function(){
var $file = $(this);
$.each($file.get(0).files, function(key, value){
formData.append(fileKey, value);
fileKey++;
});
});
$.ajax({
url:"/VishwasAPI/api/public/v2/uploadAttachment?referenceType=employee&referenceId=554
5858827148077&docType=PAN&docNo=111111145564",
type: 'POST',
headers: { 'apiKey': '' },
data: formData,
mimeType:"multipart/form-data",
cache: false,
contentType : false,
processData : false,
dataType : "json",
success: function(data, textStatus, jqXHR){
},
error: function(jqXHR, textStatus, errorThrown){
}
});

Response JSON

{
"data":"",
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

11
API DOCUMENT (Version 2.1)

4) Get verification status:

This API is for getting verification status of your employee/tenant.

Resource url :
https://hostname/VishwasAPI/api/public/v2/getVerificationStatusExt/{referenceType} ?
withProofList ={proofList}&refIdType={refIdType}

URL Parameters:
Field Length Mandatory Possible Values Format Description
referenceType - Yes employee, tenant or A-Z Association type with the
the custom type person
provided by BPSS
refIdType No client, bpss (default) - Reference Id type

withProofList No true, false (default) - Flag for response with proof

Note: We’ve added new query parameter withProofList instead of withVerificationProofs which gives the proof
list for each verification items. Using the id of the proof user can download the proof using our new Download
Attachment API. So, usage of withVerificationProofs parameter is deprecated.

Sample url: https://hostname/VishwasAPI/api/public/v2/getVerificationStatusExt/employee

Method Type: POST

Request JSON

[
{ "id": ""},
{ "id": ""}
]

Field Length Mandatory Possible Values Format


id 20 YES [0-9, -] -

Response JSON

{
"data": [
{
"name": "",
"referenceId": "",
"dataEntryRequestedOn": "",
"dataEntryCompletedOn": "",
"clientStatus": "",
"bpssStatus": "",
"result": {
"DOCUMENT": {
"result": {
"PAN": [
{
"detail": "",
"status": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {
"verificationProofList": [
{
"id": "",
"itemId": "",

12
API DOCUMENT (Version 2.1)

"fileName": "",
"mimeType": "",
"type": ""
}
]
}
}
]
}
"clientStatus": "",
" bpssStatus": "",
},
"CRIMINAL": {
"result": {
"POLICE_VERIFICATION": [
{
"detail": "",
"status": "",
"subStatus": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}
}
],
"COURT_RECORD": [
{
"detail": "",
"status": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {
"result": {
"HIGH_COURT": [
{
"state": "",
"name": "",
"caseType": "",
"caseNo": "",
"caseDate": "",
"remark": "",
"district": "",
"addressType": "",
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}
}
],
"DISTRICT_COURT": [
{
"state": "",
"name": "",
"caseType": "",
"caseNo": "",
"caseDate": "",
"remark": "",
"district": "",
"addressType": "",

13
API DOCUMENT (Version 2.1)

"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}
],
"SUPREME_COURT":[
{
"state": "",
"name": "",
"caseType": "",
"caseNo": "",
"caseDate": "",
"remark": "",
"district": "",
"addressType": "",
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}
]
}
}
}
]
},
"clientStatus": "",
"bpssStatus": "",
},
"WORK_HISTORY": {
"result": {
"Employer Name": [
{
"detail": "",
"status": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}
}
]
},
"clientStatus": "",
"bpssStatus": ""
},
"ADDRESS": {
"result": {
"CURRENT_ADDRESS": [
{
"detail": "",
"status": "",
"remark": "",
"requestedOn": "",
"completedOn": "",

14
API DOCUMENT (Version 2.1)

"moreDetails": {
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}
}
],
"PERMANENT_ADDRESS": [
{
"detail": "",
"status": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}]
}
}
}
]
},
"clientStatus": "",
"bpssStatus": "",
}
"HEALTH": {
"result": {
"HEALTH_CHECK": [
{
"detail": "",
"status": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {
"verificationProofList": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
],
"dexterityAndStrength": "",
"histryCntgusOrInfectusDisease": "",
"empChest": "",
"isBlindLeft": "",
"hearingNormalRemark": "",
"remarkLeft": "",
"isVerifiedFlatFoot": "",
"isVerifiedRightSight": "",
"isVerifiedHistOfDisease": "",
"isVerifiedKnockKnee": "",
"knockKnee": "",
"histryOfDiseaseRemark": "",
"isVerifiedHight": "",
"isBlindRight": "",
"flatFootRemark": "",
"isVerifiedChest": "",
"remarkRight": "",
"flatFoot": "",
"isVerifiedDextAndStngth": "",
"isVerifiedLeftSight": "",
"empWeight": "",

15
API DOCUMENT (Version 2.1)

"knockKneeRemark": "",
"hearingNormal": "",
"empHeight": "",
"verificationProofs": "",
"isVerifiedWeight": "",
"dexterityAndStrengthRemark": "",
"isVerifiedHearNormal": "",
}
}
]

},

"clientStatus": "VERIFIED",
"bpssStatus": "VERIFIED"
},

"CREDIT": {
"result": {
"CREDIT_CHECK": [{
"detail": "",
"status": "",
"subStatus": "",
"remark": "",
"requestedOn": "",
"completedOn": "",
"moreDetails": {}
}]
},
"clientStatus": "VERIFIED",
"bpssStatus": "VERIFIED"
}
}

],
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

'moreDetails' possible response for documents


Key Fields given in values
PAN dob, name, verificationProofList(id, itemId, fileName,
mimeType, type)
DRIVING_LICENCE dob, state, issuedOn, validFrom, validTill, address, pincode,
bloodGroup, commercialLicenseNo, verificationProofList(id,
itemId, fileName, mimeType, type)
AADHAAR dob, issuedOn, address, pincode, verificationProofList(id,
itemId, fileName, mimeType, type)
VOTER_ID dob, address, pincode, verificationProofList(id, itemId,
fileName, mimeType, type)
RC dob, owner, vehicleName, taxUpto, motorClass,
registeredDate, expiryDate,
address, pincode, manufacturingDate, chassisNo, engineNo,
fuelType, vehicleColour, validityOfFitnessCertificate,
expiryOfFitnessCertificate, validityOfRoadTax, noOfSeats,
manufacturer, verificationProofList(id, itemId, fileName,
mimeType, type)
LICENCE licenceType, validFor, validFrom, validTill,
verificationProofList(id, itemId, fileName, mimeType, type)

16
API DOCUMENT (Version 2.1)

BANK_ACCOUNT bankName, branch, ifsc, verificationProofList(id, itemId,


fileName, mimeType, type)
TIN cstNumber, state, issuedOn, address, pincode,
verificationProofList(id, itemId, fileName, mimeType, type)
TAN Pannumber, address, pincode, verificationProofList(id,
itemId, fileName, mimeType, type)
ROC rocType, state, issuedOn, address, pincode,
verificationProofList(id, itemId, fileName, mimeType, type)
SERVICE_TAX address, pincode, verificationProofList(id, itemId,
fileName, mimeType, type)
HEALTH_CHECK dexterityAndStrength, histryCntgusOrInfectusDisease,
empChest, isBlindLeft, hearingNormalRemark, remarkLeft,
isVerifiedFlatFoot, isVerifiedRightSight,
isVerifiedHistOfDisease, isVerifiedKnockKnee, knockKnee,
histryOfDiseaseRemark, isVerifiedHight, isBlindRight,
flatFootRemark, isVerifiedChest, remarkRight, flatFoot,
isVerifiedDextAndStngth, isVerifiedLeftSight, empWeight,
knockKneeRemark, hearingNormal, empHeight,
isVerifiedWeight, dexterityAndStrengthRemark,
isVerifiedHearNormal, verificationProofList(id, itemId,
fileName, mimeType, type)
Verification Status:
• PENDING: Item picked for verification and it is in process.
• VERIFIED: Item verified successfully.
• RED_CASE: Item failed in verification because of discrepancy.
• PARTIALLY_VERIFIED: Item failed in verification because of discrepancy.
• NOT_VERIFIABLE: Item is not verifiable.
• CANCELLED: Item is cancelled.
• NO_RESPONSE: No response for police verification.

Verification Sub Status (Right now supported only for Police Verification):
• DOCUMENT_SUBMITTED: Document submitted for PVC process.
• ACKNOWLEDGEMENT_RECEIVED: Acknowlegment received from the Police station.

Field Length Possible Values Format Description


name - [A-Z, a-z, .] - Name of
Employee/Tenant
referenceId 20 [0-9, -] - Reference ID of
Employee/Tenant
dataEntryRequestedOn - - dd-mm-yyyy Data entry requested on
hh:mm:ss date
dataEntryCompletedOn - - dd-mm-yyyy Data entry completed
hh:mm:ss on date
report - - Refer report Report
table below

Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

17
API DOCUMENT (Version 2.1)

Report
Field Length Possible Values Format Description
DOCUMENT - PAN, - Under DOCUMENT detail
DRIVING_LICENCE, indicates the document
VOTER_ID, AADHAR, number and status indicates
RATION, RC its verification status
ADDRESS - CURRENT_ADDRESS, - Under ADDRESS detail will
PERMANENT_ADDRESS have full address and status
indicates its verification
status. MoreDetails will give
verification proofs details as
mentioned in document
moreDetails section above.
EDUCATION - TENTH, TWELVE, - Under EDUCATION detail will
GRADUATION, PG, have course name and status
DIPLOMA, PHD indicates its verification
status. MoreDetails will give
verification proofs details as
mentioned in document
moreDetails section above.
WORK_HISTORY - Employer Name - Under WORK_HISTORY detail
will have position and status
indicates its verification
status. MoreDetails will give
verification proofs details as
mentioned in document
moreDetails section above.
HEALTH - HEALTH_CHECK - Under Health detail will have
some details and status
indicates its verification
status. MoreDetails will give
verification proofs and other
details as mentioned in health
moreDetails section section.
CRIMINAL - POLICE_VERIFICATION, - Under CRIMINAL detail will
COURT_RECORD have some details and status
indicates its verification
status. MoreDetails will give
verification proofs details as
mentioned in document
moreDetails section above.
CREDIT - CREDIT_CHECK - Under CREDIT detail indicates
the verification status of
CREDIT CHECK.

18
API DOCUMENT (Version 2.1)

5) Get ask more requests:

This API is for get ask more requests of your employee/tenant. Ask more requests will be
created when the provided details are not sufficient for verification or for data entry. This url
supports askMoreRequestId as optional query parameter, if you pass this then api will return ask more
request for given id else api will return all pending ask more request.

Resource Url:
https://hostname/VishwasAPI/api/public/v2/getAllAskMoreRequests?id={askMoreRequestId}

Method Type: GET

Url Variable Mandatory Possible values Description


id NO [0-9, -] Ask more request id

Response JSON

{
"data": [
{
"name": "",
"referenceId": "",
"referenceType": "",
"report": [
{
"remark": "",
"id": "",
"type": "",
"subType": "",
"subValue": ""
},
{
"remark": "",
"id": "",
"type": "",
"subType": "",
"subValue": ""
}
]
}
],
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

Field Length Possible Values Format Description


name - [A-Z, a-z, .] - Name of
Employee/Tenant
referenceId 20 [0-9, -] - Reference ID of
Employee/Tenant
referenceType - Employee, tenant - Reference type
(employee or
tenant)
report - - Refer report Report
table below

19
API DOCUMENT (Version 2.1)

Field Length Possible Values Description


Remark contains what extra
remark - - details needed for verification
in text
ID of verification item. Later
id 20 [0-9, -] Client will have to pass this ID
when sending a response for
this request.
Document, address,
type - education, workHistory, Type of verification
courtRecord,
policeVerification
If type is Document then
PAN, TAN, TIN, LICENCE,
ROC, BANK_ACCOUNT,
SERVICE_TAX,
DRIVING_LICENCE,
VOTER_ID, AADHAR, RC,
BANK_ACCOUNT

subType - If type is address then Sub Type of verification.


Present, permanent

If type is education then


TENTH, TWELVE,
GRADUATION, PG, DIPLOMA,
PHD

If type is workHistory then


Employer Name
If type is Document
thenDocument number
subValue - If type is address then Details of verification item.
Full address details
If type is education then
Course name
If type is workHistory then
Employee id

Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

20
API DOCUMENT (Version 2.1)

6) Respond to ask more request:

This API is for the client to send a response for a particular ask more request.

Resource url:
https://hostname/VishwasAPI/api/public/v2/respondToAskMoreRequest/{id}?remark={remark}

(id – ID of verification item of ask more request, remark - mandatory; should contain the additional info that
was requested in the ask more request instance for which this response is being given.)

Sample
url:https://hostname/VishwasAPI/api/public/v2/respondAskMoreRequest/522533756342438351?re
mark=responding text

* Note : No need to send any data in the body.

Method Type: GET

Response example (response sent by this API):


{
"data": true,
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

Messages
Field Length Possible Values Format
type - SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

7) Download verification report:

This API is to download the verification report of your employee/tenant.

Resource Url:
https://hostname/VishwasAPI/api/public/v2/downloadVerificationReport/{referenceType}/{refere
nceId}?refIdType={idType}

URL Parameters:
Field Length Mandatory Possible Values Format Description
referenceType - Yes employee, tenant or the A-Z Association type
custom type provided by BPSS with the person
referenceId - Yes BPSS/Client Reference ID [0-9]/[A-Z,
a-z,0-9]
refIdType - No client, bpss (Default) - Reference ID
Type

21
API DOCUMENT (Version 2.1)

Sample url:
https://hostname/VishwasAPI/api/public/v2/downloadVerificationReport/employee/845548754875
11545554

Method Type: GET

Response: PDF File

8) Upload Profile Pic:

This API is for uploading profile picture for your employee/tenant.

Resource Url:
https://hostname/VishwasAPI/api/public/v2/uploadProfilePic?referenceType={referenceType}&ref
erenceId={referenceId}&clientRefId={clientRefId}

URL Parameters:
Field Length Mandatory Possible Values Format Description
referenceType - Yes employee, tenant or A-Z Association type
the custom type with the person
provided by BPSS
referenceId 20 Yes if client Id not Numeric String [0-9] BPSS reference Id
passed for Profile
clientRefId - Yes if referenceId Alphanumeric String [A-Z, a- Client Refrence Id
not passed z, 0-9] for Profile

Sample
Url:https://hostname/VishwasAPI/api/public/v2/uploadProfilePic?referenceType=employee&refere
nceId=5545858827148077

Method Type: POST

Javascript example:

var formData = new FormData();


var fileKey = 0;
$formObj.find("input[type='file']").each(function(){
var $file = $(this);
$.each($file.get(0).files, function(key, value){
formData.append(fileKey, value);
fileKey++;
}); });
$.ajax({
url:"/VishwasAPI/api/public/v2/uploadProfilePic?referenceType=employee&referenceId=5545858827148077",
type: 'POST',
headers: { 'apiKey': '' },
data: formData,
mimeType:"multipart/form-data",
cache: false,
contentType : false,
processData : false,
dataType : "json",
success: function(data, textStatus, jqXHR){
},
error: function(jqXHR, textStatus, errorThrown){
}
});

22
API DOCUMENT (Version 2.1)

Response JSON

{
"data":"",
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

09) Employee Status Update:

This API is to update the status of employee. This API will not be applicable for tenants and
other referenceTypes.

Resource url: https://hostname/VishwasAPI/api/public/v2/updateEmployeeStatus/{referenceType


}/{referenceId}?refIdType={idType}

URL Parameters:

Field Length Mandatory Possible Values Format Description


referenceType - Yes employee, tenant or A-Z Association type
the custom type with the person
provided by BPSS
referenceId Yes BPSS or Client [0-9]
Reference ID
refIdType - No client, bpss (Default) - Reference ID Type

Sample url: https://hostname/VishwasAPI/api/public/v2/updateEmployeeStatus/employee


/11111111111111111111

Method Type: POST

Request JSON:
{
"newStatus" : "",
"location" : "",
"employeeId" : "",
"designation" : "",
"joinedDate" : "",
"relievedDate" : "",
"comment" : "",
"commentRank" : ""
}

23
API DOCUMENT (Version 2.1)

Field Length Mandatory Possible Values Format Description


newStatus - YES HIRED, PRE_HIRE, - Status of employee
TERMINATED to be changed
location - NO - - Location of the
employee
employeeId - NO - - Employee ID
designation - YES if - - Employee
employee designation
status
changing from
PRE_HIRE to
HIRED
joinedDate - YES if - dd-mm-yyyy Employee joined
employee date
status
changing from
PRE_HIRE to
HIRED
relievedDate - YES if - dd-mm-yyyy Employee relieved
employee date
status
changing from
HIRED to
TERMINATED
comment - YES if - - Comment for
employee employee
status
changing from
HIRED to
TERMINATED
commentRank - YES if GOOD, BAD, - Comment rank for
employee AVERAGE employee
status
changing from
HIRED to
TERMINATED

Response JSON:
{
"data": "",
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}

Field Length Possible Values Format


data - true, false -
messages - Array of messages Refer
messages
table below

24
API DOCUMENT (Version 2.1)

Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

10) Push Notification:

This will give you the notification whenever the subscribed section of verification request got
closed or any ask more request got created. This API contains the information of verification
(referenceId and referenceType) which got closed, status (old and new) etc. and as well as if any ask
more request got created (askMoreRequestId, subSection). To save this data you have to create the
service which can receive the data in the format shown below. And provide this service information
like URL, authentication details for us. If the notification type is of ask more request then you will
get the askMoreRequestId which you can pass in the Get ask more requests API to get that ask more
request details.

This will give the data in the format(JSON) shown below:

{
"referenceId" : "",
"referenceType" : "",
"section" : "",
"subSection":"",
"oldStatus" : "",
"subStatus" : "",
"newStatus" : "",
"notificationType":"",
"clientReferenceId":"",
"askMoreRequestId":"",
}

Field Length Possible Values Format Description

referenceId 20 [0-9, -] - Reference ID of


Employee/Tenant

clientReferenceId - [A-Z, 0-9] - Unique client reference


ID of Employee/Tenant

referenceType - - - Reference type


section - PROFILE, DOCUMENT, ADDRESS, EDUCATION, - Section completed
EMPLOYEE, CRIMINAL
subSection - PAN, AADHAR, RATION, DRIVING_LICENCE, - Type of the item for
VOTER_ID, RC, LICENCE, BANK_ACCOUNT, which ask more request
OTHERS, CURRENT_ADDRESS, created.
PERMANENT_ADDRESS, ANY_ONE_ADDRESS,
COURT_RECORD, POLICE_VERIFICATION,
CRIMINAL_DB, TENTH, TWELVE, GRADUATION,
PG, DIPLOMA, PHD

oldStatus - PENDING, VERIFIED, RED_CASE, - Status of the


PARTIALLY_VERIFIED, NOT_VERIFIABLE, verification request
NO_RESPONSE, CANCELLED before completion.

25
API DOCUMENT (Version 2.1)

newStatus - PENDING, VERIFIED, RED_CASE, - New status of the


PARTIALLY_VERIFIED, NOT_VERIFIABLE, verification request
NO_RESPONSE, CANCELLED
subStatus - DOCUMENT_SUBMITTED, Sub Status of
ACKNOWLEDGEMENT_RECEIVED verification
(Right now supported Only for
PVC)

notificationType - VERIFICATION, ASKMORE_REQUEST - Type of notification

askMoreRequestId - [0-9, -] Reference id of the ask


more request created

11) Create/Update Entity Profile:

This API is for creating/updating the entity profile.

Resource Url:
https://hostname/VishwasAPI/api/public/v2/createEntityProfile/{referenceType}?referenceId={ref
erenceId}&clientRefId={clientRefId}

URL Parameters:
Field Length Mandatory Possible Values Format Description
referenceType - Yes linkOrg or the custom A-Z Association type
type provided by BPSS with the Organiztn
referenceId 20 Yes, if client Id not Numeric String [0-9] BPSS reference Id
passed (In Case of for Profile
Update only)
clientRefId - Yes, if referenceId Alphanumeric String [A-Z, a- Client Refrence Id
not passed (In Case z, 0-9] for Profile
of Update only)
Note - Once the profile is created successfully then the response gives back the reference id. The id needs to be stored for
future use. If Client is calling Update Profile API, referenceId or clientRefId is mandatory otherwise there is no need of
referenceId/clientRefId.

Sample url to create Profile:


https://hostname/VishwasAPI/api/public/v2/createEntityProfile /{linkOrg}

Sample url to update Profile:


https://hostname/VishwasAPI/api/public/v2/createEntityProfile/linkOrg?referenceId=11111111111
111111111

Method Type: POST

Request JSON:
{
"name": "",
"aliasName": "",
"organizationType": "",
"organizationClass": "",
"conectionId": "",
"location": "",
"startDate": "",
"endDate": "",
"website": "",
"phone": "",

26
API DOCUMENT (Version 2.1)

"subscriptionCategory" : "",
"documents": [
{
"docType": "",
"docNo": "",
"licenceType": ""
}
],
"addresses": [
{
"addressType": "",
"line1": ",
"line2": "",
"locality": "",
"poName": "",
"city": "",
"landMark": "",
"district": "",
"state": "",
"pincode": ""
}]}

Field Mandatory Possible Values Format Description


name YES [A-Z, a-z, .] - Name of the entity
aliasName NO [A-Z, a-z, .] - Alias name of the
entity
organizationType YES COMPANY, HOTEL, - Type of the entity
COLLEGE, UNIVERSITY,
SCHOOL, BOARD
organizationClass YES PROPRIETORSHIP, - Class of the entity
PARTNERSHIP, LLP,
PVT_LTD_COMPANY
conectionId NO - - Connection ID of
the entity
location YES - - Location of the
entity
startDate NO - dd-mm-yyyy Connection start
date
endDate NO - dd-mm-yyyy Connection end
date
website NO - - Website of the
entity
phone NO - - Phone number of
the entity
subscriptionCategory NO - - Subscription
category
documents NO - Refer the Documents of the
documents entity
table below
addresses NO - Refer the Addresses of the
addresses entity
table below

documents
Field Length Mandatory Possible Values Format Description
docType - YES PAN, TAN, TIN, - Document Type
LICENCE, ROC,

27
API DOCUMENT (Version 2.1)

BANK_ACCOUNT,
SERVICE_TAX, GST
docNo - YES [0-9, A-Z, a-z, .] - Document Number
licenceType - If docType is LICENCE - - Type of the LICENCE. This
then YES, else No field is only for
LICENCEdocument
bankName - If docType is - - Name of the bank. This
BANK_ACCOUNT then YES field is only for
BANK_ACCOUNTdocument
ifsc - If docType is - - IFSC code of the bank.
BANK_ACCOUNT then YES This field is only for
BANK_ACCOUNTdocument

addresses
Field Length Mandatory Possible Values Format Description
addressType - YES HEADOFFICE, - Address Type
ADDITIONAL
line1 - YES - - Address Line1
line2 - NO - - Address Line2
locality - NO - - Locality
poName - NO - - Post office Name
City - YES - - City
landMark - NO - - Landmark
district - NO - - District
state - YES - - State
pincode 6 YES [0-9] - Pincode/Zipcode

Response JSON:
{
"data": {
"name": "",
"referenceId": "",
"report": ""
},
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}]
}

Field Length Possible Values Format


Data - - Refer data table below
Messages - Array of messages Refer messages table below

data
Field Length Possible Values Format Description
name - - - Name of the entity
referenceId 20 [0-9, -] - Reference ID of the entity. Client needs
to store this ID for future use (eg.
Update Profile, Get Verification Status,
Upload Document Attachment, Get
Profile Status etc.)
clientRefId - [A-Z, 0-9] - Client reference ID of employee, tenant
report - - - -

28
API DOCUMENT (Version 2.1)

12) PAN Verification:

This API is to verify PAN.

Resource url: https://hostname/VishwasAPI/api/public/v2/panVerification/{panNo}

Sample url: https://hostname/VishwasAPI/api/public/v2/panVerification/PIUPY6997D

Method Type: GET

Response JSON:

{
"data":
{
"statusCode": "1",
"panNumber": "PIRRY3422D ",
"panstatus": "E",
"lastName": "YELA",
"firstName": "KUMAR",
"middleName":,"",
"panTitle": "Shri",
"lastUpdateDate": "28/11/2012",
"message": "Record found in PAN database."
},
"messages": [ ]
}

Field Length Possible Values Format


data - - -
messages - Array of messages Refer messages
table below

Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

Field Possible Description


Values
E Existing and Valid PAN
F Fake PAN
panstatus D PAN Deleted
N Record (PAN) Not Found in ITD
Database/Invalid PAN
1 Success
statusCode 422 Validation Error
110 Source Not Available

29
API DOCUMENT (Version 2.1)

13) Employee Export (Push to Customer’s API):

To receive details of employees entered in the BPSS system into their own HR/ERP system
via Push mode, Customers can implement a HTTPs POST method that accepts a JSON format
Request body as defined below, expose it, and register its end-point URL and API Authentication
Key with BPSS.

The BPSS system will then call the registered API using HTTPs POST to send employee details
to the customer’s system whenever an employee profile entry for that Customer is completed in
the BPSS system through any channel - UI input, Excel Upload or API call.

The Request Body (JSON) format:

{
"empReportingName": "",
"empFirstName": "",
"empLastName": "",
"mobile": "",
"email": "",
"dob": "",
"yob": "",
"gender": "",
"maritalStatus": "",
"religion": "",
"nationality": "",
"bloodGroup": "",
"identificationMark": "",
“referenceId”:””,
"empId": "",
"jobFunction": "",
"jobRole": "",
"designation": "",
"employeeStatus": "",
"employeeType": "",
"vendorId": "",
"vendorEmpId": "",
"location": "",
"joinedOn": "",
"relievedOn": "",
"uan": "",
"pfNo": "",
"esic": "",
"defaultSite": "",
"familyMembers": [{
"familyMemberName": "",
"relation": "",
"mobile": "",
"dob": "",
"valid": "",
"dependent": "",
"emergency": "",
"nominee": ""
}],
"documents": [
{ "docType": "",
"docNo": "",
"nameOnDoc": "",
"attachments": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]
}

],

30
API DOCUMENT (Version 2.1)

"addresses": [
{
"addressType": "",
"line1": "",
"line2": "",
"locality": "",
"poName": "",
"city": "",
"landMark": "",
"district": "",
"state": "",
"country": "",
"pincode": "",
"attachments": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}
]

}
],
"empAddDetails": {
"empHeight": "",
"empWeight": "",
"empChest": "",
"nominee1": {
"familyMemberName": "",
"relation": "",
"mobile": "",
"dob": "",
"valid": "",
"dependent": "",
"emergency": "",
"nominee": ""
},
"nominee1Percentage": "",
"nominee1Remark": "",
"blindLeft": "",
"farSightForLeft": "",
"nearSightForLeft": "",
"remarkLeft": "",
"blindRight": "",
"farSightForRight": "",
"nearSightForRight": "",
"remarkRight": "",
"knockKnee": "",
"knockKneeRemark": "",
"flatFoot": "",
"flatFootRemark": "",
"hearingNormal": "",
"hearingNormalRemark": "",
"dexterityAndStrength": "",
"dexterityAndStrengthRemark": "",
"histryCntgusOrInfectusDisease": "",
"histryOfDiseaseRemark": "",
"empPreferreLanguage": ""
}
}

Field Format Description


empReportingName - Employee reporting name
empFirstName - Employee first name
empLastName - Employee last name
dob [YYYY-MM-DD] Date of birth

31
API DOCUMENT (Version 2.1)

yob [yyyy] Year of birth


gender [MALE, FEMALE, Gender
OTHERS]
maritalStatus [ UNKNOWN, Marital status
MARRIED, SINGLE,
DIVORCED,
SEPARATED,
WIDOW_WIDOWER]
religion [ Hinduism, Religion
Muslim,
Christianity,
Sikhism, Buddhism,
Jainism, Other]
nationality [Indian, Nationality
Bangladeshi,
Nepali, Other]
bloodGroup [OP, ON, AP, AN, Blood group
ABP, ABN, BP, BN]
identificationMark - Identification mark
referenceId - BPSS employee reference ID
empId - Employee ID
jobFunction - Job function
jobRole - Job role
designation - Designation
employeeStatus HIRED, PRE_HIRE Status of employee
CONTRACTOR,
employeeType SUB_CONTRACTOR, Type of employment
EMP_PART_TIME,
EMP_FULL_TIME
vendorId - Vendor ID
vendorEmpId - Vendor employee ID
location - Location
joinedOn [YYYY-MM-DD] Joined on date
relievedOn [YYYY-MM-DD] Relieved on date
uan - UAN number
pfNo - PF number
esic - ESIC number
defaultSite - Default site to employee
familyMembers Array Refer Family Member table below
documents Array Refer Documents table above
addresses Array Refer Addresses table above

Attachments (For Documents and Address sections)


Field Format Description Possible values
id [0-9] Attachment ID -
itemId [0-9] Profile item id -
fileName - File name of the -
attachment
mimeType - Mime type of the -
attachment
type - Type attachement PROFILE, VERIFICATION

32
API DOCUMENT (Version 2.1)
Documents
Field Format Description
doctype [AADHAR, PAN, RC, Document Type
DRIVING_LICENCE,
VOTER_ID]
docNo - Document number
nameOnDoc - Name on document
attachments - Attachments. Refer
attachments table
below for details.

Addresses
Field Format Description
addressType [PRESENT, PERMANENT] Address Type
line1 - Door Number
line2 - Street
Locality - Locality
poName - Post Office
city - City
landMark - Landmark
district - District
State - State
Country - Country
Pincode [0-9] Pincode
attachments - Attachments. Refer
attachments table
below for details.

Family Member
Field Format Description
familyMemberName - familyMemberName
relation - Relation
mobile [0-9] Mobile
dob [YYYY-MM-DD] DOB
valid {true/false} Valid
dependent {true/false} Dependent
emergency {true/false} Emergency
Nominee {true/false} Nominee

Emp Additional Details


Field Format Description
empHeight [0-9] Emp height in kg
empWeight [0-9] Emp weight in cm
empChest [0-9] Emp chest in cm
nominee1 Array Refer Family Member table
below
nominee1Percentage [0-9] First nominee percentage
nominee1Remark - First nominee remark
nominee2 Array Refer Family Member table
below
nominee2Percentage [0-9] Second nominee percentage

33
API DOCUMENT (Version 2.1)

nominee2Remark - Second nominee remark


nominee3 Array Refer Family Member table
below
nominee3Percentage [0-9] Third nominee percentage
nominee3Remark - Third nominee remark
blindLeft {true/false} Blind left eye
farSightForLeft - Far sight for left eye details
nearSightForLeft - Near sight for left eye details
remarkLeft - Remarks for left eye
blindRight {true/false} Blind right eye
farSightForRight - Far sight for right eye details
nearSightForRight - Near sight for right eye details
remarkRight - Remarks for right eye
knockKnee {true/false} Knock knee
knockKneeRemark - Knock knee remark
flatFoot {true/false} Flat foot
flatFootRemark - Flat foot remark
hearingNormal {true/false} Hearing normal
hearingNormalRemark - Hearing normal remark
dexterityAndStrength {true/false} Dexterity and strength
dexterityAndStrengthRemark - Dexterity and strength remark
histryCntgusOrInfectusDisease {true/false} History of contagious infectious
disease
histryOfDiseaseRemark - History of contagious infectious
disease remark
empPreferreLanguage [ ENGLISH] Emp Preferred language

14) Get Employee Data:

This API is to get employee data - Reporting name, Job function, Job role, Default site, IDs,
etc.

Resource url:
https://{hostname}/VishwasAPI/api/profile/v2/getEmpData?idType={idType}&idNo={idNo}

Sample url:
https://{hostname}/VishwasAPI/api/profile/v2/getEmpData?idType=AADHAR&idNo=9635687412
35

Method Type: GET


Field Mandatory Format Description
idType Yes [REFERENCE_ID, EMP_ID, AADHAR, ID Type
PAN, DRIVING_LICENCE, VOTER_ID, RC]
idNo Yes - ID No
Note: REFERENCE_ID - BPSS reference ID for the employee record,
EMP_ID – Customer-specified Employee ID of the employee.

Response JSON:
{
"data": {
"empReportingName": "",
"empFirstName": "",
"empLastName": "",
"dob": "",
"yob": "",
"gender": "",
"maritalStatus": "",
"religion": "",

34
API DOCUMENT (Version 2.1)
"nationality": "",
"bloodGroup": "",
"identificationMark": "",
"referenceId": "",
"empId": "",
"jobFunction": "",
"jobRole": "",
"designation": "",
"employeeStatus": "",
"employeeType": "",
"vendorId": "",
"vendorEmpId": "",
"location": "",
"joinedOn": "",
"relievedOn": "",
"uan": "",
"pfNo": "",
"esic": "",
"defaultSite": "",
"familyMembers": [{
"familyMemberName": "",
"relation": "",
"mobile": "",
"dob": "",
"valid": "",
"dependent": "",
"emergency": "",
"nominee": ""
}],
"addresses": [
{
"addressType": "",
"line1": "",
"line2": "",
"locality": "",
"poName": "",
"city": "",
"landMark": "",
"district": "",
"state": "",
"country": "",
"pincode": "",
"attachments": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}

},
],
"documents": [
{
"docType": "",
"docNo": "",
"nameOnDoc": "",
"attachments": [
{
"id": "",
"itemId": "",
"fileName": "",
"mimeType": "",
"type": ""
}

}
],
"empAddDetails": {
"empHeight": "",
"empWeight": "",
"empChest": "",
"nominee1": {
"familyMemberName": "",
"relation": "",

35
API DOCUMENT (Version 2.1)

"name": "",
"mobile": "",
"dob": "",
"valid": "",
"dependent": "",
"emergency": "",
"nominee": ""
},
"nominee1Percentage": "",
"nominee1Remark": "",
"nominee2": ""
"nominee2Percentage": "",
"nominee2Remark": "",
"nominee3": "",
"nominee3Percentage": "",
"nominee3Remark": "",
"blindLeft": "",
"farSightForLeft": "",
"nearSightForLeft": "",
"remarkLeft": "",
"blindRight": "",
"farSightForRight": "",
"nearSightForRight": "",
"remarkRight": "",
"knockKnee": "",
"knockKneeRemark": "",
"flatFoot": "",
"flatFootRemark": "",
"hearingNormal": "",
"hearingNormalRemark": "",
"dexterityAndStrength": "",
"dexterityAndStrengthRemark": "",
"histryCntgusOrInfectusDisease": "",
"histryOfDiseaseRemark": "",
"empPreferreLanguage": ""
}
},
"messages": []
}

Field Length Possible Values Format


data - - Refer data table
below
messages - Array of messages Refer messages table
below

data
Field Format Description
empReportingName - Employee reporting name
empFirstName - Employee first name
empLastName - Employee last name
dob [YYYY-MM-DD] Date of birth
yob [yyyy] Year of birth
gender [MALE, FEMALE, OTHERS] Gender
maritalStatus [ UNKNOWN, MARRIED, Marital status
SINGLE, DIVORCED,
SEPARATED,
WIDOW_WIDOWER]

36
API DOCUMENT (Version 2.1)

religion [ Hinduism, Muslim, Religion


Christianity, Sikhism,
Buddhism, Jainism, Other]
nationality [Indian, Bangladeshi, Nationality
Nepali, Other]
bloodGroup [OP, ON, AP, AN, ABP, Blood group
ABN, BP, BN]
identificationMark - Identification mark
referenceId - BPSS employee reference ID
empId - Employee ID
jobFunction - Job function
jobRole - Job role
designation - Designation
employeeStatus HIRED, PRE_HIRE Status of employee
CONTRACTOR,
employeeType SUB_CONTRACTOR, Type of employment
EMP_PART_TIME,
EMP_FULL_TIME
vendorId - Vendor ID
vendorEmpId - Vendor employee ID
location - Location
joinedOn [YYYY-MM-DD] Joined on date
relievedOn [YYYY-MM-DD] Relieved on date
uan - UAN number
pfNo - PF number
esic - ESIC number
defaultSite - Default site to employee
familyMembers Array Refer Family Member table below
documents Array Refer Documents table below
addresses Array Refer Addresses table below
empAddDetails Array Refer Emp Additional Details table below

Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

Documents
Field Format Description
doctype [AADHAR, PAN, RC, Document Type
DRIVING_LICENCE, VOTER_ID,
OTHERS]
docNo - Document number
nameOnDoc - Name on
document
attachments - Attachments.
Refer attachments
table below for
details.

37
API DOCUMENT (Version 2.1)
Emp Additional Details
Field Format Description
empHeight [0-9] Emp height in kg
empWeight [0-9] Emp weight in cm
empChest [0-9] Emp chest in cm
nominee1 Array Refer Family Member table
below
nominee1Percentage [0-9] First nominee percentage
nominee1Remark - First nominee remark
nominee2 Array Refer Family Member table
below
nominee2Percentage [0-9] Second nominee percentage
nominee2Remark - Second nominee remark
nominee3 Array Refer Family Member table
below
nominee3Percentage [0-9] Third nominee percentage
nominee3Remark - Third nominee remark
blindLeft {true/false} Blind left eye
farSightForLeft - Far sight for left eye details
nearSightForLeft - Near sight for left eye details
remarkLeft - Remarks for left eye
blindRight {true/false} Blind right eye
farSightForRight - Far sight for right eye details
nearSightForRight - Near sight for right eye details
remarkRight - Remarks for right eye
knockKnee {true/false} Knock knee
knockKneeRemark - Knock knee remark
flatFoot {true/false} Flat foot
flatFootRemark - Flat foot remark
hearingNormal {true/false} Hearing normal
hearingNormalRemark - Hearing normal remark
dexterityAndStrength {true/false} Dexterity and strength
dexterityAndStrengthRemark - Dexterity and strength remark
histryCntgusOrInfectusDisease {true/false} History of contagious infectious
disease
histryOfDiseaseRemark - History of contagious infectious
disease remark
empPreferreLanguage - Emp Preferred language

Addresses
Field Format Description
addressType [PRESENT, PERMANENT] Address Type
line1 - Door Number
line2 - Street
Locality - Locality
poName - Post Office
city - City
landMark - Landmark
district - District
State - State
Country - Country
Pincode [0-9] Pincode
attachments - Attachments. Refer
attachments table below
for details.

38
API DOCUMENT (Version 2.1)

Attachments (For Documents and Address sections)


Field Format Description Possible values
id [0-9] Attachment ID -
itemId [0-9] Profile item id -
fileName - File name of -
the attachment
mimeType - Mime type of -
the attachment
type - Type PROFILE, VERIFICATION
attachement

Family Member
Field Format Description
familyMemberName - familyMemberName
relation - Relation
mobile [0-9] Mobile
dob [YYYY-MM-DD] DOB
valid {true/false} Valid
dependent {true/false} Dependent
emergency {true/false} Emergency
Nominee {true/false} Nominee

15) Set Employee ID:

This API is to set the Employee ID for an employee record that is already created in BPSS
system, and is identified by the values of ID Type & ID No fields in the Request body.

If the ID Type and ID No. combination to not identify an employee record belonging to the caller,
the Employee ID will not be set and an error message will be returned.

Resource url: https://{hostname}/VishwasAPI/api/profile/v2/setEmpId

Method Type: POST

Request JSON:

{
"empId":"EM8901",
"idType":"AADHAR",
"idNo":"78946513012"
}

Field Mandatory Format Description


empId Yes - Employee ID
idType Yes [REFERENCE_ID, ID Type
AADHAR, PAN,
DRIVING_LICENCE,
VOTER_ID, RC]
idNo Yes - ID No

39
API DOCUMENT (Version 2.1)

Response JSON:

{
"data": "{Success Message}",
"messages":
[
{
"message": null,
"type": null,
"errorCode": null
}
]
}

Field Possible Values Format


Data Success Message -
Messages Array of messages Refer
messages
table below

Field Possible Values


Type INFO, WARN, SUCCESS, ERROR
message -
errorCode Refer Error Messages Section

16) Manage Organization Location:

This API is to manage organization location.

Resource url: https://{hostname}/VishwasAPI/api/public/v2/manageOrgLocation

Method Type: POST

Request JSON:

{
"action": "",
"location": "",
"address":"",
"oldLocation": ""

Field Mandatory Possible Values Description


action Yes CREATE, UPDATE, DELETE Action for Location
location Yes Any String Name of Location
address No Any String Address of location
oldLocation Yes only in case of Any String Old name of location
update action

Response JSON:

{
"data":"true/false",
"messages": []
}

40
API DOCUMENT (Version 2.1)

Field Possible Values Format


Data true/false -
Messages Array of messages Refer
messages
table below

Field Possible Values


Type INFO, WARN, SUCCESS, ERROR
message -
errorCode Refer Error Messages Section

Create Location Sample:

Request JSON:

{
"action":"CREATE",
"location":"Jodhpur",
"address":"259/5, 1 st Cross, Shastri Nagar, Jodhpur",
"oldLocation":""
}

Response JSON:

{
"data":"true",
"messages": [
{
"type": "SUCCESS",
"message": "Location created successfully.",
"errorCode": ""

}
]
}

Update Location Sample:

Request JSON:

{
"action":"UPDATE",
"location":"Chennai",
"address":"259/5, 1 st Cross, Shastri Nagar, Chennai",
"oldLocation":"Jodhpur"
}

Response JSON:

{
"data":"true",
"messages": [
{
"type": "SUCCESS",
"message": "Location updated successfully.",
"errorCode": ""

}
]
}

41
API DOCUMENT (Version 2.1)

DELETE Location Sample:

Request JSON:

{
"action":"DELETE",
"location":"Delhi",
"address":"",
"oldLocation":""
}

Response JSON:

{
"data":"false",
"messages": [
{
"type": "ERROR",
"message": "Location not found.",
"errorCode": "3508"

}
]
}

17) Re-Verify Individual: This API is for Re-Verify any verification which is requested earlier.

Resource url: https://{hostname}/VishwasAPI/api/public/v2/reverifyIndividual

Method Type: POST

Request JSON:

{
"clientReferenceNumber": "",
"bpssReferenceNumber":"",
"referenceType": "",
"subscription":"",
"document": {
"panCard": true/false,
"aadhaarCard": true/false,
"drivingLicence": true/false,
"licence": true/false,
"voterId": true/false,
"bankAccount": true/false,
"rc": true/false
},
"courtRecordCheck": true/false,
"databaseCheck": true/false,
"education": {
"tenth": true/false,
"twelfth": true/false,
"graduation": true/false,
"pg": true/false,
"phd": true/false,
"diploma": true/false
},
"address": {
"current": true/false,
"permanent": true/false
},
"health": true/false,
"pvc": true/false,
"bankKyc": {
"initiate": true/false,
"dualDeclaration": true/false,
"vernacularDeclaration": true/false,
"vernacularLanguage": ""
}

42
API DOCUMENT (Version 2.1)

Field Mandatory Possible Values Description


clientReferenceNumber No - Your employee/db reference ID of
(If bpssReferenceNumber is passed) the person
bpssReferenceNumber No Number only BPSS reference ID
(If clientReferenceNumber is passed)
referenceType Yes employee/tenant Your relationship type with person
subscription No Any String Verification category name
Other Fields are No true/false Specify true if re-verification
Verification Type needed for any type

Response JSON:

{
"data":"true/false",
"messages": []
}

18) Download attachment:

This API is to download the attachments (Profile or Verification Proof).

Resource url:
https://{hostname}/VishwasAPI/api/public/v2/downloadAttachment?id={id}&itemId={itemI
d}&type={type}

Method Type: GET


URL Parameters:

Field Mandatory Format Description Possible values


id Yes [0-9] Attachment ID -
itemId Yes [0-9] Profile item id -
type Yes - Type PROFILE, VERI_ITEM,
attachement VERI_SECTION, VERI_CRC

Response: Attachment File

43
API DOCUMENT (Version 2.1)

19) Create onboarding record:

This API is to create onboarding record.

Resource url: https://hostname/VishwasAPI/api/public/v2/createOnboardingRecord

Method Type: POST

Request JSON:
{
"clientReferenceId": "",
"location": "",
"referenceType": "",
"subscriptionCategory": ""
}

Field Length Possible Values Format


data - Please refer “Data -
Format” table
messages - Array of messages Refer messages table
below

Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -

Field Length Mandatory Possible Values Format


clientReferenceId - YES - -
location - YES - -
referenceType - YES - -
subscriptionCategory - NO - -

Response JSON:

{
"data":{
"bpssReferenceId": "",
"clientReferenceId":"",
},
"messages": []
}

Data Format
Field Format Description
bpssReferenceId [0-9] Bpss reference id
clientReferenceId - Client reference id

44
API DOCUMENT (Version 2.1)

API Error Messages

Error Code Error Message


1001 API Key specified in HTTP is not valid. Please provide valid API Key.
1002 API Key in HTTP Header is mandatory. Please provide API key.
1003 API is not active
1004 Aadhaar Authenticate API is not enabled for you
1005 Profile status API is not enabled for you
1006 Upload document API is not enabled for you
1007 Verification status API is not enabled for you
1008 Profile creation API is not enabled for you
1009 AadhaarEkyc API is not enabled for you
1010 Getting All AskMore requests API is not enabled for you
1011 Respond to Askmore request API is not enabled for you
1012 Download report API is not enabled for you
1013 Upload Profile Pic API is not enabled for you
1014 Update employee status API is not enabled for you
1015 Entity Profile creation API is not enabled for you
1016 Aadhaar QrFp not enabled for you
1017 PANVerification not enabled for you
1018 You have reached maximum hit count for this API, please contact us.
2000 Please pass all the mandatory fields. For mandatory fields please refer the API
document
2001 Request body cannot be blank.
2002 Contact mandatory
2003 10 digits allowed in mobile number
2004 Only number allowed in mobile/phone number
2005 Not a valid email
2006 First name is mandatory
2007 Name is mandatory
2008 Mobile number is mandatory
2009 Location is mandatory
2010 Check the {Reference Type}’s startDate format
2011 Check the {Reference Type}’s endDate format
2012 Some address fields are mandatory
2013 Some work history fields are mandatory
2014 Mention address as either present or permanent
2015 State is mandatory for Driving License and Voter ID
2016 Check PAN Id format
2017 Check the date of birth format
2018 Check the education start date format
2019 Check the education end date format
2020 Check the work historystart date format
2021 Check the work historyend date format
2022 Education start date must not allowed to come after end date
2023 Education Type is mandatory
2024 College/School name is mandatory
2025 University name is mandatory
2026 Course name is mandatory
2027 Document type and number is mandatory
2028 Document type and number is already exist for some other person
2029 Blank spaces are not allowed in docNo
2030 Aadhaar number is not valid
2031 Mention dobType as date or year
2032 Education start date must not allowed to come after end date
2033 Can't upload the attachment
2034 ReferenceType and referenceIds cannot be blank

45
API DOCUMENT (Version 2.1)

2035 ReferenceType, referenceId, docType and docNo cannot be blank


2036 Remark is mandatory
2037 Request is in Awaiting State, So you can't download the report now
2038 ReferenceType and referenceId/clientRefId cannot be blank
2039 Attachment should be of image type
2040 AttachmentId cannot be blank
2041 Only one referenceId is allowed with verification proof
2042 Only 20 referenceIds is allowed in single request
2043 ReferenceType is not one of the value given in the API Document
2045 EmployeeStatus is not one of the value given in the API Document
2046 Employee active field is mandatory
2047 Can't change the employee status from PRE_HIRE to TERMINATED
2048 Can't change the employee status from HIRED to PRE_HIRE
2049 Can't change the status of TERMINATED employee
2050 Employee joinedDate and designation are mandatory fields
2051 Employee relievedDate, comment and commentRank are mandatory fields
2052 Can't update PRE_HIRE employee profile
2053 BankName and ifsc are mandatory for Bank Account Document
2054 Check the entity's startDate format
2055 Check the entity's endDate format
2056 Not a valid website
2057 Entity not found for this reference ID
2058 Mention address as either headOffice or additional
2059 LicenceType is mandatory for Licence Document
2060 Person's location is not one of the locations maintained for the Organization
2061 DocType {docType} is not one of the value given in the API Document
2062 Multiple current or permanent addresses are not allowed
2063 The field same in address should be true only for one address
2064 You can't use same field as true in this case
2065 Dob is mandatory if you are sending dobType
2066 DobType is mandatory if you are sending dob
2067 Unable to fetch Reference Type
2068 Aadhaar authentication limit exceeded
2069 Aadhaar data not found.
2070 Fingerprint is not captured for the given Aadhaar No.
2071 Can't connect to the given Host or API url .
2072 Reference type is mandatory.
2073 Employee type is mandatory.
2074 Employee statusis mandatory.
2075 Employee type is not one of the value given in the API Document.
2076 Subscription not found for this reference type, please subscribe first.
2077 Reference type not found.
2078 {Reference type} reference type is not allowed here.
2079 PAN number is not valid.
2080 Marital status is not one of the value given in the API Document.
2081 DOB/YOB is mandatory.
2082 Check the year of birth format.
2083 Person yet to born.
2084 Verified profile pic exists, So can not be updated.
2085 Client Ref No can not be duplicate
2086 No record found with the given client ref no
2087 Given client ref No is not for document
2088 Given doc number and clientRef number not matching
2089 Attachment is missing please attach file
2090 Profile action is not one of the value given in the document.
2091 Address action is not one of the value given in the document.

46
API DOCUMENT (Version 2.1)

2092 Education action is not one of the value given in the document.
2093 Document action is not one of the value given in the document.
2094 Work History action is not one of the value given in the document.
2095 ClientRefId {id} already exist.
2096 Agency details allowed only if the employee type is either contractor or sub
contractor.
2097 Agency not found for the given reference ID.
2098 Name and website or doc type and doc number are mandatory for agency.
2099 Website format is wrong for agency.
2100 Job function is mandatory if you are passing job role.
2101 Job role is mandatory if you are passing job function.
2102 Job role and function is doesn't exist.
2103 Reference ID is not allowed in profile create action.
2104 Profile record not found for the reference Id {id}.
2105 Client ref ID already exist. It should be unique per record.
2106 Profile record conflicts. Different profiles found from each unique ID passed.
2107 Document {details} already exist with some other profile.
2108 At least one unique ID required.
2109 Mobile number {mobile} already exist with some other profile.
2110 UAN already exist with some other profile.
2111 PF Number already exist with some other profile.
2112 UAN already exist with some other profile.
2113 PF Number already exist with some other profile.
2114 Profile not found from any unique ID passed, to update.
2115 Profile action is not one of the values given in the API Document.
2116 {Details} not found to re-open.
2117 {Details} not found to delete.
2118 Education {details} already exist in the profile to create.
2119 Education {details} not found in the profile to update/delete.
2120 Document {details} not found in the profile to update/delete.
2121 Work history {details} already exist in the profile to create.
2122 Work history {details} not found in the profile to update/delete.
2123 Delete action cannot be performed on Work history {details} since it is verified.
2124 Multiple employee records exist with connection ID {ID}.
2125 Another employee already exists with connection ID {ID}.
2126 Document already exist in the profile with referenceId: {ID}.
2127 Default site doesn't exist for given site code.
2128 Agency employee ID not allowed for the given agency.
2129 Pin code should be of 6 digits.
2130 BPSS reference id({bpssReferenceId}) should be in number format.
2131 Age should be greater than {Min Age}.
2132 Age should be between {min Age} and {max Age}.
2133 Job function role {function role name} not allowed for this subscription category
{category name}.
2134 Job function role is required for this subscription category {category name}.
2500 Re-Verify API is not enabled for you.
2501 ReferenceType is mandatory.
2502 BpssReferenceNumber or clientReferenceNumber is mandatory.
2503 Employee / Reference not found.
2504 Person not found for Re-Verify.
2505 Verification request not found for Re-Verify.
2506 Subscription not found for submitted data.
2507 Verification Item request not found for Re-Verify.
2508 Error in Re-Verify Individual.
2509 Consent policy should be accepted.
2510 Consent attachment not uploaded. Please upload proper file.

47
API DOCUMENT (Version 2.1)

2511 Consent attachment is not in correct format.


2512 Consent attachment mime type should be image or pdf.
3000 No person found
3001 You don't have any subscription to create verification request
3002 Verification request not found for this person
3003 {Employee type} not found for this reference Id
3004 {Reference type} not found for this reference Id
3005 Ask more request not found
3006 {Entity type} not found for this reference Id
3007 Biometric based authentication not allowed
3008 Verification request not found for {reference Id}.
3009 Verification request not found, data entry request is in pending for {reference Id}.
3500 Manage Location API is not enabled for you.
3501 Action field is mandatory.
3502 Wrong Action value passed.
3503 Location field is mandatory
3504 Old location is mandatory for UPDATE action.
3505 Given location already exists.
3506 Location already in use, so can’t be deleted.
3507 Given old location not found.
3508 Given location not found.
3521 Type field is mandatory.
3522 Id field is mandatory.
3523 ItemId field is mandatory.
3524 Wrong value for type.
3525 Attachment with given id not found.
3526 Not authorized to download attachment.
3527 No record found with given itemId.
3550 Record already in onboarding queue with given clientReferenceId.
3551 Subscription category not found.
3552 Organization location not found.
3553 Employee record already exist with given clientReferenceId.
3554 Reference record already exist with given clientReferenceId.
3555 Client reference id is mandatory.
3556 Location is mandatory.
3557 Subscription category is mandatory.
3558 Please provide valid Sub-Vendor details.
3559 Please provide valid Vendor details.
3560 There is no relation between Vendor Details and Sub-Vendor Details.
4000 Internal error occurred. Please contact BPSS Support.
5002 API Set Employee ID is not enabled for you.
5003 API Get Employee data is not enabled for you.
5100 Employee ID or Reference No is mandatory.
5125 ID type and ID number are mandatory.
5126 Employee ID is mandatory.
5127 Attendance log is not allowed for a future date/time.
5128 Employee ID is already assigned to another person.
5129 Assignment End Date should be greater than Start Date.
5130 Unable to record Approved Hours. Please add IN attendance log first.
5131 Invalid value given for ID Type.
5141 Multiple employees found for the given details. Please correct the data.
5142 Employee with given details data not found.

48

You might also like