---
icon: gear
label: VerifEye Service API
---

# VerifEye Service API

## Overview

The VerifEye Service API provides endpoints to manage verification configurations and to create and validate signed query strings.

The VerifEye Service API enables you to:
- Create, retrieve, list, update and delete verification configurations
- Configure verification settings for liveness, age, gender, and face recognition
- Create signed query strings for secure API requests
- Validate signed query strings to ensure request integrity
- Manage redirect URLs and result parameters
- Control session-level configuration overrides
- Configure webhooks to receive server-side notifications when verification sessions complete
- Retrieve full session results server-side via the Get Session Result endpoint

!!!tip
This API is intended for **server-side use only**. Using it directly from the client side would expose it to potential misuse and abuse.
!!!

## Base URLs

| Region | Base URL |
|--------|----------|
| **EU** | `https://verifeye-service-api-api-eu.realeyes.ai/v1/` |
| **US** | `https://verifeye-service-api-api-us.realeyes.ai/v1/` |

---

## API Endpoints

### Create Signature

Creates a signed query string based on the query string provided in the request body.

**Endpoint:** `POST /v1/signature/create`

**Authentication:** API Key or Bearer Token

**Request Body:**

```json
{
  "queryString": "key1=value1&key2=value2...keyN=valueN",
  "securitySettings": {
    "enableNonce": true,
    "expirationEnabled": true,
    "expirationInSeconds": 3600
  }
}
```

**Request Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `queryString` | string | Yes | The full query string to be signed |
| `securitySettings` | object | No | Optional security options. **When omitted, expiration defaults to enabled (1 day)** — send `{ "expirationEnabled": false }` to opt out and get a non-expiring URL. |
| `securitySettings.expirationEnabled` | boolean | No | Controls whether an expiration timestamp (`reExpiration`) is embedded in the URL. **Defaults to `true`.** Send `false` to disable expiration entirely. |
| `securitySettings.expirationInSeconds` | integer | No | Lifetime of the URL in seconds. Range `1..604800` (max 7 days). Defaults to `86400` (1 day) when expiration is enabled and the value is omitted. Cannot be combined with `expirationEnabled: false`. |
| `securitySettings.enableNonce` | boolean | No | When `true`, a one-time-use nonce (`reNonce`) is embedded in the URL. Requires expiration to be enabled (which is the default). Defaults to `false`. |

**Response Example:**

```json
{
  "signature": "THE_SIGNATURE",
  "signedQueryString": "key1=value1&key2=value2...keyN=valueN&reExpiration=1747852345&reNonce=bf5c7f4e8a794e41a58e08dfd634f816&reSignature=THE_SIGNATURE",
  "expiration": 1747852345,
  "nonce": "bf5c7f4e8a794e41a58e08dfd634f816"
}
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| `signature` | string | The signature for the query string |
| `signedQueryString` | string | The signed query string that includes the signature, plus `reExpiration` / `reNonce` when set |
| `expiration` | integer? | UTC unix epoch (seconds) when the URL expires. Present only when `expirationEnabled` was `true`. |
| `nonce` | string? | The one-time-use nonce embedded in the URL. Present only when `enableNonce` was `true`. |

**Example Request:**

```bash
curl -X POST "https://verifeye-service-api-eu.realeyes.ai/v1/signature/create" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "queryString": "key1=value1&key2=value2...keyN=valueN",
    "securitySettings": {
      "enableNonce": true,
      "expirationEnabled": true,
      "expirationInSeconds": 900
    }
  }'
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters (e.g. nonce enabled without expiration, or `expirationInSeconds` outside `1..604800`)
- `401` - Unauthorized - Missing or invalid authentication

---

### Validate Signature

Validates the signature of the request using the query string and the signature inside the query string. Also checks the optional `reExpiration` and `reNonce` parameters when present.

This endpoint is **read-only** — calling it never consumes a nonce, so you can use it from your backend to detect a bad / expired / already-used link before redirecting the user.

**Endpoint:** `POST /v1/signature/validate`

**Authentication:** API Key or Bearer Token

**Request Body:**

```json
{
  "queryString": "key1=value1&key2=value2...keyN=valueN&reSignature=THE_SIGNATURE"
}
```

**Request Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `queryString` | string | Yes | The full query string of the request to validate |

**Response Example:**

```json
{
  "result": "Valid"
}
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| `result` | string | The validation outcome — one of `Valid`, `Invalid`, `Expired`, `NonceAlreadyUsed` |

**Outcome semantics:**

| `result` | Meaning |
|---|---|
| `Valid` | Signature matches; if `reExpiration` is present it has not passed; if `reNonce` is present it has not yet been consumed. |
| `Invalid` | The signature does not match the query string. |
| `Expired` | The signature is valid but `reExpiration` is in the past. |
| `NonceAlreadyUsed` | The signature is valid and the URL has not expired, but the `reNonce` has already been consumed by an earlier `init-redirect-session` call. |

Validation is evaluated in the order **signature → expiration → nonce**. The first failing check determines the result.

**Example Request:**

```bash
curl -X POST "https://verifeye-service-api-eu.realeyes.ai/v1/signature/validate" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "queryString": "key1=value1&key2=value2...keyN=valueN&reSignature=THE_SIGNATURE"
  }'
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `401` - Unauthorized - Missing or invalid authentication

---

### Get Verification

Returns a verification configuration by `verificationId`.

**Endpoint:** `GET /v1/verification/get`

**Authentication:** API Key or Bearer Token

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `verificationId` | string | Yes | The ID of the verification configuration to retrieve |

