ThirdFactor AI API Gateway

https://third-factor.readthedocs.io/en/latest/
Admin
ThirdFactor AI API Gateway is an AI-powered identity verification and document understanding...
Tokens:17,887
Snippets:92
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Full Webhook Notification Payload Example for ThirdFactor KYC

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

An example of the complete payload structure received via webhook when the KYC process is completed. It includes detailed logs for document detection, gesture detection, and face detection.

```json
{
  "documentDetectionLog": [
    {
      "created_at": "2026-01-27 10:43:26.644142+00:00",
      "is_verified": true,
      "nationality": "nepali",
      "document_number": "11111111",
      "photo": "<BASE64_STRING_OF_SCANNED_DOC>",
      "original_photo": "<BASE64_STRING_OF_ORIGINAL_FRAME>",
      "claimed_doc_type": "citizenship-back",
      "detected_doc_type": "citizenship-back",
      "reason": "Valid Type"
    },
    {
      "created_at": "2026-01-27 10:43:27.201931+00:00",
      "is_verified": true,
      "nationality": "nepali",
      "document_number": "11111111",
      "photo": "<BASE64_STRING>",
      "original_photo": "<BASE64_STRING>",
      "percentage_match": 64.7401,
      "claimed_doc_type": "citizenship-front",
      "detected_doc_type": "citizenship-front",
      "reason": "Valid"
    }
  ],
  "documentPhoto": [
    {
      "created_at": "2026-01-27 10:43:26.644142+00:00",
      "is_verified": true,
      "nationality": "nepali",
      "document_number": "11111111",
      "photo": "<BASE64_STRING>",
      "claimed_doc_type": "citizenship-back",
      "detected_doc_type": "citizenship-back",
      "reason": "Valid Type"
    }
  ],
  "gestureDetectionLog": [
    {
      "created_at": "2026-01-27 10:43:10.255518+00:00",
      "is_verified": true,
      "challenged_gesture": "Thumb_Down",
      "detected_gesture": "Thumb_Down",
      "percentage_match": 80.8998,
      "photo": "<BASE64_STRING_OF_GESTURE>",
      "reason": "Valid",
      "is_passive_live": true,
      "passive_score": 99.998
    }
  ],
  "faceDetectionLog": [
    {
      "created_at": "2026-01-27 10:42:58.538744+00:00",
      "is_verified": false,
      "photo": "<BASE64_STRING_OF_FACE>",
      "age": "-1",
      "gender": "N/A",
      "reason": "Face Occluded or Blurry.",
      "force_next": true
    }
  ],
  "nationality": "nepali",
  "completed_at": "2026-01-27T10:43:27.882837+00:00",
  "bypassed": 1,
  "document_uplaod_retries": 2,
  "session": "F7bgp2I",
  "faceDetectionSuccess": false,
  "document_number": "11111111",
  "gestureSuccess": true,
  "gender": "N/A",
  "documentDetectionSuccess": true,
  "in_progress": 0,
  "age": -1,
  "expires_at": "2026-01-29T18:24:26.141586+00:00",
  "userPhoto": "<BASE64_STRING_OF_USER>",
  "gesture_photo": "<BASE64_STRING>",
  "gesture_challenge": [
    "Thumb_Down"
  ],
  "percentage_match": 64.7401,
  "face_detection_retries": 1,
  "allow_force_next": 1,
  "started_at": "2026-01-27T10:42:46.141586+00:00",
  "gesture_verification_retries": 1,
  "label": "Jane User",
  "secondary_label": "jane",
  "identifier": "1715",
  "jwt": "<JWT_TOKEN>",
  "is_verified": true,
  "forced_next": false,
  "signature": "<SIGNATURE>"
}
```

--------------------------------

### Error Response for Insufficient Credits in ThirdFactor KYC

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

An example of an error response when the user account has insufficient credits to generate a KYC URL.

```json
{
  "error": "Insufficient credits. Available credits: 0. 1 credit is required to generate KYC URL."
}
```

--------------------------------

### Liveness Analysis Response

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Example response for the /api/analyze-liveness endpoint, providing liveness and antispoof scores, blink count, and base64 encoded frames.

```json
{
  "analysis": {
    "liveness_score": "0.70",
    "antispoof_score": "1.00",
    "blink_count": 0
  },
  "is_live": true,
  "frames": [
    "data:image/jpeg;base64,/9j/4AAQ...",
    "data:image/jpeg;base64,/9j/4AAQ..."
  ]
}
```

--------------------------------

### GET /api/v1/business_doc_detection/health

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Checks the status of the Business Document Detection service.

