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.

INTERESTED ?

To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.

Chat With Attestr Support

API Details

Request

TypeURL
POSThttps://api.attestr.com/api/{version}/public/factx/async/work

Request Header Parameters

TypeNameValue / DescriptionOptionalMin VersionMax Version
StringContent-Typeapplication/jsonRequiredv1
StringAuthorizationBasic {authToken}Requiredv1

If you do not have the authentication token, please refer to Register App to generate one.

Request Body Parameters

TypeNameDescriptionOptional (default)Min VersionMax Version
StringtagUnique employee Id / reference id to be passed by the clientRequiredv1
StringemployerName of the employerRequiredv1
StringregEmployee ID as registered with the employerRequiredv1
StringpositionDesignation / position last held by the candidateRequiredv1
StringstartDateStart date of employment DD-MM-YYYYRequiredv1
BooleanendedFlag indicating if the candidate has taken an exit or still employed with this organizationRequiredv1
StringendDateEnd date of employment, required if the ended flag is set as true DD-MM-YYYYConditionalv1
Array [String]documentsArray 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) APIRequiredv1
Array [Object]referencesIt it is required to perform reference verification, then this array should contain list of references to be verified. See Work Reference schema below.Optionalv1
BooleanwebhookBoolean flag to be used for triggering webhooks once record is updated. More details below.Optionalv1

Work Reference Item Schema

TypeNameDescriptionOptional (default)Min VersionMax Version
StringnameName of the referenceRequiredv1
StringpositionDesignation of the referenceRequiredv1
StringemailEmail if available, else set as nullOptionalv1
StringcontactMandatory, contact number of the referenceRequiredv1

Sample Request

JSON
Copy

Response Details

Http Status 200

KeyDescriptionTypeMin VersionMax Version
_idUnique request Id to be used later for querying the resultStringv1
numberUnique human readable number to be used for any reference laterStringv1
Employment Check Response
Copy

Querying Employment Check Result

Get Employment Async Request Outcome API

TypeURLMin VersionMax Version
GEThttps://api.attestr.com/api/{version}/public/async/<asyncId>v1

Request Header Parameters

TypeNameValue / DescriptionOptionalMin VersionMax Version
StringContent-Typeapplication/jsonRequiredv1
StringAuthorizationBasic {authToken}Requiredv1

Request URL Parameters

NameDescriptionMin VersionMax Version
asyncIdReplace <asyncId> in the URL with the _id received in the employment verification API response as described above.v1

Response

Http Status 200

KeyDescriptionTypeMin VersionMax Version
_idRequest Id as queried in the URLStringv1
numberRequest numberStringv1
requestIdUnique ID used by Attestr for request tracing purposesStringv1
statusStatus of the request. Possible values are - COMPLETED, INITIATED, ERROREDStringv1
inputThe input details used for verificationStringv1
outputWork check output object. Details described as below. Null if status is errored or initiated.WorkCheckOutputRecordv1
errorError object if the operation ran into errors, null otherwise. Null if status is completed or initiated.Stringv1
createdUnix timestamp when the request was placed.Numberv1
updatedUnix timestamp when the request was last updated. Null if status is initiated.Numberv1
signatureSignature generated using the output and client secret. Used for validating the accuracy of data. Null if status is errored or initiated.Stringv1

Work Check Output Record

KeyDescriptionTypeMin VersionMax Version
statusOne of Clear, Alert, False, MoreInfo, NoResultStringv1
modeMode of verification e.g Online, Offline, Physical, Email, Telephone etcStringv1
verifiedDate on which verified data was received from the employer. For online verification, it is the date on which verification was performed. DD-MM-YYYYDatev1
verifierName of the verifying employerStringv1
authorityName of the individual or department that verified the documentStringv1
descriptionDescription text provided by Attestr back office for each verification. This text is particularly useful for alert and false cases. HTML formatted string.Stringv1
documentsList of supporting verified letter, documents, email as received from the employerArray[String]v1
voiceRecordsFor 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 StreamArray[String]v1

Sample Output

JSON
Copy

Error Response

ParameterTypeDescription
codeNumberUnique error codes for different errors. Always available.
messageStringError message describing the error. Always Available.
detailsStringDetail error message. Available only for certain types of errors.

Error Codes

HTTP StatusError CodeError Message
4004001Malformed data or missing required parameter values
4004005Operation could not be performed due to low credits balance
4014016Invalid client authorization
4034031Unauthorized access
4034035Requested service is not provisioned for your account
4034039Client's IP address is not whitelisted
4034035Requested service is not provisioned for your account
4294291Maximum account rate limit exceeded
4294292Maximum API rate limit exceeded
4294293Maximum account daily limit exceeded
4294294Maximum API daily limit exceeded
5005001Request could not be processed

Sample Error Response

JSON
Copy

Webhooks

Work check supports the following two webhook events.

See Webhooks for more details on how to register webhooks.

  1. async.completed
  2. async.errored

To enable webhooks, the API input parameter webhook must be set as true while initiating the request.

Webhook Event Payload

KeyTypeDescriptionMin VersionMax Version
_idStringID of the async request. This is same as received in the output of Person / Business search API as described above.v1
requestIdStringUnique request ID for internal tracing purposes.v1
statusStringOne of INITIATED, COMPLETED OR ERROREDv1
outputObjectWork Check output record same as output key described in Querying Result API above.
errorObjectError object if the check runs into errors. The structure of this is same as the Error Response object described above.v1
signatureStringgenerated using hmacHexDigest of output object and client secret. Null if archived.

Sample Webhook Payload

JSON
Copy

INTERESTED ?

To start a chat, click the button below, and one of our available executives will assist you with questions about onboarding and commercials.

Chat With Attestr Support
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard