The Incode Workforce API allows clients to generate a verification link for identity verification processes through 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

1. **Automation Integration:** Trigger identity verification automatically within workflows managed by automation tools like Zapier, Workato, or internal systems.
2. **Client Portals:** Embed the verification link in a 'Verify' button within client-facing applications, enabling seamless and user-initiated identity verification.
3. **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](https://workforce.developer.incode.com/docs/webhooks) 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](https://workforce.developer.incode.com/docs/authorization)

#### cURL Example

```shell
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

```json
{
    "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.                           | Yes      | `c0fd10ff-c36e-49a6-afde-a00496c1c8e7`               |
| `secret`           | A secret parameter for additional security.                                                           | Yes      | `s3cureS3cr3tValue`                                 |
| `loginHint`        | The employee’s email or username, used for login as specified in the employee directory              | Yes      | `john.doe@company.com` / `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

```shell
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": "john.doe@company.com",
    "loginHintType": "EMAIL",
    "correlationId": "abc-123-xyz",
    "redirectUrl": "https://client-portal.com/success",
    "validityMinutes": 30
}'
```

### Response

**Status Code:**`200 OK`

#### **Success Response**

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

### Error Responses

#### **Missing Required Parameter**

**Status Code:**`400 Bad Request`

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

#### **Invalid Login Hint Type**

**Status Code:**`400 Bad Request`

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