```APIDOC
## GET /api/v1/business_doc_detection/health

### Description
Checks the status of the Business Document Detection service.

### Method
GET

### Endpoint
/api/v1/business_doc_detection/health

### Response
#### Success Response (200)
- **status** (String) - Service status.

#### Response Example
{
  "status": "Ok"
}
```

--------------------------------

### GET /api/v1/business_doc_detection/health

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Checks the operational status of the Business Document Detection service.

```APIDOC
## GET /api/v1/business_doc_detection/health

### Description
Checks the operational status of the Business Document Detection service.

### Method
GET

### Endpoint
/api/v1/business_doc_detection/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (String) - The status of the service (e.g., "Ok").

#### Response Example
```json
{ "status": "Ok" }
```
```

--------------------------------

### GET /health

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Verifies that the API service is operational.

```APIDOC
## GET /health

### Description
Verifies that the API service is operational.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The operational status of the service.
- **service** (string) - The name of the service.

#### Response Example
{
  "status": "healthy",
  "service": "thirdfactor-ai-gateway"
}
```

--------------------------------

### Error Response for Invalid Token in ThirdFactor KYC

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

An example of an error response when the provided JWT token is invalid or does not belong to the specified tenant.

```json
{
  "error": "Invalid token or token does not belong to tenant: <Org Name>"
}
```

--------------------------------

### Ingest Face for 1:N Search using Python

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Ingests an image into the database for future 1:N reverse face searches. The endpoint expects a binary image file and returns the filename and assigned ID upon successful ingestion.

```python
import requests

url = "/batch_ingest"
files = {
    'file': open('path/to/your/image.jpg', 'rb')
}

response = requests.post(url, files=files)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### Compare Face (1:N) using Python

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Performs a reverse search to find a face match within a pre-ingested database. This endpoint accepts a binary image file and returns a list of potential matches with their scores.

```python
import requests

url = "/api/face-reverse-search"
files = {
    'file': open('path/to/your/image.jpg', 'rb')
}

response = requests.post(url, files=files)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### POST /api/v1/business_doc_detection/inference/folder

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Batch processes images within a specified folder path.

```APIDOC
## POST /api/v1/business_doc_detection/inference/folder

### Description
Batch processes images within a specified folder path.

### Method
POST

### Endpoint
/api/v1/business_doc_detection/inference/folder

### Parameters
#### Request Body (multipart/form-data)
- **folder_path** (Text) - Required - Path to the folder containing images.
- **confidence** (Number) - Optional - Confidence threshold. Default: 0.7

### Response
#### Success Response (200)
- **total_images** (Number) - Total images processed.
- **correct_predictions** (Number) - Count of correct predictions.
- **incorrect_predictions** (Number) - Count of incorrect predictions.
- **no_predictions** (Number) - Count of images with no prediction.
- **files** (Array) - List of individual file results.

#### Response Example
{
  "total_images": 10,
  "correct_predictions": 8,
  "incorrect_predictions": 1,
  "no_predictions": 1,
  "files": [
     { "filename": "doc1.jpg", "predicted_class": "vat", "confidence": 0.98 },
     { "filename": "doc2.jpg", "predicted_class": "pan", "confidence": 0.92 }
  ]
}
```

--------------------------------

### POST /api/analyze-liveness

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Analyzes a video file to verify liveness and detect potential spoofing attempts.

```APIDOC
## POST /api/analyze-liveness

### Description
Analyzes a video file to verify liveness and detecting potential spoofing attempts.

### Method
POST

### Endpoint
/api/analyze-liveness

### Parameters
#### Request Body
- **video** (File) - Required - The video file to analyze (multipart/form-data).

### Request Example
Content-Type: multipart/form-data

### Response
#### Success Response (200)
- **analysis** (object) - Liveness and antispoof scores.
- **is_live** (boolean) - Result of the liveness check.

#### Response Example
{
  "analysis": {
    "liveness_score": "0.70",
    "antispoof_score": "1.00",
    "blink_count": 0
  },
  "is_live": true
}
```

--------------------------------

### Detect and Crop Document using Python

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Automatically detects the type of document and returns a cropped image. This endpoint requires a base64 encoded image string and supports various document types.

```python
import requests
import base64

def encode_image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

url = "/type-of-document-crop/"

image_path = 'path/to/your/document.jpg'
base64_image = encode_image_to_base64(image_path)

data = {
    'base64_image': base64_image
}

response = requests.post(url, data=data)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### Analyze Liveness API

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Analyzes a video file to verify liveness and detect potential spoofing attempts. This endpoint does not require authentication.

```APIDOC
## POST /api/analyze-liveness

### Description
Analyzes a video file to verify liveness and detecting potential spoofing attempts.

### Method
POST

### Endpoint
/api/analyze-liveness

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **video** (File) - Required - The video file to analyze.

