BetterPlace API-Version2.1
BetterPlace API-Version2.1
1)
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.
Available APIs
1
API DOCUMENT (Version 2.1)
APIs
1) Create/Update 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.
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)
4
API DOCUMENT (Version 2.1)
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)
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)
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 -
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
[
{ "id": ""},
{ "id": ""}
]
Request JSON:
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" : ""
}
]
}
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)
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 :
Resource url :
https://hostname/VishwasAPI/api/public/v2/uploadAttachment?referenceType={referenceType}&r
eferenceId={referenceId}&refIdType={refIdType}&docType={docType}&docNo={docNo}&clientRefNo
={clientRefNo}"
URL Parameters:
10
API DOCUMENT (Version 2.1)
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:
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)
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
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.
Request JSON
[
{ "id": ""},
{ "id": ""}
]
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" : ""
}
]
}
16
API DOCUMENT (Version 2.1)
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.
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)
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}
Response JSON
{
"data": [
{
"name": "",
"referenceId": "",
"referenceType": "",
"report": [
{
"remark": "",
"id": "",
"type": "",
"subType": "",
"subValue": ""
},
{
"remark": "",
"id": "",
"type": "",
"subType": "",
"subValue": ""
}
]
}
],
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}
19
API DOCUMENT (Version 2.1)
Messages
Field Length Possible Values Format
type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -
20
API DOCUMENT (Version 2.1)
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
Messages
Field Length Possible Values Format
type - SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -
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
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
Javascript example:
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 -
This API is to update the status of employee. This API will not be applicable for tenants and
other referenceTypes.
URL Parameters:
Request JSON:
{
"newStatus" : "",
"location" : "",
"employeeId" : "",
"designation" : "",
"joinedDate" : "",
"relievedDate" : "",
"comment" : "",
"commentRank" : ""
}
23
API DOCUMENT (Version 2.1)
Response JSON:
{
"data": "",
"messages": [
{
"message": "",
"type": "",
"errorCode" : ""
}
]
}
24
API DOCUMENT (Version 2.1)
Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -
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.
{
"referenceId" : "",
"referenceType" : "",
"section" : "",
"subSection":"",
"oldStatus" : "",
"subStatus" : "",
"newStatus" : "",
"notificationType":"",
"clientReferenceId":"",
"askMoreRequestId":"",
}
25
API DOCUMENT (Version 2.1)
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.
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": ""
}]}
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" : ""
}]
}
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)
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": [ ]
}
Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -
29
API DOCUMENT (Version 2.1)
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.
{
"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": ""
}
}
31
API DOCUMENT (Version 2.1)
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
33
API DOCUMENT (Version 2.1)
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
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": []
}
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)
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)
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
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.
Request JSON:
{
"empId":"EM8901",
"idType":"AADHAR",
"idNo":"78946513012"
}
39
API DOCUMENT (Version 2.1)
Response JSON:
{
"data": "{Success Message}",
"messages":
[
{
"message": null,
"type": null,
"errorCode": null
}
]
}
Request JSON:
{
"action": "",
"location": "",
"address":"",
"oldLocation": ""
Response JSON:
{
"data":"true/false",
"messages": []
}
40
API DOCUMENT (Version 2.1)
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": ""
}
]
}
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)
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.
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)
Response JSON:
{
"data":"true/false",
"messages": []
}
Resource url:
https://{hostname}/VishwasAPI/api/public/v2/downloadAttachment?id={id}&itemId={itemI
d}&type={type}
43
API DOCUMENT (Version 2.1)
Request JSON:
{
"clientReferenceId": "",
"location": "",
"referenceType": "",
"subscriptionCategory": ""
}
Messages
Field Length Possible Values Format
Type - INFO, WARN, SUCCESS, ERROR -
message - - -
errorCode - Refer Error Messages Section -
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)
45
API DOCUMENT (Version 2.1)
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)
48