# Incode Workforce API Overview

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 during the recruiting process. It also enables embedding a 'Verify' button within client portals, streamlining the verification process for candidates.

## Use Cases

1. **Automation Integration:** Trigger identity verification automatically within workflows managed by automation or ATS tools like Workato, Greenhouse, 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 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 the Authorize endpoint.

### 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/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.                     | Yes      | `c0fd10ff-c36e-49a6-afde-a00496c1c8e7` |
| `secret`        | A secret parameter for additional security.                                                    | Yes      | `s3cureS3cr3tValue`               |
| `loginHint`     | The candidate's email or username, used for login                                              | Yes      | `john.doe@company.com` / `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`        |

#### cURL Example

```undefined
curl -X POST "https://{server-url}/v1/verification/candidate/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",
    "givenNames": "John",
    "lastName": "Doe",
    "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"
}
```