### Request Example
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="video"; filename="example.mp4"
Content-Type: video/mp4

[Binary video data]
--boundary--

### Response
#### Success Response (200 OK)
- **analysis** (object) - Object containing analysis results.
  - **liveness_score** (string) - The score indicating the likelihood of the video being live.
  - **antispoof_score** (string) - The score indicating the likelihood of the video not being a spoof attempt.
  - **blink_count** (integer) - The number of blinks detected in the video.
- **antispoof_score** (string) - The overall anti-spoof score.
- **blink_count** (integer) - The overall blink count.
- **liveness_score** (string) - The overall liveness score.
- **frames** (array) - An array of Base64 encoded image strings for each frame analyzed.
- **is_live** (boolean) - Indicates whether the video is determined to be live.

#### Response Example
```json
{
  "analysis": {
    "liveness_score": "0.70",
    "antispoof_score": "1.00",
    "blink_count": 0
  },
  "antispoof_score": "1.00",
  "blink_count": 0,
  "liveness_score": "0.70",
  "frames": [
    0: "data:image/jpeg;base64,/9j/4AAQ...",
    1:"data:image/jpeg;base64,/9j/4AAQ..."
  ],
  "is_live": true
}
```
```

--------------------------------

### Verify API health status

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

The response structure for the GET /health endpoint. This endpoint is public and confirms that the ThirdFactor AI gateway service is operational.

```json
{
  "status": "healthy",
  "service": "thirdfactor-ai-gateway"
}
```

--------------------------------

### POST /type-of-document-crop/

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Automatically detects the type of document and returns a cropped image.

```APIDOC
## POST /type-of-document-crop/

### Description
Automatically detects the type of document and returns a cropped image.

### Method
POST

### Endpoint
/type-of-document-crop/

### Parameters
#### Request Body
- **base64_image** (string) - Required - Base64 encoded string of the document image.

### Request Example
{
  "base64_image": "data:image/jpeg;base64,..."
}

### Response
#### Success Response (200)
- **document_type** (string) - The detected document type.
- **score** (float) - Confidence score.
- **cropped_image** (string) - Base64 encoded cropped image.

#### Response Example
{
  "document_type": "national-id-front",
  "score": 0.98,
  "cropped_image": "data:image/jpeg;base64,..."
}
```

--------------------------------

### POST /api/v1/business_doc_detection/inference/single

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Detects the business document class in a single uploaded image.

```APIDOC
## POST /api/v1/business_doc_detection/inference/single

### Description
Detects the business document class in a single uploaded image.

### Method
POST

### Endpoint
/api/v1/business_doc_detection/inference/single

### Parameters
#### Request Body (multipart/form-data)
- **file** (File) - Required - The image file to analyze.
- **expected_class** (Text) - Optional - The expected class name for validation.
- **confidence** (Number) - Optional - Confidence threshold. Default: 0.7

### Request Example
Content-Type: multipart/form-data

### Response
#### Success Response (200)
- **filename** (String) - Name of the uploaded file.
- **predicted_class** (String) - The detected document class.
- **expected_class** (String) - The validated class.
- **confidence** (Number) - Detection confidence score.
- **is_correct** (Boolean) - Whether the prediction matches the expected class.
- **bbox** (Array) - Bounding box coordinates.
- **output_path** (String) - Path to the processed result.

#### Response Example
{
  "filename": "image.jpg",
  "predicted_class": "business_vat_pan",
  "expected_class": "business_vat_pan",
  "confidence": 0.95,
  "is_correct": true,
  "bbox": [100, 150, 400, 500],
  "output_path": "/app/media_files/results/image.jpg"
}
```

--------------------------------

### POST /api/v1/business_doc_detection/inference/folder

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Processes images within a specified folder to detect business documents. It returns a summary of predictions and details for each file.

```APIDOC
## POST /api/v1/business_doc_detection/inference/folder

### Description
Processes images within a specified folder to detect business documents. It returns a summary of predictions and details for each file.

### Method
POST

### Endpoint
/api/v1/business_doc_detection/inference/folder

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **folder_path** (Text) - Required - Path to the folder containing images.
- **confidence** (Number) - Optional - Confidence threshold. Default: 0.7

### Request Example
```
--boundary
Content-Disposition: form-data; name="folder_path"

/path/to/your/images

--boundary
Content-Disposition: form-data; name="confidence"

0.8
--boundary--
```

### Response
#### Success Response (200)
- **total_images** (Number) - Total number of images processed.
- **correct_predictions** (Number) - Number of images with correct predictions.
- **incorrect_predictions** (Number) - Number of images with incorrect predictions.
- **no_predictions** (Number) - Number of images with no predictions.
- **files** (Array) - List of prediction details for each file.
  - **filename** (String) - The name of the file.
  - **predicted_class** (String) - The predicted class of the document.
  - **confidence** (Number) - The confidence score of the prediction.

