INTERESTED ?
Employment Verification API
Automate employee work verification with easy to integrate API
Introduction
Employment verification API is one among the suite of background check APIs offered by the Attestr Platform. This is an asynchronous API which accepts the work history as input. Once requested, the details are verified by our back office team in co-ordination with the concerned employer and the result is made available through API and webhooks offering an end to end automation.
To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.

API Details
Request
Type | URL |
---|---|
POST | https://api.attestr.com/api/{version} /public/factx/async/work |
Request Header Parameters
Type | Name | Value / Description | Optional | Min Version | Max Version |
---|---|---|---|---|---|
String | Content-Type | application/json | Required | v1 | |
String | Authorization | Basic {authToken} | Required | v1 |
If you do not have the authentication token, please refer to Register App to generate one.
Request Body Parameters
Type | Name | Description | Optional (default) | Min Version | Max Version |
---|---|---|---|---|---|
String | tag | Unique employee Id / reference id to be passed by the client | Required | v1 | |
String | employer | Name of the employer | Required | v1 | |
String | reg | Employee ID as registered with the employer | Required | v1 | |
String | position | Designation / position last held by the candidate | Required | v1 | |
String | startDate | Start date of employment DD-MM-YYYY | Required | v1 | |
Boolean | ended | Flag indicating if the candidate has taken an exit or still employed with this organization | Required | v1 | |
String | endDate | End date of employment, required if the ended flag is set as true DD-MM-YYYY | Conditional | v1 | |
Array [String] | documents | Array of supporting document Ids such as relieving letter, salary slips, offer letter etc. To generate document Ids, the documents must be uploaded using [Document Upload](Document Upload) API | Required | v1 | |
Array [Object] | references | It it is required to perform reference verification, then this array should contain list of references to be verified. See Work Reference schema below. | Optional | v1 | |
Boolean | webhook | Boolean flag to be used for triggering webhooks once record is updated. More details below. | Optional | v1 |
Work Reference Item Schema
Type | Name | Description | Optional (default) | Min Version | Max Version |
---|---|---|---|---|---|
String | name | Name of the reference | Required | v1 | |
String | position | Designation of the reference | Required | v1 | |
String | Email if available, else set as null | Optional | v1 | ||
String | contact | Mandatory, contact number of the reference | Required | v1 |
Sample Request
{
"tag": "ABCD1234",
"employer": "Radisson Blu Bengaluru",
"reg": "EMP-1234",
"position": "Trainee",
"startDate": "02-12-2019",
"ended": true,
"endDate": "19-03-2020",
"documents": [
"MX17Cd6KEBSsbKSaou"
],
"references": [
{
"name": "Akxxx xxxxxrni",
"position": "Mentor",
"email": "akxxxxk.xxx@gmail.com",
"contact": "+91 xxxx 61354"
},
{
"name": "Reddxxxx du",
"position": "Mentor",
"email": "bxxxxal.ccc@gmail.com",
"contact": "988xxxxx8"
}
],
"webhook": false
}
Response Details
Http Status 200
Key | Description | Type | Min Version | Max Version |
---|---|---|---|---|
_id | Unique request Id to be used later for querying the result | String | v1 | |
number | Unique human readable number to be used for any reference later | String | v1 |
{
"_id": "AR02zfeuv2iz5ksij09nf",
"number": "3801-575765-9695"
}
Querying Employment Check Result
Get Employment Async Request Outcome API
Type | URL | Min Version | Max Version |
---|---|---|---|
GET | https://api.attestr.com/api/{version}/public/async/<asyncId> | v1 |
Request Header Parameters
Type | Name | Value / Description | Optional | Min Version | Max Version |
---|---|---|---|---|---|
String | Content-Type | application/json | Required | v1 | |
String | Authorization | Basic {authToken} | Required | v1 |
Request URL Parameters
Name | Description | Min Version | Max Version |
---|---|---|---|
asyncId | Replace <asyncId> in the URL with the _id received in the employment verification API response as described above. | v1 |
Response
Http Status 200
Key | Description | Type | Min Version | Max Version |
---|---|---|---|---|
_id | Request Id as queried in the URL | String | v1 | |
number | Request number | String | v1 | |
requestId | Unique ID used by Attestr for request tracing purposes | String | v1 | |
status | Status of the request. Possible values are - COMPLETED, INITIATED, ERRORED | String | v1 | |
input | The input details used for verification | String | v1 | |
output | Work check output object. Details described as below. Null if status is errored or initiated. | WorkCheckOutputRecord | v1 | |
error | Error object if the operation ran into errors, null otherwise. Null if status is completed or initiated. | String | v1 | |
created | Unix timestamp when the request was placed. | Number | v1 | |
updated | Unix timestamp when the request was last updated. Null if status is initiated. | Number | v1 | |
signature | Signature generated using the output and client secret. Used for validating the accuracy of data. Null if status is errored or initiated. | String | v1 |
Work Check Output Record
Key | Description | Type | Min Version | Max Version |
---|---|---|---|---|
status | One of Clear, Alert, False, MoreInfo, NoResult | String | v1 | |
mode | Mode of verification e.g Online, Offline, Physical, Email, Telephone etc | String | v1 | |
verified | Date on which verified data was received from the employer. For online verification, it is the date on which verification was performed. DD-MM-YYYY | Date | v1 | |
verifier | Name of the verifying employer | String | v1 | |
authority | Name of the individual or department that verified the document | String | v1 | |
description | Description text provided by Attestr back office for each verification. This text is particularly useful for alert and false cases. HTML formatted string. | String | v1 | |
documents | List of supporting verified letter, documents, email as received from the employer | Array[String] | v1 | |
voiceRecords | For reference verification performed over the phone, this will contain voice recording media Ids and can be used for audit trail. To download these media using Id, refer to Get Media Stream | Array[String] | v1 |
Sample Output
{
"status": "Clear",
"documents": [
"MX1lLjcMNsrG_jA2nx"
],
"voiceRecords": null,
"description": "sample description",
"verifier": "AkXXX XXXXXarni",
"authority": "HR Head, XXXX Employer",
"verified": "04-02-2022",
"mode": "Email"
}
Error Response
Parameter | Type | Description |
---|---|---|
code | Number | Unique error codes for different errors. Always available. |
message | String | Error message describing the error. Always Available. |
details | String | Detail error message. Available only for certain types of errors. |
Error Codes
HTTP Status | Error Code | Error Message |
---|---|---|
400 | 4001 | Malformed data or missing required parameter values |
400 | 4005 | Operation could not be performed due to low credits balance |
401 | 4016 | Invalid client authorization |
403 | 4031 | Unauthorized access |
403 | 4035 | Requested service is not provisioned for your account |
403 | 4039 | Client's IP address is not whitelisted |
403 | 4035 | Requested service is not provisioned for your account |
429 | 4291 | Maximum account rate limit exceeded |
429 | 4292 | Maximum API rate limit exceeded |
429 | 4293 | Maximum account daily limit exceeded |
429 | 4294 | Maximum API daily limit exceeded |
500 | 5001 | Request could not be processed |
Sample Error Response
{
"code": 4001,
"message": "Malformed data or missing required parameter values"
}
Webhooks
Work check supports the following two webhook events.
See Webhooks for more details on how to register webhooks.
- async.completed
- async.errored
To enable webhooks, the API input parameter webhook must be set as true while initiating the request.
Webhook Event Payload
Key | Type | Description | Min Version | Max Version |
---|---|---|---|---|
_id | String | ID of the async request. This is same as received in the output of Person / Business search API as described above. | v1 | |
requestId | String | Unique request ID for internal tracing purposes. | v1 | |
status | String | One of INITIATED, COMPLETED OR ERRORED | v1 | |
output | Object | Work Check output record same as output key described in Querying Result API above. | ||
error | Object | Error object if the check runs into errors. The structure of this is same as the Error Response object described above. | v1 | |
signature | String | generated using hmacHexDigest of output object and client secret. Null if archived. |
Sample Webhook Payload
{
"event": "async.completed",
"payload": {
"_id": "AR0U643cotcGalyCTb",
"requestId": "ea1d5141-c32d-48ba-bef4-0a34b0ce1531",
"status": "COMPLETED",
"output": {
"status": "Clear",
"documents": null,
"voiceRecords": [
"MX1NTqvN4QUfyRzsDY"
],
"description": "We contacted Ossie Fernandes (Manager and the candidate's direct supervisor) working for the organization Marquis Beach Resort, Goa. As confirmed, the candidate Agassi Dsouza has been working in the capacity of a Waiter in the organization for last one year. According to the supervisor, he is a hardworking individual. He always reports to work on time and never ignored the management's orders. He used to finish his assignment in the time allotted. There have been no unfavourable remarks. No unethical or malpractises reported at work. Candidate is reported to be service the notice period. The salary details were not revealed. The status of the final work verification report is Green. The profile includes voice recordings of our chat with the Executive.",
"verifier": "Ossie Fernandes",
"authority": "Manager / supervisor",
"verified": "26-07-2022",
"mode": "Telephone"
},
"error": null,
"signature": "69f255d85d62c789e0936107490a6ae2d7d526812896d446e164ababe64b5293"
}
}
INTERESTED ?
To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.
