Request Verification

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 at critical moments, such as onboarding new employees or during security checks. It also enables embedding a 'Verify' button within client portals, streamlining the verification process for end-users.

Use Cases

Automation Integration: Trigger identity verification automatically within workflows managed by automation tools like Zapier, Workato, 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/verification/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 employee’s email or username, used for login as specified in the employee directory	Yes	`[email protected]` / `johndoe123`
`loginHintType`	Defines the type of login hint. It must be `EMAIL` or `USERNAME`	Yes	`EMAIL`
`correlationId`	A unique employee 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",
    "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"
}