API Documentation

Available Endpoints

• Create Verification Request - Initiate a new verification request
• Get Verification Details - Retrieve verification results by reference

---

Create Verification Request

POST/api/verification-request

This endpoint allows the user to initiate a verification request by uploading a file. The service type (face, document, or deepfake) is determined by the TYPE configuration in your .env file.

This endpoint accepts a base64-encoded file in data URI format and stores it in MongoDB GridFS. The request metadata is saved in the MongoDB collection.

Request Requirements

• HTTP Method: POST
• Content-Type: application/json
• Authentication: IP Whitelist Required

Parameters and Description

The request body must contain exactly 2 required fields:

Parameters	Description
file	Required: Yes Type: Array Format: Base64-encoded data URI Image Format: JPG, JPEG, PNG Maximum: 5MB Provide valid BASE64 encoded string in data URI format. Only image files are allowed. Example: "data:image/png;base64,..."
proof_method	Required: Yes Type: Array Accepted Values: uploaded, captured Method of proof submission indicating how the file was obtained by the user. Example: "uploaded"

Payload Examples

Scenario 1: User-Uploaded Image (PNG)

{
  "proof_method": "uploaded",
  "file": [
    "data:image/png;base64,..."
  ]
}

Scenario 2: User-Captured Image (JPEG)

{
  "proof_method": "captured",
  "file": [
    "data:image/jpeg;base64,..."
  ]
}

Response Codes

Code	Description
201	Created - Request successfully processed
400	Bad Request - Invalid input or validation error
403	Forbidden - IP address not whitelisted
500	Internal Server Error - Server error occurred

Success Response (201 Created)

{
  "success": true,
  "message": "Successfully created 1 verification request(s)",
  "references": [
    "4954931963AE34B1869c"
  ]
}

Error Response Examples

403 Forbidden - IP Not Whitelisted

{
  "detail": {
    "error": "Forbidden",
    "message": "Your IP address is not allowed to access this resource"
  }
}

400 Bad Request - File Too Large

{
  "detail": {
    "error": "ValidationError",
    "message": "Failed to process file at index 0: Failed to upload file: File size (7.43 MB) exceeds maximum allowed size (5 MB)",
    "details": {
      "type": "document",
      "file_index": 0
    }
  }
}

---

Get Verification Details

POST/api/get/verification-details

This endpoint retrieves decrypted verification files by reference.

Retrieves files associated with a verification request and returns them as base64-encoded data URIs.

Request Requirements

• HTTP Method: POST
• Content-Type: application/json
• Authentication: IP Whitelist Required

Parameters and Description

Parameters	Description
reference	Required: Yes Type: string Minimum: 6 characters Maximum: 250 characters Each request is issued a unique reference ID which is sent back to Shufti's client with each response. This reference ID helps to verify the request. The client can use this ID to check the status of already performed verifications. Example: "4954931963AE34B1869c"

Payload Example

{
  "reference": "4954931963AE34B1869c"
}

Request Validation Rules

• Reference must be non-empty
• Reference must be a valid verification request ID

Response Codes

Code	Description
200	OK - Request successfully retrieved
400	Bad Request - Invalid reference or not found
500	Internal Server Error - Server error occurred

Success Response (200 OK)

{
  "reference": "4954931963AE34B1869c",
  "type": "face",
  "proof_method": "captured",
  "status": "accepted",
  "request_info": {
    "ip_address": "0.0.0.0",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
    "browser": "Chrome",
    "browser_version": "0.0.0.0",
    "os": "",
    "os_version": "",
    "device": "Unknown",
    "device_type": "Desktop",
    "language": "en-US",
    "referer": "",
    "host": ""
  },
  "ml_response": {},
  "ml77": null,
  "created_at": "2025-11-12T13:35:32.187000",
  "angle": 0,
  "file": {
    "content_type": "image/jpeg",
    "size": 219089,
    "data": "data:image/jpeg;base64,..."
  },
  "crop_image": "data:image/jpeg;base64,..."
}

Error Response Examples

400 Bad Request - Reference Not Found

{
  "detail": {
    "error": "ValidationError",
    "message": "Verification request with reference ... not found"
  }
}

---

Need Help?

Contact our support team for assistance with AWS Marketplace API integration at [email protected]