Request Verification (Candidates)

The Incode Workforce API allows clients to generate a verification link for identity verification processes through the a simple API call. This feature is particularly useful for integrating with automation tools to request identity verification during recruiting process. It also enables embedding a 'Verify' button within client portals, streamlining the verification process for candidates.

Use Cases

Automation Integration: Trigger identity verification automatically within workflows managed by automation or ATS tools like Workato, Greenhouse, or internal systems.
Client Portals: Embed the verification link in a 'Verify' button within client-facing applications, enabling seamless and user-initiated identity verification.
Security & Compliance: Automatically request identity verification at critical security checkpoints, ensuring compliance and enhancing security protocols.

To provide real-time updates on the progress of identity verification requests, Incode Workforce supports webhook notifications. When a verification is initiated through the generated verification link, the system will send webhook notifications to a pre-configured endpoint as the verification progresses through various stages. More information about webhooks can be found in the Webhook Notifications guide.

Step 1: Authorizing the Server

To authorize a server to request a verification for a user, you would need to get an authorization token via Authorize endpoint

cURL Example

curl --location 'https://{server-url}/v1/integration/authorize/server' \
--header 'x-api-key: 4115e33314e12c0effe540c74bac55937b65a448' \
--header 'Content-Type: application/json' \
--data '{
    "integrationId": "621cda6e-c7de-4ebd-9219-a137a84a5211",
    "secret": "supersecret"
}'

Response Example

{
    "token": "eyJhbGciOiJIUzI1NiJ9..."
}

The response contains a token, which is required for fetching verification data.

Token Validity

Validity Period: The token is valid for 15 minutes.
Multi-use: The token can be used for multiple result fetch requests within the validity period.

Step 2: Requesting a verification

Once you have the authorization token, you can use it to request a verification.

Endpoint

POST v1/workforce/verification/candidate/generate-verification-link

Headers

Header	Description	Required	Example Value
`x-auth-token`	This token is received in the authorize endpoint	Yes	`eyJhbGciOiJIUzI1NiJ9...`
`Content-Type`	Supported content type for this request is `application/json`	Yes	`application/json`

Request Parameters

Parameter	Description	Required	Example Value
`integrationId`	The integration ID, representing the unique identifier for the integration. The parameter is available on the Workforce Dashboard for a particular integration	Yes	`c0fd10ff-c36e-49a6-afde-a00496c1c8e7`
`secret`	A secret parameter for additional security. The parameter is available on the Workforce Dashboard for a particular integration under name Client Secret	Yes	`s3cureS3cr3tValue`
`loginHint`	The candidate's email or username, used for login	Yes	`[email protected]` / `johndoe123`
`loginHintType`	Defines the type of login hint. It must be `EMAIL` or `USERNAME`	Yes	`EMAIL`
`givenNames`	The candidate's given names, used for name matching vs name on government issued document.	Yes	`John`
`lastName`	The candidate's last name, used for name matching vs name on government issued document.	Yes	`Doe`
`correlationId`	A unique candidate identifier in the client's system, used for data matching	No	`abc-123-xyz`
`redirectUrl`	The URL to redirect the user after successful verification	No	`https://client-portal.com/success`
`validityMinutes`	The duration in minutes for which the verification link remains valid before expiring	No	`30` (default), `15` , `60` (Any positive number)

cURL Example

curl -X POST "https://{server-url}/v1/verification/generate-verification-link" \
-H "x-auth-token: eyJhbGciOiJIUzI1NiJ9..." \
-H "Content-Type: application/json" \
-d '{
    "integrationId": "c0fd10ff-c36e-49a6-afde-a00496c1c8e7",
    "secret": "s3cureS3cr3tValue",
    "loginHint": "[email protected]",
    "loginHintType": "EMAIL",
    "givenNames": "John",
    "lastName": "Doe"
    "correlationId": "abc-123-xyz",
    "redirectUrl": "https://client-portal.com/success",
    "validityMinutes": 30
}'

Response

Status Code: 200 OK

Success Response

{
  "verificationLink": "https://icd.sh/03ymltf",
  "verificationTraceId": "32hfu84e-we56-hg4d-1293-fwdd83yf3412"
}

Error Responses

Missing Required Parameter

Status Code: 400 Bad Request

{
  "error": "Missing required parameter: integration_id",
  "errorCode": "INVALID_PARAMETER_INTEGRATION_ID"
}

Invalid Login Hint Type

Status Code: 400 Bad Request

{
  "error": "Invalid login hint type. Accepted values are EMAIL or USERNAME.",
  "errorCode": "INVALID_LOGIN_HINT_TYPE"
}