**Response Example:**
```json
{
  "verification": {
    "created": "2025-11-07T00:00:00Z",
    "lastModified": "2025-11-07T00:00:00Z",
    "verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf",
    "name": "Test Verification",
    "verificationConfig": {
      "verifierConfigs": {
        "liveness": {
          "type": "Verification",
          "challengeType": "Balanced"
        },
        "age": {
          "type": "CalculationOnly"
        },
        "faceRecognition": {
          "type": "DuplicateVerification"
        },
        "gender": {
          "type": "CalculationOnly"
        }
      },
      "redirectConfig": {
        "passedUrl": "https://example.com?result=passed",
        "failedUrl": "https://example.com?result=failed"
      },
      "resultParameterConfig": {
        "includeSignature": true,
        "includeSessionId": true,
        "includeFaceId": true,
        "includeAge": true,
        "includeGender": true,
        "includeVerificationResult": true,
        "includeCustomInputParameters": true,
        "includeLivenessCheckResult": true,
        "includeAgeVerificationResult": true,
        "includeGenderVerificationResult": false,
        "includeFaceRecognitionResult": true,
        "includeCorrelationId": true,
        "includeTotalFaceCount": true,
        "includeFailedReason": true
      },
      "securityConfig": {
        "forceSignedInput": true
      },
      "sessionOverrideConfig": {
        "allowVerifierOverrides": true,
        "allowResultParameterOverrides": false,
        "allowRedirectOverrides": false
      },
      "webhookConfig": {
        "eventCallbackUrl": "https://your-server.example.com/webhook"
      }
    }
  }
}
```

**Response Fields:**

| Field Path | Type | Description |
|------------|------|-------------|
| `verification` | object | Detailed verification configuration model including metadata and nested configuration sections |
| `verification.verificationId` | string | Unique identifier of the verification configuration |
| `verification.name` | string | Human readable name of the verification configuration |
| `verification.created` | string | UTC timestamp when the configuration was created (ISO 8601 format) |
| `verification.lastModified` | string | UTC timestamp of the last modification (ISO 8601 format) |
| `verification.verificationConfig` | object | Root container for all adjustable verification configuration sections |
| `verification.verificationConfig.verifierConfigs` | object | Collection of verifier specific configuration sections |
| `verification.verificationConfig.verifierConfigs.liveness` | object | Liveness verifier configuration model |
| `verification.verificationConfig.verifierConfigs.liveness.type` | string | Supported liveness verification modes (Disabled, Verification) |
| `verification.verificationConfig.verifierConfigs.liveness.challengeType` | string | Supported liveness verification challenges (<!--Basic, -->Balanced, Advanced) |
| `verification.verificationConfig.verifierConfigs.age` | object | Age verifier configuration model |
| `verification.verificationConfig.verifierConfigs.age.type` | string | Supported age verification modes (Disabled, CalculationOnly, ThresholdVerification, RangeVerification) |
| `verification.verificationConfig.verifierConfigs.age.thresholdConfig` | object | Configuration for threshold based age verification |
| `verification.verificationConfig.verifierConfigs.age.thresholdConfig.threshold` | integer | Age threshold value used for verification |
| `verification.verificationConfig.verifierConfigs.age.thresholdConfig.direction` | string | Direction used when evaluating age threshold comparisons (Above, Below) |
| `verification.verificationConfig.verifierConfigs.age.rangeConfig` | object | Configuration for range based age verification |
| `verification.verificationConfig.verifierConfigs.age.rangeConfig.minimum` | integer | Minimum allowed age |
| `verification.verificationConfig.verifierConfigs.age.rangeConfig.maximum` | integer | Maximum allowed age |
| `verification.verificationConfig.verifierConfigs.faceRecognition` | object | Face recognition verifier configuration model |
| `verification.verificationConfig.verifierConfigs.faceRecognition.type` | string | Supported face recognition verification modes (Disabled, CalculationOnly, DuplicateVerification, UniqueMatchVerification, MatchVerification) |
| `verification.verificationConfig.verifierConfigs.gender` | object | Gender verifier configuration model |
| `verification.verificationConfig.verifierConfigs.gender.type` | string | Supported gender verification modes (Disabled, CalculationOnly) |
| `verification.verificationConfig.verifierConfigs.commonSettings` | object | Common settings configuration model |
| `verification.verificationConfig.verifierConfigs.commonSettings.failOnMultipleFacesDetected` | boolean | Fail the verification if multiple faces are detected in the input image |
| `verification.verificationConfig.redirectConfig` | object | Redirect URLs used after different verification outcomes |
| `verification.verificationConfig.redirectConfig.passedUrl` | string | URL to redirect to when verification succeeds |
| `verification.verificationConfig.redirectConfig.failedUrl` | string | URL to redirect to when verification fails |
| `verification.verificationConfig.resultParameterConfig` | object | Controls which result parameters are included in API responses |
| `verification.verificationConfig.resultParameterConfig.includeSignature` | boolean | Include a signature value in the response |
| `verification.verificationConfig.resultParameterConfig.includeSessionId` | boolean | Include the session identifier in the response |
| `verification.verificationConfig.resultParameterConfig.includeFaceId` | boolean | Include a face identifier (if available) in the response |
| `verification.verificationConfig.resultParameterConfig.includeAge` | boolean | Include the estimated age |
| `verification.verificationConfig.resultParameterConfig.includeGender` | boolean | Include the estimated gender |
| `verification.verificationConfig.resultParameterConfig.includeVerificationResult` | boolean | Include the overall verification result status |
| `verification.verificationConfig.resultParameterConfig.includeCustomInputParameters` | boolean | Include any custom input parameters that were part of the request |
| `verification.verificationConfig.resultParameterConfig.includeLivenessCheckResult` | boolean | Include the liveness check result |
| `verification.verificationConfig.resultParameterConfig.includeAgeVerificationResult` | boolean | Include the age verification result |
| `verification.verificationConfig.resultParameterConfig.includeGenderVerificationResult` | boolean | Include the gender verification result |
| `verification.verificationConfig.resultParameterConfig.includeFaceRecognitionResult` | boolean | Include the face recognition verification result |
| `verification.verificationConfig.resultParameterConfig.includeCorrelationId` | boolean | Include the correlation identifier |
| `verification.verificationConfig.resultParameterConfig.includeTotalFaceCount` | boolean | Include the total face count detected |
| `verification.verificationConfig.resultParameterConfig.includeFailedReason` | boolean | Include the failed reason |
| `verification.verificationConfig.securityConfig` | object | Security related options influencing verification request validation |
| `verification.verificationConfig.securityConfig.forceSignedInput` | boolean | When true, input payloads must be signed. Default: `true`. |
| `verification.verificationConfig.sessionOverrideConfig` | object | Settings that allow selectively overriding verification behavior per session |
| `verification.verificationConfig.sessionOverrideConfig.allowVerifierOverrides` | boolean | Allows overriding which verifiers are enabled/disabled |
| `verification.verificationConfig.sessionOverrideConfig.allowResultParameterOverrides` | boolean | Allows overriding which result parameters are returned |
| `verification.verificationConfig.sessionOverrideConfig.allowRedirectOverrides` | boolean | Allows overriding redirect URLs |
| `verification.verificationConfig.webhookConfig` | object | Webhook configuration for server-side event notifications |
| `verification.verificationConfig.webhookConfig.eventCallbackUrl` | string | URL to which a `VerificationCompleted` event is sent when a session finishes |