#### Response Example
```json
{
  "total_images": 10,
  "correct_predictions": 8,
  "incorrect_predictions": 1,
  "no_predictions": 1,
  "files": [
    { "filename": "doc1.jpg", "predicted_class": "vat", "confidence": 0.98 },
    { "filename": "doc2.jpg", "predicted_class": "pan", "confidence": 0.92 }
  ]
}
```
```

--------------------------------

### POST /batch_ingest

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Ingests an image into the database for future 1:N reverse face searches.

```APIDOC
## POST /batch_ingest

### Description
Ingests an image into the database for future 1:N reverse face searches.

### Method
POST

### Endpoint
/batch_ingest

### Parameters
#### Request Body
- **Binary File** (binary) - Required - Upload the image file as the raw body content.

### Request Example
[Binary Image Data]

### Response
#### Success Response (200)
- **results** (array) - List of ingested file details.

#### Response Example
{
    "results": [
        { "filename": "test.jpeg", "id": 35 }
    ]
}
```

--------------------------------

### Successful Response for ThirdFactor KYC URL Generation

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

The expected successful response (200 OK) when generating a KYC URL. It includes the dynamic URL for the SDK and the number of remaining credits.

```json
{
    "url": "https://endpoint/tfauth/start?",
    "remaining_credits": 97
}
```

--------------------------------

### POST /detect-face/

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Detects faces and optional attributes in a provided base64 encoded image.

```APIDOC
## POST /detect-face/

### Description
Detects faces and optional attributes (age range, gender, occlusion, etc.) within an image.

### Method
POST

### Endpoint
/detect-face/

### Parameters
#### Request Body
- **base64_image** (string) - Required - Base64 encoded string of the image containing the face.

### Request Example
{
  "base64_image": "/9j/4AAQSkZJRgABAQ..."
}

### Response
#### Success Response (200)
- **status** (string) - Status of the detection process.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Authentication & Base Configuration

Source: https://third-factor.readthedocs.io/en/latest/index.html

Configuration details for accessing the ThirdFactor AI API, including base URL and authentication requirements.

```APIDOC
## Authentication

### Description
The API uses HTTP Bearer Token authentication. All requests must include the `Authorization` header.

### Header
`Authorization: Bearer <YOUR_ACCESS_TOKEN>`

### Base URL
`https://<YOUR_API_ENDPOINT>`
```

--------------------------------

### POST https://<thirdfactor_URL>/tfauth/get-kyc-url/

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Generates a dynamic URL for the ThirdFactor SDK authentication process. Requires a pre-generated JWT token.

```APIDOC
## POST https://<thirdfactor_URL>/tfauth/get-kyc-url/

### Description
Generates a dynamic URL for the ThirdFactor SDK authentication process. Requires a pre-generated JWT token.

### Method
POST

### Endpoint
https://<thirdfactor_URL>/tfauth/get-kyc-url/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **jwt_token** (string) - Required - The generated JWT token signed with HS256.

### Request Example
```json
{
    "jwt_token": "<YOUR_GENERATED_JWT_TOKEN>"
}
```

### Response
#### Success Response (200 OK)
- **url** (string) - The generated KYC URL.
- **remaining_credits** (integer) - The number of remaining credits for the account.

#### Response Example
```json
{
    "url": "https://endpoint/tfauth/start?",
    "remaining_credits": 97
}
```

#### Error Response (Invalid Token)
```json
{
  "error": "Invalid token or token does not belong to tenant: <Org Name>"
}
```

#### Error Response (Insufficient Credits)
```json
{
  "error": "Insufficient credits. Available credits: 0. 1 credit is required to generate KYC URL."
}
```
```

--------------------------------

### POST /compare-face/

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Compares two face images to verify if they belong to the same person.

```APIDOC
## POST /compare-face/

### Description
Compares two face images to verify if they belong to the same person.

### Method
POST

### Endpoint
/compare-face/

### Parameters
#### Query Parameters
- **threshold** (float) - Optional - Similarity threshold for matching (Default: 52.0).
- **live_check** (boolean) - Optional - Perform liveness check (Default: false).
- **occlusion_check** (boolean) - Optional - Check for face obstructions (Default: false).

#### Request Body
- **images** (Array) - Required - A JSON array containing two base64 encoded image strings.

### Request Example
[
  "<BASE64_IMAGE_1>",
  "<BASE64_IMAGE_2>"
]

### Response
#### Success Response (200)
- **verified** (boolean) - Whether the faces match.
- **confidence** (float) - Confidence score of the match.
- **percentage_match** (float) - Percentage match value.

