Employment Verification API

AI Tools

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.

The legacy data processing model is being formally deprecated.

In order to ensure continued compliance with the Digital Personal Data Protection Act, 2023 (DPDP Act), we are implementing DPDP V3 (Consent-Driven Processing). Under this framework, clients are required to obtain explicit, informed, and verifiable consent from the data principal prior to accessing, processing, viewing, or storing any personal data through the platform. This regulatory transition may require modifications to existing configurations and workflows. Clients are advised to review and update their implementations to ensure ongoing compliance with applicable data protection obligations. Further information regarding this transition can be enquired here. Learn more about this change here.

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

Info

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
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
String	name	Name of the reference	Required	v1
String	position	Designation of the reference	Required	v1
String	email	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
_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
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
_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" } }

Last updated on Feb 3, 2026