**Example Request:**

```bash
curl -X GET "https://verifeye-service-api-eu.realeyes.ai/v1/verification/get?verificationId=39e00c96-6431-4b2e-8707-2fb80e561fbf" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `401` - Unauthorized - Missing or invalid authentication
- `404` - Not Found - Verification configuration not found

---

### Get All Verifications

Returns all verification configurations for the account.

**Endpoint:** `GET /v1/verification/get-all`

**Authentication:** API Key or Bearer Token

**Response Example:**
```json
{
  "verifications": [
    {
      "verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf",
      "name": "Test Verification",
      "created": "2026-02-01T00:00:00Z",
      "lastModified": "2026-02-01T00:00:00Z"
    }
  ]
}
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| `verifications` | array | Collection of verification configuration overview models |
| `verifications[].verificationId` | string | Unique identifier of the verification configuration |
| `verifications[].name` | string | Human readable name of the configuration |
| `verifications[].created` | string | UTC timestamp when the configuration was created (ISO 8601 format) |
| `verifications[].lastModified` | string | UTC timestamp of the last modification (ISO 8601 format) |

**Example Request:**

```bash
curl -X GET "https://verifeye-service-api-eu.realeyes.ai/v1/verification/get-all" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"
```

**Response Codes:**
- `200` - Success
- `401` - Unauthorized - Missing or invalid authentication

---

### Create Verification