#### Response Example
{
  "verified": true,
  "confidence": 98.5,
  "percentage_match": 99.9
}
```

--------------------------------

### POST /api/v1/business_doc_detection/inference/folder

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Batch processes images within a specified folder path for business document detection. This endpoint is part of the Business Document Detection API.

```APIDOC
## POST /api/v1/business_doc_detection/inference/folder

### Description
Batch processes images within a specified folder path.

### Method
POST

### Endpoint
/api/v1/business_doc_detection/inference/folder

### Parameters
#### Request Body
(Details for folder inference parameters are not provided in the source text.)

### Request Example
(Not provided in the source text.)

### Response
(Details for folder inference response are not provided in the source text.)
```

--------------------------------

### Detect Forgery using Python

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Analyzes an image to detect potential manipulation or forgery. This endpoint uses multipart/form-data and returns a forgery status, original image path, and highlighted image path.

```python
import requests

url = "/api/analyze"

files = {
    'file': open('path/to/your/image.jpg', 'rb')
}

response = requests.post(url, files=files)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### Generate KYC URL

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Generates a dynamic URL for the ThirdFactor SDK authentication process. Requires a pre-generated JWT token signed with HS256.

```APIDOC
## POST /tfauth/get-kyc-url/

### Description
Generates a dynamic URL for the ThirdFactor SDK authentication process. To use this endpoint, you must first generate a signed JWT token.

### Method
POST

### Endpoint
`https://<thirdfactor_URL>/tfauth/get-kyc-url/`

### Parameters
#### Request Body
- **jwt_token** (string) - Required - The JWT token generated and signed with your Secret using HMAC SHA256 (HS256).

### Request Example
```json
{
    "jwt_token": "<YOUR_GENERATED_JWT_TOKEN>"
}
```

### Response
#### Success Response (200 OK)
- **url** (string) - The generated URL for the KYC process.
- **remaining_credits** (integer) - The number of remaining credits after this operation.

#### Response Example
```json
{
    "url": "https://endpoint/tfauth/start?",
    "remaining_credits": 97
}
```

#### Error Response (Invalid Token)
- **error** (string) - "Invalid token or token does not belong to tenant: <Org Name>"

#### Error Response (Insufficient Credits)
- **error** (string) - "Insufficient credits. Available credits: 0. 1 credit is required to generate KYC URL."
```

--------------------------------

### POST /type-of-document-crop/

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Automatically detects the type of document and returns a cropped image. Supports various document types like citizenship, driving license, passport, etc.

```APIDOC
## POST /type-of-document-crop/

### Description
Automatically detects the type of document and returns a cropped image.

### Method
POST

### Endpoint
/type-of-document-crop/

### Parameters
#### Query Parameters
None

#### Request Body
- **base64_image** (string) - Required - Base64 encoded string of the document image.

### Request Example
```json
{
  "base64_image": "string"
}
```

### Response
#### Success Response (200 OK)
- **document_type** (string) - The detected document type.
- **score** (number) - The confidence score of the detection.
- **cropped_image** (string) - Base64 encoded string of the cropped image.

#### Response Example
```json
{
  "document_type": "national-id-front",
  "score": 0.98,
  "cropped_image": "data:image/jpeg;base64,/9j/..."
}
```
```

--------------------------------

### POST /detect-face

Source: https://third-factor.readthedocs.io/en/latest/index.html

Detects faces within an image and analyzes facial features.

```APIDOC
## POST /detect-face

### Description
Detects faces within provided images and returns metadata regarding facial features.

### Method
POST

### Endpoint
/detect-face

### Request Body
- **image** (string) - Required - Base64 encoded image string.

### Request Example
{
  "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
}

### Response
#### Success Response (200)
- **faces** (array) - List of detected face objects.

#### Response Example
{
  "faces": [
    { "box": [0, 0, 100, 100], "confidence": 0.99 }
  ]
}
```

--------------------------------

### POST /image-to-base64/

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Converts an uploaded image file into a base64 string for use in analysis endpoints.

```APIDOC
## POST /image-to-base64/

### Description
Converts an uploaded image file into a base64 string. Use this if your client application needs to convert files before sending them to the analysis endpoints.

### Method
POST

### Endpoint
/image-to-base64/

### Parameters
#### Request Body
- **image** (File) - Required - Image file to convert.

### Response
#### Success Response (200)
- **data_url** (string) - The base64 encoded data URL.
- **content_type** (string) - The MIME type of the image.
- **filename** (string) - The original filename.

