# Verify API

The Verify API provides duplicate detection and JWT token generation services for identity verification workflows.

Key Features:

JWT Token Generation: Generate time-limited JWT tokens for secure API authentication
Duplicate Detection: Verify if a user already exists in a face recognition collection
Collection Management: Reset collections by deleting all entries
Face Deletion: Remove specific faces from collections

# Base URLs

# Production Endpoints

EU: https://verify-api-eu.realeyes.ai/api/v1/verify
US: https://verify-api-us.realeyes.ai/api/v1/verify

# Authentication

The Verify API supports two authentication methods:

# 1. API Key Authentication (X-API-Key Header)

Header Format:

X-API-Key: <your-api-key>

# 2. JWT Bearer Token Authentication

Header Format:

Authorization: Bearer <jwt-token>

Note: Use the /get-token endpoint to generate JWT tokens.

# Endpoints

# 1. Get Token

Generate a JWT token for API authentication.

Endpoint: GET /get-token

Authentication: API Key (X-API-Key header)

Query Parameters:

expirationInSeconds (integer, optional): Token expiration time in seconds
- Minimum: 60 seconds
- Maximum: 3600 seconds (1 hour)
- Default: 900 seconds (15 minutes)

Response:

eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9...

cURL Example:

curl -X GET "https://verify-api-eu.realeyes.ai/api/v1/verify/get-token?expirationInSeconds=900" \
  -H "X-API-Key: your-api-key-here"

# 2. Verify Duplicate

Check if a user already exists in a face recognition collection.

Endpoint: POST /verify-duplicate

Authentication: API Key or JWT Bearer Token

Query Parameters:

collectionName (string, required): Name of the collection to check
externalIdentifier (string, optional): External identifier for the user if not already in the collection
includeDemographicalInfo (boolean, required): Whether to include age and gender information

Request Body:

{
  "imageData": "base64-encoded-image-string"
}

Response:

{
  "collectionName": "my-collection",
  "faceId": "face-123",
  "hasFace": true,
  "demographicalInfo": {
    "age": "25-35",
    "gender": "Male",
    "genderConfidence": 98.5
  },
  "isDuplicate": false,
  "isCollectionFull": false,
  "externalIdentifierOfDuplicate": null,
  "telemetry": [
    {
      "name": "DetectFace",
      "durationInMilliseconds": 150
    }
  ]
}

Response Fields:

collectionName (string): Name of the collection used
faceId (string): Face ID if a face was detected, null otherwise
hasFace (boolean): Whether a face was detected in the image
demographicalInfo (object): Age and gender information (only if includeDemographicalInfo is true)
- age (string): Age range (e.g., "25-35")
- gender (string): "Male" or "Female"
- genderConfidence (float): Confidence level for gender detection
isDuplicate (boolean): Whether the user already exists in the collection
isCollectionFull (boolean): Whether the collection has reached its maximum capacity
externalIdentifierOfDuplicate (string): External identifier of the duplicate user (only if isDuplicate is true)
telemetry (array): Performance metrics for each processing step

cURL Example:

curl -X POST "https://verify-api-eu.realeyes.ai/api/v1/verify/verify-duplicate?collectionName=my-collection&externalIdentifier=user123&includeDemographicalInfo=true" \
  -H "Authorization: Bearer eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageData": "base64-encoded-image-string"
  }'

# 3. Reset Collection

Delete all entries from a collection.

Endpoint: POST /reset-collection

Authentication: API Key or JWT Bearer Token

Query Parameters:

collectionName (string, required): Name of the collection to reset
entryLimit (integer, optional): Maximum number of entries to delete (default: 50)

Response:

{
  "numberOfEntriesDeleted": 42,
  "errorMessage": null
}

Response Fields:

numberOfEntriesDeleted (integer): Number of entries deleted from the collection
errorMessage (string): Error message if the operation failed, null otherwise

cURL Example:

curl -X POST "https://verify-api-eu.realeyes.ai/api/v1/verify/reset-collection?collectionName=my-collection&entryLimit=100" \
  -H "Authorization: Bearer eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

# Common Response Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters or collection not found
`401`	Unauthorized - Invalid or missing authentication
`429`	Too Many Requests - Request throttled

# Swagger Documentation

Interactive API documentation is available via Swagger UI:

Last updated: 2026-01-27