Create a new verification configuration. If you require idempotent behavior — where the configuration is created when it does not yet exist or updated when it does — use [Create or Update Verification](#create-or-update-verification) instead.

!!!danger IMPORTANT
A verification is supposed to be a reusable configuration that can be used across multiple verification sessions and with the same face collection. This follows a one-time setup concept: create it once and reuse it many times. For more details, see [One-time setup: Create once, reuse many times](../../redirect/concept/#one-time-setup-create-once-reuse-many-times).
!!!

**Endpoint:** `POST /v1/verification/create`

**Authentication:** API Key or Bearer Token

**Request Body:**
```json
{
  "name": "Test Verification",
  "verificationConfig": {
  "verifierConfigs": {
        "liveness": {
          "type": "Verification",
          "challengeType": "Balanced"
        },
        "age": {
          "type": "CalculationOnly"
        },
        "faceRecognition": {
          "type": "DuplicateVerification"
        },
        "gender": {
          "type": "CalculationOnly"
        }
      },
      "redirectConfig": {
        "passedUrl": "https://example.com?result=passed",
        "failedUrl": "https://example.com?result=failed"
      },
      "resultParameterConfig": {
        "includeSignature": true,
        "includeSessionId": true,
        "includeFaceId": true,
        "includeAge": true,
        "includeGender": true,
        "includeVerificationResult": true,
        "includeCustomInputParameters": true,
        "includeLivenessCheckResult": true,
        "includeAgeVerificationResult": true,
        "includeGenderVerificationResult": false,
        "includeFaceRecognitionResult": true,
        "includeCorrelationId": true,
        "includeTotalFaceCount": true,
        "includeFailedReason": true
      },
      "securityConfig": {
        "forceSignedInput": true
      },
      "sessionOverrideConfig": {
        "allowVerifierOverrides": true,
        "allowResultParameterOverrides": false,
        "allowRedirectOverrides": false
      },
      "webhookConfig": {
        "eventCallbackUrl": "https://your-server.example.com/webhook"
      }
  }
}
```

**Request Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human readable name for the verification configuration |
| `verificationConfig` | object | Yes | Root container for all adjustable verification configuration sections |
| `verificationConfig.verifierConfigs` | object | No | Collection of verifier specific configuration sections |
| `verificationConfig.verifierConfigs.liveness` | object | No | Liveness verifier configuration model |
| `verificationConfig.verifierConfigs.liveness.type` | string | No | Supported liveness verification modes (Disabled, Verification) |
| `verificationConfig.verifierConfigs.liveness.challengeType` | string | No | Supported liveness verification challenges (<!--Basic, -->, Balanced, Advanced) |
| `verificationConfig.verifierConfigs.age` | object | No | Age verifier configuration model |
| `verificationConfig.verifierConfigs.age.type` | string | No | Supported age verification modes (Disabled, CalculationOnly, ThresholdVerification, RangeVerification) |
| `verificationConfig.verifierConfigs.age.thresholdConfig` | object | No | Configuration for threshold based age verification |
| `verificationConfig.verifierConfigs.age.thresholdConfig.threshold` | integer | No | Age threshold value used for verification |
| `verificationConfig.verifierConfigs.age.thresholdConfig.direction` | string | No | Direction used when evaluating age threshold comparisons (Above, Below) |
| `verificationConfig.verifierConfigs.age.rangeConfig` | object | No | Configuration for range based age verification |
| `verificationConfig.verifierConfigs.age.rangeConfig.minimum` | integer | No | Minimum allowed age |
| `verificationConfig.verifierConfigs.age.rangeConfig.maximum` | integer | No | Maximum allowed age |
| `verificationConfig.verifierConfigs.faceRecognition` | object | No | Face recognition verifier configuration model |
| `verificationConfig.verifierConfigs.faceRecognition.type` | string | No | Supported face recognition verification modes (Disabled, CalculationOnly, DuplicateVerification, UniqueMatchVerification, MatchVerification) |
| `verificationConfig.verifierConfigs.gender` | object | No | Gender verifier configuration model |
| `verificationConfig.verifierConfigs.gender.type` | string | No | Supported gender verification modes (Disabled, CalculationOnly) |
| `verificationConfig.verifierConfigs.commonSettings` | object | No | Common settings configuration model |
| `verificationConfig.verifierConfigs.commonSettings.failOnMultipleFacesDetected` | boolean | No | Fail the verification if multiple faces are detected in the input image |
| `verificationConfig.redirectConfig` | object | No | Redirect URLs used after different verification outcomes |
| `verificationConfig.redirectConfig.passedUrl` | string | No | URL to redirect to when verification succeeds |
| `verificationConfig.redirectConfig.failedUrl` | string | No | URL to redirect to when verification fails |
| `verificationConfig.resultParameterConfig` | object | No | Controls which result parameters are included in API responses |
| `verificationConfig.resultParameterConfig.includeSignature` | boolean | No | Include a signature value in the response |
| `verificationConfig.resultParameterConfig.includeSessionId` | boolean | No | Include the session identifier in the response |
| `verificationConfig.resultParameterConfig.includeFaceId` | boolean | No | Include a face identifier (if available) in the response |
| `verificationConfig.resultParameterConfig.includeAge` | boolean | No | Include the estimated age |
| `verificationConfig.resultParameterConfig.includeGender` | boolean | No | Include the estimated gender |
| `verificationConfig.resultParameterConfig.includeVerificationResult` | boolean | No | Include the overall verification result status |
| `verificationConfig.resultParameterConfig.includeCustomInputParameters` | boolean | No | Include any custom input parameters that were part of the request |
| `verificationConfig.resultParameterConfig.includeLivenessCheckResult` | boolean | No | Include the liveness check result |
| `verificationConfig.resultParameterConfig.includeAgeVerificationResult` | boolean | No | Include the age verification result |
| `verificationConfig.resultParameterConfig.includeGenderVerificationResult` | boolean | No | Include the gender verification result |
| `verificationConfig.resultParameterConfig.includeFaceRecognitionResult` | boolean | No | Include the face recognition verification result |
| `verificationConfig.resultParameterConfig.includeCorrelationId` | boolean | No | Include the correlation identifier |
| `verificationConfig.resultParameterConfig.includeTotalFaceCount` | boolean | No | Include the total face count detected |
| `verificationConfig.resultParameterConfig.includeFailedReason` | boolean | Include the failed reason |
| `verificationConfig.securityConfig` | object | No | Security related options influencing verification request validation |
| `verificationConfig.securityConfig.forceSignedInput` | boolean | No | When true, input payloads must be signed. **Default: `true`** (strongly recommended — see [security guidance](/redirect/security/#incoming-signed-verification-url-request-integrity)) |
| `verificationConfig.sessionOverrideConfig` | object | No | Settings that allow selectively overriding verification behavior per session |
| `verificationConfig.sessionOverrideConfig.allowVerifierOverrides` | boolean | No | Allows overriding which verifiers are enabled/disabled |
| `verificationConfig.sessionOverrideConfig.allowResultParameterOverrides` | boolean | No | Allows overriding which result parameters are returned |
| `verificationConfig.sessionOverrideConfig.allowRedirectOverrides` | boolean | No | Allows overriding redirect URLs |
| `verificationConfig.webhookConfig` | object | No | Webhook configuration for server-side event notifications |
| `verificationConfig.webhookConfig.eventCallbackUrl` | string | No | URL to which a `VerificationCompleted` event is sent when a session finishes. Omit or leave empty to disable |

**Response Example:**

```json
{
  "verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf"
}
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| `verificationId` | string | Identifier of the newly created verification configuration |

**Example Request:**

```bash
curl -X POST "https://verifeye-service-api-eu.realeyes.ai/v1/verification/create" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Verification",
    "verificationConfig": {
      "verifierConfigs": {
        "liveness": {
          "type": "Verification",
          "challengeType": "Balanced"
        },
        "age": {
          "type": "CalculationOnly"
        },
        "faceRecognition": {
          "type": "DuplicateVerification"
        },
        "gender": {
          "type": "CalculationOnly"
        }
      },
      "redirectConfig": {
        "passedUrl": "https://example.com?result=passed",
        "failedUrl": "https://example.com?result=failed"
      },
      "resultParameterConfig": {
        "includeSignature": true,
        "includeSessionId": true,
        "includeFaceId": true,
        "includeAge": true,
        "includeGender": true,
        "includeVerificationResult": true,
        "includeCustomInputParameters": true,
        "includeLivenessCheckResult": true,
        "includeAgeVerificationResult": true,
        "includeGenderVerificationResult": false,
        "includeFaceRecognitionResult": true,
        "includeCorrelationId": true,
        "includeTotalFaceCount": true,
        "includeFailedReason": true
      },
      "securityConfig": {
        "forceSignedInput": true
      },
      "sessionOverrideConfig": {
        "allowVerifierOverrides": true,
        "allowResultParameterOverrides": false,
        "allowRedirectOverrides": false
      }
    }
  }'
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `401` - Unauthorized - Missing or invalid authentication
- `409` - Conflict - A verification configuration with the same name already exists

---

### Create or Update Verification

Create a new verification configuration, or update the existing one if a verification with the same name already exists.

!!!danger IMPORTANT
A verification is supposed to be a reusable configuration that can be used across multiple verification sessions and with the same face collection. This follows a one-time setup concept: create it once and reuse it many times. For more details, see [One-time setup: Create once, reuse many times](../../redirect/concept/#one-time-setup-create-once-reuse-many-times).
!!!

**Endpoint:** `POST /v1/verification/create-or-update`

**Authentication:** API Key or Bearer Token

**Request Body:**
```json
{
  "name": "Test Verification",
  "verificationConfig": {
  "verifierConfigs": {
        "liveness": {
          "type": "Verification",
          "challengeType": "Balanced"
        },
        "age": {
          "type": "CalculationOnly"
        },
        "faceRecognition": {
          "type": "DuplicateVerification"
        },
        "gender": {
          "type": "CalculationOnly"
        }
      },
      "redirectConfig": {
        "passedUrl": "https://example.com?result=passed",
        "failedUrl": "https://example.com?result=failed"
      },
      "resultParameterConfig": {
        "includeSignature": true,
        "includeSessionId": true,
        "includeFaceId": true,
        "includeAge": true,
        "includeGender": true,
        "includeVerificationResult": true,
        "includeCustomInputParameters": true,
        "includeLivenessCheckResult": true,
        "includeAgeVerificationResult": true,
        "includeGenderVerificationResult": false,
        "includeFaceRecognitionResult": true,
        "includeCorrelationId":true,
        "includeTotalFaceCount":true,
        "includeFailedReason":true
      },
      "securityConfig": {
        "forceSignedInput": true
      },
      "sessionOverrideConfig": {
        "allowVerifierOverrides": true,
        "allowResultParameterOverrides": false,
        "allowRedirectOverrides": false
      },
      "webhookConfig": {
        "eventCallbackUrl": "https://your-server.example.com/webhook"
      }
  }
}
```

**Request Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human readable name for the verification configuration |
| `verificationConfig` | object | Yes | Root container for all adjustable verification configuration sections |
| `verificationConfig.verifierConfigs` | object | No | Collection of verifier specific configuration sections |
| `verificationConfig.verifierConfigs.liveness` | object | No | Liveness verifier configuration model |
| `verificationConfig.verifierConfigs.liveness.type` | string | No | Supported liveness verification modes (Disabled, Verification) |
| `verificationConfig.verifierConfigs.liveness.challengeType` | string | No | Supported liveness verification challenges (<!--Basic, -->, Balanced, Advanced) |
| `verificationConfig.verifierConfigs.age` | object | No | Age verifier configuration model |
| `verificationConfig.verifierConfigs.age.type` | string | No | Supported age verification modes (Disabled, CalculationOnly, ThresholdVerification, RangeVerification) |
| `verificationConfig.verifierConfigs.age.thresholdConfig` | object | No | Configuration for threshold based age verification |
| `verificationConfig.verifierConfigs.age.thresholdConfig.threshold` | integer | No | Age threshold value used for verification |
| `verificationConfig.verifierConfigs.age.thresholdConfig.direction` | string | No | Direction used when evaluating age threshold comparisons (Above, Below) |
| `verificationConfig.verifierConfigs.age.rangeConfig` | object | No | Configuration for range based age verification |
| `verificationConfig.verifierConfigs.age.rangeConfig.minimum` | integer | No | Minimum allowed age |
| `verificationConfig.verifierConfigs.age.rangeConfig.maximum` | integer | No | Maximum allowed age |
| `verificationConfig.verifierConfigs.faceRecognition` | object | No | Face recognition verifier configuration model |
| `verificationConfig.verifierConfigs.faceRecognition.type` | string | No | Supported face recognition verification modes (Disabled, CalculationOnly, DuplicateVerification, UniqueMatchVerification, MatchVerification) |
| `verificationConfig.verifierConfigs.gender` | object | No | Gender verifier configuration model |
| `verificationConfig.verifierConfigs.gender.type` | string | No | Supported gender verification modes (Disabled, CalculationOnly) |
| `verificationConfig.verifierConfigs.commonSettings` | object | No | Common settings configuration model |
| `verificationConfig.verifierConfigs.commonSettings.failOnMultipleFacesDetected` | boolean | No | Fail the verification if multiple faces are detected in the input image |
| `verificationConfig.redirectConfig` | object | No | Redirect URLs used after different verification outcomes |
| `verificationConfig.redirectConfig.passedUrl` | string | No | URL to redirect to when verification succeeds |
| `verificationConfig.redirectConfig.failedUrl` | string | No | URL to redirect to when verification fails |
| `verificationConfig.resultParameterConfig` | object | No | Controls which result parameters are included in API responses |
| `verificationConfig.resultParameterConfig.includeSignature` | boolean | No | Include a signature value in the response |
| `verificationConfig.resultParameterConfig.includeSessionId` | boolean | No | Include the session identifier in the response |
| `verificationConfig.resultParameterConfig.includeFaceId` | boolean | No | Include a face identifier (if available) in the response |
| `verificationConfig.resultParameterConfig.includeAge` | boolean | No | Include the estimated age |
| `verificationConfig.resultParameterConfig.includeGender` | boolean | No | Include the estimated gender |
| `verificationConfig.resultParameterConfig.includeVerificationResult` | boolean | No | Include the overall verification result status |
| `verificationConfig.resultParameterConfig.includeCustomInputParameters` | boolean | No | Include any custom input parameters that were part of the request |
| `verificationConfig.resultParameterConfig.includeLivenessCheckResult` | boolean | No | Include the liveness check result |
| `verificationConfig.resultParameterConfig.includeAgeVerificationResult` | boolean | No | Include the age verification result |
| `verificationConfig.resultParameterConfig.includeGenderVerificationResult` | boolean | No | Include the gender verification result |
| `verificationConfig.resultParameterConfig.includeFaceRecognitionResult` | boolean | No | Include the face recognition verification result |
| `verificationConfig.resultParameterConfig.includeCorrelationId` | boolean | No | Include the correlation identifier |
| `verificationConfig.resultParameterConfig.includeTotalFaceCount` | boolean | No | Include the total face count detected |
| `verificationConfig.resultParameterConfig.includeFailedReason` | boolean | Include the failed reason |
| `verificationConfig.securityConfig` | object | No | Security related options influencing verification request validation |
| `verificationConfig.securityConfig.forceSignedInput` | boolean | No | When true, input payloads must be signed. **Default: `true`** (strongly recommended — see [security guidance](/redirect/security/#incoming-signed-verification-url-request-integrity)) |
| `verificationConfig.sessionOverrideConfig` | object | No | Settings that allow selectively overriding verification behavior per session |
| `verificationConfig.sessionOverrideConfig.allowVerifierOverrides` | boolean | No | Allows overriding which verifiers are enabled/disabled |
| `verificationConfig.sessionOverrideConfig.allowResultParameterOverrides` | boolean | No | Allows overriding which result parameters are returned |
| `verificationConfig.sessionOverrideConfig.allowRedirectOverrides` | boolean | No | Allows overriding redirect URLs |
| `verificationConfig.webhookConfig` | object | No | Webhook configuration for server-side event notifications |
| `verificationConfig.webhookConfig.eventCallbackUrl` | string | No | URL to which a `VerificationCompleted` event is sent when a session finishes. Omit or leave empty to disable |

**Response Example:**

```json
{
  "verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf",
  "wasCreated": true
}
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| `verificationId` | string | Identifier of the created or updated verification configuration |
| `wasCreated` | boolean | Indicates whether the verification configuration was newly created (true) or an existing one with the same name was updated (false) |

**Example Request:**

```bash
curl -X POST "https://verifeye-service-api-eu.realeyes.ai/v1/verification/create-or-update" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Verification",
    "verificationConfig": {
      "verifierConfigs": {
        "liveness": {
          "type": "Verification",
          "challengeType": "Balanced"
        },
        "age": {
          "type": "CalculationOnly"
        },
        "faceRecognition": {
          "type": "DuplicateVerification"
        },
        "gender": {
          "type": "CalculationOnly"
        }
      },
      "redirectConfig": {
        "passedUrl": "https://example.com?result=passed",
        "failedUrl": "https://example.com?result=failed"
      },
      "resultParameterConfig": {
        "includeSignature": true,
        "includeSessionId": true,
        "includeFaceId": true,
        "includeAge": true,
        "includeGender": true,
        "includeVerificationResult": true,
        "includeCustomInputParameters": true,
        "includeLivenessCheckResult": true,
        "includeAgeVerificationResult": true,
        "includeGenderVerificationResult": false,
        "includeFaceRecognitionResult": true,
        "includeCorrelationId":true,
        "includeTotalFaceCount":true,
        "includeFailedReason":true
      },
      "securityConfig": {
        "forceSignedInput": true
      },
      "sessionOverrideConfig": {
        "allowVerifierOverrides": true,
        "allowResultParameterOverrides": false,
        "allowRedirectOverrides": false
      }
    }
  }'
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `401` - Unauthorized - Missing or invalid authentication

---

### Update Verification

Update a verification configuration.

**Endpoint:** `PUT /v1/verification/update`

**Authentication:** API Key or Bearer Token

**Request Body:**
```json
{
   "name":"Test Verification",
   "verificationConfig":{
      "verifierConfigs":{
         "liveness":{
            "type":"Verification",
            "challengeType": "Balanced"
         },
         "age":{
            "type":"CalculationOnly"
         },
         "faceRecognition":{
            "type":"Disabled"
         },
         "gender":{
            "type":"CalculationOnly"
         }
      },
      "redirectConfig":{
         "passedUrl":"https://example.com?result=passed",
         "failedUrl":"https://example.com?result=failed"
      },
      "resultParameterConfig":{
         "includeSignature":true,
         "includeSessionId":true,
         "includeFaceId":true,
         "includeAge":true,
         "includeGender":true,
         "includeVerificationResult":true,
         "includeCustomInputParameters":true,
         "includeLivenessCheckResult":true,
         "includeAgeVerificationResult":true,
         "includeGenderVerificationResult":false,
         "includeFaceRecognitionResult":true,
         "includeCorrelationId":true,
         "includeTotalFaceCount":true,
         "includeFailedReason":true
      },
      "securityConfig":{
         "forceSignedInput":true
      },
      "sessionOverrideConfig":{
         "allowVerifierOverrides":true,
         "allowResultParameterOverrides":false,
         "allowRedirectOverrides":false
      },
      "webhookConfig":{
         "eventCallbackUrl":"https://your-server.example.com/webhook"
      }
   },
   "verificationId":"39e00c96-6431-4b2e-8707-2fb80e561fbf"
}
```

**Request Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `verificationId` | string | Yes | The ID of the verification configuration to update |
| `name` | string | Yes | Human readable name for the verification configuration |
| `verificationConfig` | object | Yes | Root container for all adjustable verification configuration sections |
| `verificationConfig.verifierConfigs` | object | No | Collection of verifier specific configuration sections |
| `verificationConfig.verifierConfigs.liveness` | object | No | Liveness verifier configuration model |
| `verificationConfig.verifierConfigs.liveness.type` | string | No | Supported liveness verification modes (Disabled, Verification) |
| `verificationConfig.verifierConfigs.liveness.challengeType` | string | No | Supported liveness verification challenges (<!--Basic, -->, Balanced, Advanced) |
| `verificationConfig.verifierConfigs.age` | object | No | Age verifier configuration model |
| `verificationConfig.verifierConfigs.age.type` | string | No | Supported age verification modes (Disabled, CalculationOnly, ThresholdVerification, RangeVerification) |
| `verificationConfig.verifierConfigs.age.thresholdConfig` | object | No | Configuration for threshold based age verification |
| `verificationConfig.verifierConfigs.age.thresholdConfig.threshold` | integer | No | Age threshold value used for verification |
| `verificationConfig.verifierConfigs.age.thresholdConfig.direction` | string | No | Direction used when evaluating age threshold comparisons (Above, Below) |
| `verificationConfig.verifierConfigs.age.rangeConfig` | object | No | Configuration for range based age verification |
| `verificationConfig.verifierConfigs.age.rangeConfig.minimum` | integer | No | Minimum allowed age |
| `verificationConfig.verifierConfigs.age.rangeConfig.maximum` | integer | No | Maximum allowed age |
| `verificationConfig.verifierConfigs.faceRecognition` | object | No | Face recognition verifier configuration model |
| `verificationConfig.verifierConfigs.faceRecognition.type` | string | No | Supported face recognition verification modes (Disabled, CalculationOnly, DuplicateVerification, UniqueMatchVerification, MatchVerification) |
| `verificationConfig.verifierConfigs.gender` | object | No | Gender verifier configuration model |
| `verificationConfig.verifierConfigs.gender.type` | string | No | Supported gender verification modes (Disabled, CalculationOnly) |
| `verificationConfig.verifierConfigs.commonSettings` | object | No | Common settings configuration model |
| `verificationConfig.verifierConfigs.commonSettings.failOnMultipleFacesDetected` | boolean | No | Fail the verification if multiple faces are detected in the input image |
| `verificationConfig.redirectConfig` | object | No | Redirect URLs used after different verification outcomes |
| `verificationConfig.redirectConfig.passedUrl` | string | No | URL to redirect to when verification succeeds |
| `verificationConfig.redirectConfig.failedUrl` | string | No | URL to redirect to when verification fails |
| `verificationConfig.resultParameterConfig` | object | No | Controls which result parameters are included in API responses |
| `verificationConfig.resultParameterConfig.includeSignature` | boolean | No | Include a signature value in the response |
| `verificationConfig.resultParameterConfig.includeSessionId` | boolean | No | Include the session identifier in the response |
| `verificationConfig.resultParameterConfig.includeFaceId` | boolean | No | Include a face identifier (if available) in the response |
| `verificationConfig.resultParameterConfig.includeAge` | boolean | No | Include the estimated age |
| `verificationConfig.resultParameterConfig.includeGender` | boolean | No | Include the estimated gender |
| `verificationConfig.resultParameterConfig.includeVerificationResult` | boolean | No | Include the overall verification result status |
| `verificationConfig.resultParameterConfig.includeCustomInputParameters` | boolean | No | Include any custom input parameters that were part of the request |
| `verificationConfig.resultParameterConfig.includeLivenessCheckResult` | boolean | No | Include the liveness check result |
| `verificationConfig.resultParameterConfig.includeAgeVerificationResult` | boolean | No | Include the age verification result |
| `verificationConfig.resultParameterConfig.includeGenderVerificationResult` | boolean | No | Include the gender verification result |
| `verificationConfig.resultParameterConfig.includeFaceRecognitionResult` | boolean | No | Include the face recognition verification result |
| `verificationConfig.resultParameterConfig.includeCorrelationId` | boolean | No | Include the correlation identifier |
| `verificationConfig.resultParameterConfig.includeTotalFaceCount` | boolean | No | Include the total face count detected |
| `verificationConfig.resultParameterConfig.includeFailedReason` | boolean | Include the failed reason |
| `verificationConfig.securityConfig` | object | No | Security related options influencing verification request validation |
| `verificationConfig.securityConfig.forceSignedInput` | boolean | No | When true, input payloads must be signed. **Default: `true`** (strongly recommended — see [security guidance](/redirect/security/#incoming-signed-verification-url-request-integrity)) |
| `verificationConfig.sessionOverrideConfig` | object | No | Settings that allow selectively overriding verification behavior per session |
| `verificationConfig.sessionOverrideConfig.allowVerifierOverrides` | boolean | No | Allows overriding which verifiers are enabled/disabled |
| `verificationConfig.sessionOverrideConfig.allowResultParameterOverrides` | boolean | No | Allows overriding which result parameters are returned |
| `verificationConfig.sessionOverrideConfig.allowRedirectOverrides` | boolean | No | Allows overriding redirect URLs |
| `verificationConfig.webhookConfig` | object | No | Webhook configuration for server-side event notifications |
| `verificationConfig.webhookConfig.eventCallbackUrl` | string | No | URL to which a `VerificationCompleted` event is sent when a session finishes. Omit or leave empty to disable |

**Response Example:**

```json
{
  "verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf"
}
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| `verificationId` | string | Identifier of the updated verification configuration |

**Example Request:**

```bash
curl -X PUT "https://verifeye-service-api-eu.realeyes.ai/v1/verification/update" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Verification",
    "verificationConfig": {
      "verifierConfigs": {
        "liveness": {
          "type": "Verification",
          "challengeType": "Balanced"
        },
        "age": {
          "type": "CalculationOnly"
        },
        "faceRecognition": {
          "type": "Disabled"
        },
        "gender": {
          "type": "CalculationOnly"
        }
      },
      "redirectConfig": {
        "passedUrl": "https://example.com?result=passed",
        "failedUrl": "https://example.com?result=failed"
      },
      "resultParameterConfig": {
        "includeSignature": true,
        "includeSessionId": true,
        "includeFaceId": true,
        "includeAge": true,
        "includeGender": true,
        "includeVerificationResult": true,
        "includeCustomInputParameters": true,
        "includeLivenessCheckResult": true,
        "includeAgeVerificationResult": true,
        "includeGenderVerificationResult": false,
        "includeFaceRecognitionResult": true,
        "includeCorrelationId": true,
        "includeTotalFaceCount": true,
        "includeFailedReason": true
      },
      "securityConfig": {
        "forceSignedInput": true
      },
      "sessionOverrideConfig": {
        "allowVerifierOverrides": true,
        "allowResultParameterOverrides": false,
        "allowRedirectOverrides": false
      },
      "webhookConfig": {
        "eventCallbackUrl": "https://your-server.example.com/webhook"
      }
    },
    "verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf"
  }'
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `401` - Unauthorized - Missing or invalid authentication
- `404` - Not Found - Verification configuration not found
- `409` - Conflict - A verification configuration with the same name already exists

---

### Delete Verification

Delete a verification configuration.

**Endpoint:** `DELETE /v1/verification/delete`

**Authentication:** API Key or Bearer Token

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `verificationId` | string | Yes | The ID of the verification configuration to delete |

**Example Request:**

```bash
curl -X DELETE "https://verifeye-service-api-eu.realeyes.ai/v1/verification/delete?verificationId=39e00c96-6431-4b2e-8707-2fb80e561fbf" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `401` - Unauthorized - Missing or invalid authentication
- `404` - Not Found - Verification configuration not found

---

### Get Session Result

Returns all available verification results for a given verification session, regardless of the result parameter configuration. The session must belong to the authenticated account and must have been created within the last 7 days.

!!!tip
This endpoint is intended for **server-side use only**. It allows you to retrieve the raw verification results of any session created under your account without being constrained by what the verification configuration was set up to expose.
!!!

**Endpoint:** `GET /v1/verification/get-session-result`

**Authentication:** API Key or Bearer Token

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `verificationSessionId` | string | Yes | The ID of the verification session to retrieve results for |

**Response Example:**

```json
{
  "verificationSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verificationResult": "Pass",
  "verificationFailedReasons": ["noFace"],
  "livenessVerificationResult": "Pass",
  "ageVerificationResult": "Pass",
  "estimatedAge": 30.5,
  "genderVerificationResult": "Pass",
  "estimatedGender": "Male",
  "faceRecognitionResult": "Pass",
  "faceId": "face-uuid-here",
  "correlationId": "corr-uuid-here",
  "totalFaceCount": 1,
  "customInputParameters": {
    "userId": "user123",
    "campaignId": "camp456"
  }
}
```

**Response Fields:**

| Field | Type | Description |
|-------|------|-------------|
| `verificationSessionId` | string | The ID of the verification session |
| `verificationResult` | string | Overall verification outcome (Pass, Fail). Null if not yet determined |
| `verificationFailedReasons` | array | List of categorised reasons why the verification failed. Possible values: `consentDeclined`, `cameraAccessError`, `noFace`, `multipleFaces`, `timeout`, `others`. Null if not available |
| `livenessVerificationResult` | string | Result of the liveness check (Pass, Fail). Null if liveness was not performed |
| `ageVerificationResult` | string | Result of the age verification (Pass, Fail). Null if age verification was not performed |
| `estimatedAge` | number | Estimated age of the subject. Null if age estimation was not performed |
| `genderVerificationResult` | string | Result of the gender verification (Pass, Fail). Null if gender verification was not performed |
| `estimatedGender` | string | Estimated gender of the subject. Null if gender estimation was not performed |
| `faceRecognitionResult` | string | Result of the face recognition check (Pass, Fail). Null if face recognition was not performed |
| `faceId` | string | Identifier of the recognised face. Null if face recognition was not performed |
| `correlationId` | string | Correlation identifier for tracing the session request. Null if not captured |
| `totalFaceCount` | integer | Total number of faces detected in the input. Null if not captured |
| `customInputParameters` | object | Key-value pairs of custom parameters passed in the original session request query string. Reserved system parameters are excluded. For the full list of reserved parameter names, see [Parameters](/redirect/parameters/#reserved-parameters). Null if no custom parameters were present |

**Example Request:**

```bash
curl -X GET "https://verifeye-service-api-eu.realeyes.ai/v1/verification/get-session-result?verificationSessionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"
```

**Response Codes:**
- `200` - Success
- `400` - Bad Request - Invalid parameters
- `404` - Not Found - Session does not exist, does not belong to the authenticated account or is older than 7 days

---

### Health Check

Check the API health status.

**Endpoint:** `GET /v1/healthz`

**Authentication:** None required

**Response Example:**

```
2026-02-08T11:34:54.3015450Z
```

**Response Fields:**

| Name | Type | Description |
|------|------|-------------|
| (response body) | string | The server UTC time in ISO 8601 format |

**Example Request:**

```bash
curl -X GET "https://verifeye-service-api-eu.realeyes.ai/v1/healthz"
```

**Response Codes:**
- `200` - API is healthy

---

## Common Response Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Missing or invalid authentication |
| `403` | Forbidden - Valid authentication but account not found or insufficient permissions |
| `404` | Not Found - Resource not found |
| `500` | Internal Server Error |

---

## Swagger Documentation

Interactive API documentation is available via Swagger UI:

- **EU**: [https://verifeye-service-api-eu.realeyes.ai/swagger/](https://verifeye-service-api-eu.realeyes.ai/swagger/)
- **US**: [https://verifeye-service-api-us.realeyes.ai/swagger/](https://verifeye-service-api-us.realeyes.ai/swagger/)

---

*Last updated: 2026-03-31*