#### Response Example
{
  "data_url": "data:image/jpeg;base64,/9j/4AAQ...",
  "content_type": "image/jpeg",
  "filename": "uploaded_image.jpg"
}
```

--------------------------------

### Detect Face API

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Detects faces and optional attributes such as age range, gender, and occlusion in an image. Authentication is required.

```APIDOC
## POST /detect-face/

### Description
Detects faces and optional attributes (age range, gender, occlusion, etc.) in an image.

### Method
POST

### Endpoint
/detect-face/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **image** (string) - Required - The image data in Base64 format.
- **attributes** (array of strings) - Optional - A list of attributes to detect (e.g., `["age", "gender", "occlusion"]`).

### Request Example
Content-Type: application/x-www-form-urlencoded

```
image=data:image/jpeg;base64,/9j/4AAQSB...&attributes[]=age&attributes[]=gender
```

### Response
#### Success Response (200 OK - faces found)
- **result** (boolean) - Indicates if faces were detected (`true`).
- **total_faces** (integer) - The total number of faces detected.
- **faces** (array) - An array of face objects, each containing detection details.
  - **confidence** (float) - The confidence score of the face detection.
  - **age_range** (object) - The detected age range.
    - **min_age** (integer) - Minimum detected age.
    - **max_age** (integer) - Maximum detected age.
    - **detected_age** (integer) - The estimated age.
  - **gender** (string) - The detected gender.
  - **occluded** (boolean) - Indicates if the face is occluded.

#### Response Example (faces found)
```json
{
  "result": true,
  "total_faces": 1,
  "faces": [
    {
      "confidence": 0.84,
      "age_range": { "min_age": 27, "max_age": 32, "detected_age": 29 },
      "gender": "Male",
      "occluded": false
    }
  ]
}
```

#### Success Response (200 OK - no faces found)
- **result** (boolean) - Indicates if faces were detected (`false`).
- **total_faces** (integer) - The total number of faces detected (0).
- **faces** (array) - An empty array.

#### Response Example (no faces found)
```json
{ "result": false, "total_faces": 0, "faces": [] }
```
```

--------------------------------

### Webhook Notification (Full Payload)

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Receives a detailed webhook notification from the SDK server when the KYC process is completed. The payload contains logs of the detection and verification process.

```APIDOC
## Webhook Notification

### Description
When the KYC process is completed, the SDK server sends a notification to the `callback` URL specified in the JWT payload. The payload provides a complete log of the detection and verification process.

### Method
POST (to the callback URL provided in the JWT payload)

### Endpoint
`https://your-webhook.com/callback-id` (Example callback URL)

### Parameters
#### Request Body (Example Payload Structure)
- **documentDetectionLog** (array) - Log of document detection events.
  - **created_at** (string) - Timestamp of the event.
  - **is_verified** (boolean) - Whether the document was verified.
  - **nationality** (string) - Nationality associated with the document.
  - **document_number** (string) - The document number.
  - **photo** (string) - Base64 encoded string of the scanned document.
  - **original_photo** (string) - Base64 encoded string of the original frame.
  - **claimed_doc_type** (string) - The claimed document type.
  - **detected_doc_type** (string) - The detected document type.
  - **reason** (string) - Reason for the detection result.
- **documentPhoto** (array) - Log of document photo events.
- **gestureDetectionLog** (array) - Log of gesture detection events.
- **faceDetectionLog** (array) - Log of face detection events.
- **nationality** (string) - Nationality of the user.
- **completed_at** (string) - Timestamp when the KYC process was completed.
- **bypassed** (integer) - Indicates if the process was bypassed.
- **session** (string) - The session ID.
- **faceDetectionSuccess** (boolean) - Whether face detection was successful.
- **document_number** (string) - The document number.
- **gestureSuccess** (boolean) - Whether gesture detection was successful.
- **gender** (string) - Gender of the user.
- **documentDetectionSuccess** (boolean) - Whether document detection was successful.
- **in_progress** (integer) - Indicates if the process is still in progress.
- **age** (integer) - Age of the user.
- **expires_at** (string) - Expiration timestamp of the session.
- **userPhoto** (string) - Base64 encoded string of the user's photo.
- **gesture_photo** (string) - Base64 encoded string of the gesture photo.
- **gesture_challenge** (array) - List of gestures challenged.
- **percentage_match** (float) - Percentage match score.
- **face_detection_retries** (integer) - Number of retries for face detection.
- **allow_force_next** (integer) - Indicates if forcing the next step is allowed.
- **started_at** (string) - Timestamp when the KYC process started.
- **gesture_verification_retries** (integer) - Number of retries for gesture verification.
- **label** (string) - User label.
- **secondary_label** (string) - User secondary label.
- **identifier** (string) - User identifier.
- **jwt** (string) - The JWT token used for the session.
- **is_verified** (boolean) - Whether the user is verified.
- **forced_next** (boolean) - Indicates if the next step was forced.
- **signature** (string) - Signature of the verification.

