eKYC Backend API Documentation

A serverless backend API for eKYC document verification using OCR and database matching, powered by AWS Lambda and Python.

© 2025 Goodbye World team, for Great AI Hackathon Malaysia 2025 usage.

Base URL

https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify

Headers

{
  "Content-Type": "application/json"
}

Endpoints

1. Health Check API /health

Service health status endpoint.

Method: GET

Sample Response

{
  "status": {
    "statusCode": 200,
    "statusMessage": "Service is healthy"
  },
  "data": {
    "service": "ekyc-backend",
    "status": "healthy",
    "timestamp": "2025-10-08T10:30:45.123456+00:00",
    "version": "1.0.0",
    "environment": {
      "runtime": "AWS Lambda",
      "stage": "dev"
    }
  }
}

2. User ID Verification API /userId

Verify ID document authenticity and match against database records.

Method: POST

Request

Parameters

• url (string, required) - S3 downloadable URL of the ID document image

Sample

{
  "url": "https://s3.amazonaws.com/bucket/id-document.jpg"
}

Response

Parameters

• status.statusCode (number) - HTTP status code
• status.statusMessage (string) - Status message
• data.ocr (object) - OCR analysis results
• data.db (object) - Database lookup results
• data.pass (object) - Overall assessment result

Sample Success Response

{
  "status": {
    "statusCode": 200,
    "statusMessage": "OK"
  },
  "data": {
    "ocr": {
      "status": "success",
      "timestamp": "2025-10-08T10:30:45.123456+00:00",
      "is_blurry": false,
      "extracted_data": {
        "userId": "010203-04-0506",
        "full_name": "John Doe"
      }
    },
    "db": {
      "isRecordFound": true,
      "isRecordMatched": true,
      "message": "Record found and matched"
    },
    "pass": true
  }
}

Sample Error Response

{
  "status": {
    "statusCode": 400,
    "statusMessage": "Wrong document used. Only ID cards are accepted."
  },
  "data": {
    "error": "Detected category: passport, but expected: idcard"
  }
}

Database Messages

• "Record found and matched" - ID found and name matches
• "Record found but name mismatch" - ID found but name doesn't match
• "ID number not found in database" - No matching ID in database
• "No ID number extracted from document" - OCR failed to extract ID
• "No data extracted from document for database lookup" - OCR extraction failed
• "No record found" - Default message when no record exists

Error Codes

• 400 - Bad request (missing URL, wrong document type, OCR failure)
• 500 - Server error (OCR API failure, database error, internal error)

3. TNB Document Verification API /tnb

Verify TNB (Tenaga Nasional Berhad) document authenticity via OCR analysis only.

Method: POST

Request

Parameters

• url (string, required) - S3 downloadable URL of the TNB document image

Sample

{
  "url": "https://s3.amazonaws.com/bucket/tnb-document.jpg"
}

Response

Parameters

• status.statusCode (number) - HTTP status code
• status.statusMessage (string) - Status message
• data.ocr (object) - OCR analysis results
• data.pass (object) - Final verification result

Sample Success Response

{
  "status": {
    "statusCode": 200,
    "statusMessage": "OK"
  },
  "data": {
    "ocr": {
      "status": "success",
      "timestamp": "2025-10-09T13:05:01.001147+00:00",
      "is_blurry": false,
      "extracted_data": {
        "account_number": "123456789",
        "name": "John Doe"
      }
    },
    "pass": true
  }
}

Sample Error Response

{
  "status": {
    "statusCode": 400,
    "statusMessage": "Wrong document used. Only TNB documents are accepted."
  },
  "data": {
    "error": "Detected category: idcard, but expected: tnb"
  }
}

Assessment Messages

• "TNB document processed successfully" - Document validated successfully
• "TNB document validation failed" - Document failed validation (blurry or other issues)

Error Codes

• 400 - Bad request (missing URL, wrong document type, OCR failure)
• 500 - Server error (OCR API failure, internal error)

---

Environment Variables Required

# AWS CONFIGURATION
# final-sandbox
AWS_ACCESS_KEY_ID=<your-access-key-id>                                                                      # Your AWS access key ID (optional if using AWS CLI)
AWS_SECRET_ACCESS_KEY=<your-secret-access-key>                                                              # Your AWS secret access key (optional if using AWS CLI)
AWS_REGION1=us-east-1                                                                                       # Your preferred AWS region (used in scripts)

# Deployed APIs
OCR_ANALYZE_API_URL = https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/analyze

# Lambda API Endpoints (optional - for testing deployed APIs)
# final-sandbox
EKYYC_VERIFY_HEALTH_API_URL = https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify/health
EKYC_VERIFY_USERID_API_URL = https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify/userId
EKYC_VERIFY_TNB_API_URL = https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify/tnb

# MongoDB Atlas
ATLAS_URI=mongodb+srv://<username>:<password>@<cluster-name>.mongodb.net                                     # Your MongoDB connection string
ATLAS_DB_NAME=databases                                                                                      # Your MongoDB database name

Testing

# Health check
curl -X GET https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify/health

# User ID verification
curl -X POST https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify/userId \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-s3-url/id-document.jpg"}'

# TNB document verification
curl -X POST https://<your-api-id>.execute-api.us-east-1.amazonaws.com/dev/verify/tnb \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-s3-url/tnb-document.jpg"}'