Fetch Verification Results

The Fetch Verification Result endpoint allows clients to retrieve detailed verification data for a specific identity verification process conducted within Incode Workforce. This process works best when used in combination with webhooks since verification events are asynchronous. When the client's server receives a successful verification event via webhook, it only receives the verification trace id. The client’s server must then use this verification trace id to fetch the verification details by making a request with the server token obtained from the authorization endpoint.

This webhook-based approach allows clients to react to real-time verification events efficiently and securely fetch additional details only when needed.

Use Cases

Onboarding & HR Automation: Fetch verification results after receiving a webhook event to confirm employee identity before granting access.
Security & MFA Authentication: Retrieve identity verification details for workforce authentication before allowing system or facility access.
Risk-Based Access Control: Fetch verification results to determine if additional authentication steps are needed based on risk assessment.

Step 1: Authorizing the Server

To authorize a server to fetch verification data, 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: Fetching Verification Data

Once you have the authorization token, you can use it to retrieve verification details.

Scopes and Data Mapping

Scopes determine the data returned and are set up at the organization level for each client. The available scopes and the corresponding data they return are as follows:

Scope	Data Returned
IDENTITY_ID	Unique identity ID (always included)
NAME	Full name, first name, last name
DATE_OF_BIRTH	Date of birth (UNIX timestamp in milliseconds)
PHONE	Phone number (E.164 format, e.g., `+12014825099`)

Endpoint

GET /v1/verification/details/{verification_id}

Headers

Header	Description	Required	Example Value
`x-auth-token`	This token is received in the authorize endpoint	Yes	`eyJhbGciOiJIUzI1NiJ9...`

Request Parameters

To fetch verification data, make a GET request to the following endpoint, where verification_id is provided via webhook that notifies you about successful verification and the data snapshot. Data snapshot matches the scopes set up on the organization leve.

cURL Example

curl --location 'https://{server-url}/v1/verification/details/55a951eb-265c-4706-9ebf-99ae35c745ab' \
--header 'x-auth-token: eyJhbGciOiJIUzI1NiJ9...'

Response

Status Code: 200 OK

Success Response

{
    "id": "55a951eb-265c-4706-9ebf-99ae35c745ab",
    "projectId": "ad30fbcb-a41c-465b-a9d3-f245ab418b18",
    "traceId": "46cb353b-5b3b-4de9-9676-9b2d5d081027",
    "verifiedAt": 1730481625983,
    "status": "VERIFIED",
    "scopes": ["DATE_OF_BIRTH"],
    "data": {
        "dateOfBirth": 802224000000
    }
}

This response example shows how the data is returned when only the DATE_OF_BIRTH scope is enabled.