### Response Example
```json
{
  "documentDetectionLog": [
    {
      "created_at": "2026-01-27 10:43:26.644142+00:00",
      "is_verified": true,
      "nationality": "nepali",
      "document_number": "11111111",
      "photo": "<BASE64_STRING_OF_SCANNED_DOC>",
      "original_photo": "<BASE64_STRING_OF_ORIGINAL_FRAME>",
      "claimed_doc_type": "citizenship-back",
      "detected_doc_type": "citizenship-back",
      "reason": "Valid Type"
    }
  ],
  "documentPhoto": [
    {
      "created_at": "2026-01-27 10:43:26.644142+00:00",
      "is_verified": true,
      "nationality": "nepali",
      "document_number": "11111111",
      "photo": "<BASE64_STRING>",
      "claimed_doc_type": "citizenship-back",
      "detected_doc_type": "citizenship-back",
      "reason": "Valid Type"
    }
  ],
  "gestureDetectionLog": [
    {
      "created_at": "2026-01-27 10:43:10.255518+00:00",
      "is_verified": true,
      "challenged_gesture": "Thumb_Down",
      "detected_gesture": "Thumb_Down",
      "percentage_match": 80.8998,
      "photo": "<BASE64_STRING_OF_GESTURE>",
      "reason": "Valid",
      "is_passive_live": true,
      "passive_score": 99.998
    }
  ],
  "faceDetectionLog": [
    {
      "created_at": "2026-01-27 10:42:58.538744+00:00",
      "is_verified": false,
      "photo": "<BASE64_STRING_OF_FACE>",
      "age": "-1",
      "gender": "N/A",
      "reason": "Face Occluded or Blurry.",
      "force_next": true
    }
  ],
  "nationality": "nepali",
  "completed_at": "2026-01-27T10:43:27.882837+00:00",
  "bypassed": 1,
  "document_uplaod_retries": 2,
  "session": "F7bgp2I",
  "faceDetectionSuccess": false,
  "document_number": "11111111",
  "gestureSuccess": true,
  "gender": "N/A",
  "documentDetectionSuccess": true,
  "in_progress": 0,
  "age": -1,
  "expires_at": "2026-01-29T18:24:26.141586+00:00",
  "userPhoto": "<BASE64_STRING_OF_USER>",
  "gesture_photo": "<BASE64_STRING>",
  "gesture_challenge": [
    "Thumb_Down"
  ],
  "percentage_match": 64.7401,
  "face_detection_retries": 1,
  "allow_force_next": 1,
  "started_at": "2026-01-27T10:42:46.141586+00:00",
  "gesture_verification_retries": 1,
  "label": "Jane User",
  "secondary_label": "jane",
  "identifier": "1715",
  "jwt": "<JWT_TOKEN>",
  "is_verified": true,
  "forced_next": false,
  "signature": "<SIGNATURE>"
}
```
```

--------------------------------

### Face Comparison (1:1) Request and Response

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Demonstrates the 1:1 face comparison process, requiring a JSON array of two base64 encoded images and returning a verification status with confidence metrics.

```json
[
  "<BASE64_IMAGE_1>",
  "<BASE64_IMAGE_2>"
]
```

```json
{
  "verified": true,
  "confidence": 98.5,
  "percentage_match": 99.9
}
```

--------------------------------

### POST /document-extract-information/

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Performs OCR and structured information extraction from supported document types.

```APIDOC
## POST /document-extract-information/

### Description
Performs OCR and structured information extraction from supported document types.

### Method
POST

### Endpoint
/document-extract-information/

### Parameters
#### Request Body
- **base64_image** (string) - Required - Base64 encoded string of the document image.

### Request Example
{
  "base64_image": "data:image/jpeg;base64,..."
}

### Response
#### Success Response (200)
- **success** (boolean) - Status of extraction.
- **data** (object) - Extracted information fields.

#### Response Example
{
  "success": true,
  "data": {
    "id_number": "XXXX-XXXX-XXXX",
    "name": "Jane Smith",
    "detected_type": "national-id"
  }
}
```

--------------------------------

### Detect Forgery in Image

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

This API analyzes an image to detect potential manipulation or forgery. It accepts an image file (PNG format) as multipart/form-data. The response indicates whether the image is forged, provides paths to the original and highlighted images, and includes an analysis status with a forgery score and details.

```json
{
    "is_forged": false,
    "original_image": "/static/uploads/original_ID.png",
    "highlighted_image": "/static/uploads/overlay_ID.png",
    "analysis": {
        "status": "AUTHENTIC",
        "forgery_score": "0.13",
        "details": "No manipulation detected"
    }
}
```

--------------------------------

### Compare Face (1:1) API

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Compares two face images to verify if they belong to the same person. Authentication is required.

```APIDOC
## POST /compare-face/

