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
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
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:
{
"queryString": "key1=value1&key2=value2...keyN=valueN"
}Request Parameters:
Response Example:
{
"signature": "THE_SIGNATURE",
"signedQueryString": "key1=value1&key2=value2...keyN=valueN&reSignature=THE_SIGNATURE"
}Response Fields:
Example Request:
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"
}'Response Codes:
200- Success400- Bad Request - Invalid parameters401- Unauthorized - Missing or invalid authentication
Validate Signature
Validates the signature of the request using the query string and the signature inside the query string.
Endpoint: POST /v1/signature/validate
Authentication: API Key or Bearer Token
Request Body:
{
"queryString": "key1=value1&key2=value2...keyN=valueN&reSignature=THE_SIGNATURE"
}Request Parameters:
Response Example:
{
"result": "Valid"
}Response Fields:
Example Request:
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- Success400- Bad Request - Invalid parameters401- 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:
Response Example:
{
"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:
Example Request:
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- Success400- Bad Request - Invalid parameters401- Unauthorized - Missing or invalid authentication404- 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:
{
"verifications": [
{
"verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf",
"name": "Test Verification",
"created": "2026-02-01T00:00:00Z",
"lastModified": "2026-02-01T00:00:00Z"
}
]
}Response Fields:
Example Request:
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- Success401- 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
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.
Endpoint: POST /v1/verification/create
Authentication: API Key or Bearer Token
Request Body:
{
"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:
Response Example:
{
"verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf"
}Response Fields:
Example Request:
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- Success400- Bad Request - Invalid parameters401- Unauthorized - Missing or invalid authentication409- 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.
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.
Endpoint: POST /v1/verification/create-or-update
Authentication: API Key or Bearer Token
Request Body:
{
"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:
Response Example:
{
"verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf",
"wasCreated": true
}Response Fields:
Example Request:
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- Success400- Bad Request - Invalid parameters401- Unauthorized - Missing or invalid authentication
Update Verification
Update a verification configuration.
Endpoint: PUT /v1/verification/update
Authentication: API Key or Bearer Token
Request Body:
{
"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:
Response Example:
{
"verificationId": "39e00c96-6431-4b2e-8707-2fb80e561fbf"
}Response Fields:
Example Request:
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- Success400- Bad Request - Invalid parameters401- Unauthorized - Missing or invalid authentication404- Not Found - Verification configuration not found409- 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:
Example Request:
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- Success400- Bad Request - Invalid parameters401- Unauthorized - Missing or invalid authentication404- 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.
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:
Response Example:
{
"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:
Example Request:
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- Success400- Bad Request - Invalid parameters404- 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.3015450ZResponse Fields:
Example Request:
curl -X GET "https://verifeye-service-api-eu.realeyes.ai/v1/healthz"Response Codes:
200- API is healthy
Common Response Codes
Swagger Documentation
Interactive API documentation is available via Swagger UI:
- EU: https://verifeye-service-api-eu.realeyes.ai/swagger/
- US: https://verifeye-service-api-us.realeyes.ai/swagger/
Last updated: 2026-03-31