### Description
Compares two face images to verify if they belong to the same person.

### Method
POST

### Endpoint
/compare-face/

### Parameters
#### Path Parameters
None

#### Query Parameters
- **threshold** (float) - Optional - Similarity threshold (float) for matching. Defaults to `52.0`.
- **live_check** (boolean) - Optional - Performs a liveness check. Defaults to `false`.
- **occlusion_check** (boolean) - Optional - Performs an occlusion check for face obstructions. Defaults to `false`.

#### Request Body
- **body** (JSON Array) - Required - An array containing two Base64 encoded image strings.
  - **"<BASE64_IMAGE_1>"** (string) - The Base64 encoded string of the first face image.
  - **"<BASE64_IMAGE_2>"** (string) - The Base64 encoded string of the second face image.

### Request Example
Content-Type: application/json

```json
[
  "<BASE64_IMAGE_1>",
  "<BASE64_IMAGE_2>"
]
```

### Response
#### Success Response (200 OK - match)
- **verified** (boolean) - Indicates if the faces are verified to be from the same person (`true`).
- **confidence** (float) - The confidence score of the match.
- **percentage_match** (float) - The percentage match between the two faces.

#### Response Example (match)
```json
{
  "verified": true,
  "confidence": 98.5,
  "percentage_match": 99.9
}
```

#### Success Response (200 OK - no match)
- **verified** (boolean) - Indicates if the faces are verified to be from the same person (`false`).
- **percentage_match** (float) - The percentage match between the two faces (typically 0 if no match).

#### Response Example (no match)
```json
{
  "verified": false,
  "percentage_match": 0
}
```
```

--------------------------------

### POST /api/analyze

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Analyzes an image to detect potential manipulation or forgery.

```APIDOC
## POST /api/analyze

### Description
Analyzes an image to detect potential manipulation or forgery.

### Method
POST

### Endpoint
/api/analyze

### Parameters
#### Request Body
- **file** (multipart/form-data) - Required - Image file to analyze.

### Response
#### Success Response (200)
- **is_forged** (boolean) - Whether forgery was detected.
- **analysis** (object) - Detailed analysis results.

#### Response Example
{
    "is_forged": false,
    "analysis": {
        "status": "AUTHENTIC",
        "forgery_score": "0.13"
    }
}
```

--------------------------------

### Business Document Detection - Single Inference API (POST)

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Endpoint for detecting a business document class in a single uploaded image. It requires a file upload and optionally accepts an expected class name and confidence threshold. The response includes the filename, predicted class, confidence score, bounding box, and output path.

```http
POST /api/v1/business_doc_detection/inference/single HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data;

name="file"; filename="image.jpg"
Content-Type: image/jpeg

[... image data ...]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data;

name="expected_class"

business_vat_pan
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data;

name="confidence"

0.9
------WebKitFormBoundary7MA4YWxkTrZu0gW--

HTTP/1.1 200 OK
Content-Type: application/json

{
  "filename": "image.jpg",
  "predicted_class": "business_vat_pan",
  "expected_class": "business_vat_pan",
  "confidence": 0.95,
  "is_correct": true,
  "bbox": [100, 150, 400, 500],
  "output_path": "/app/media_files/results/image.jpg"
}
```

--------------------------------

### POST /batch_ingest

Source: https://third-factor.readthedocs.io/en/latest/_sources/endpoints.rst.txt

Ingests an image into the database for future 1:N reverse face searches.

```APIDOC
## POST /batch_ingest

### Description
Ingests an image into the database for future 1:N reverse face searches.

### Method
POST

### Endpoint
/batch_ingest

### Parameters
#### Request Body
- **image** (binary) - Required - The image file uploaded as raw binary content.

### Response
#### Success Response (200)
- **results** (Array) - List of ingested file results.

#### Response Example
{
    "results": [
        { "filename": "test.jpeg", "id": 35 }
    ]
}
```

--------------------------------

### Analyze Document (OCR) using Python

Source: https://third-factor.readthedocs.io/en/latest/endpoints.html

Performs OCR and structured information extraction from supported document types. It takes a base64 encoded image and returns extracted data such as ID number, name, and date of birth.

```python
import requests
import base64

def encode_image_to_base64(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

url = "/document-extract-information/"

image_path = 'path/to/your/document.jpg'
base64_image = encode_image_to_base64(image_path)

data = {
    'base64_image': base64_image
}

response = requests.post(url, data=data)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```
Tokens:
Raw