API Reference

VeriGuard provides a RESTful API for KYC (Know Your Customer) identity verification and AML (Anti-Money Laundering) screening. All endpoints return JSON responses.

Overview

The VeriGuard API lets you submit identity verification requests, check their status, and list all verifications. Each verification runs through a multi-stage pipeline of document validation, biometric checks, and AML screening.

Base URL

text

https://ed1aa329fe01e59aef45a9ce17db9c9c.ctonew.app

Content Type

All requests and responses use application/json.

Authentication

🔑 API keys are not yet required.

Authentication via API key headers will be added in a future release. For now, all endpoints are open for testing.

Endpoints

Submit a Verification

POST/api/verify

Creates a new verification request. The customer's identity is checked against the full verification pipeline and results are returned immediately.

Request Body

Parameter	Type	Required	Description
customer_name	string	Yes	Full name of the customer being verified
email	string	Yes	Customer email address
document_type	enum	Yes	One of: "passport", "drivers_license", "national_id"
document_image_ref	string	Yes	Reference to the document image (simulated for MVP)

Example Request

bash

curl -X POST https://ed1aa329fe01e59aef45a9ce17db9c9c.ctonew.app/api/verify \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Jane Doe",
    "email": "jane@example.com",
    "document_type": "passport",
    "document_image_ref": "sim://passport-us-12345"
  }'

Example Response (201 Created)

json

{
  "id": "a1b2c3d4-...",
  "status": "approved",
  "overall_result": "pass",
  "customer_name": "Jane Doe",
  "checks": [
    {
      "name": "document_validation",
      "status": "passed",
      "details": "Document verified — authenticity markers and MRZ validation passed",
      "completed_at": "2026-07-16T04:07:31.065Z"
    },
    { "name": "biometric_check", "status": "passed", ... },
    { "name": "sanctions_screening", "status": "passed", ... },
    { "name": "pep_screening", "status": "passed", ... },
    { "name": "adverse_media", "status": "passed", ... },
    { "name": "watchlist_screening", "status": "passed", ... }
  ],
  "created_at": "2026-07-16T04:07:31.065Z",
  "completed_at": "2026-07-16T04:07:31.065Z"
}

Error Responses

400 Bad Request — Missing or invalid fields.

json

{ "error": "customer_name is required and must be a string" }

500 Internal Server Error — Unexpected error.

json

{ "error": "Internal server error" }

Get Verification Status

GET/api/verify/:id

Retrieves the status and full check results for a single verification by its UUID.

Path Parameters

Parameter	Type	Required	Description
id	UUID	Yes	The verification ID returned from POST /api/verify

Example Request

bash

curl https://ed1aa329fe01e59aef45a9ce17db9c9c.ctonew.app/api/verify/a1b2c3d4-...

Example Response (200 OK)

json

{
  "id": "a1b2c3d4-...",
  "status": "approved",
  "overall_result": "pass",
  "customer_name": "Jane Doe",
  "checks": [ ... ],
  "created_at": "2026-07-16T04:07:31.065Z",
  "completed_at": "2026-07-16T04:07:31.065Z"
}

Error Responses

404 Not Found — No verification with that ID.

json

{ "error": "Verification not found" }

List Verifications

GET/api/verifications

Lists recent verifications with optional status filtering and pagination. Returns summary data per verification (use the detail endpoint for full check results).

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
page_size	integer	No	Items per page (default: 20, max: 100)
status	enum	No	Filter by status: "approved", "rejected", "pending", "in_progress"

Example Request

bash

curl "https://ed1aa329fe01e59aef45a9ce17db9c9c.ctonew.app/api/verifications?page=1&page_size=10&status=approved"

Example Response (200 OK)

json

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "customer_name": "Jane Doe",
      "status": "approved",
      "overall_result": "pass",
      "check_count": 6,
      "flagged_checks": 0,
      "created_at": "2026-07-16T04:07:31.065Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10,
  "total_pages": 1
}

The check_count field shows the total number of pipeline checks, and flagged_checks shows how many had non-passing results (flagged or failed).

Verification Pipeline

Each verification runs through a 6-stage pipeline in order. Every stage produces a result of passed, flagged, or failed.

1. Document Validation

Checks the authenticity of the submitted identity document (passport, driver's license, or national ID). Verifies MRZ data, security features, and format integrity.

✅ Pass: Clean documents with valid formatting

⚠️ Flag: Suspicious or tampered documents

❌ Fail: Clear forgery detected

2. Biometric Liveness Check

Confirms the applicant is a live person (not a photo, video, or deepfake) using facial motion analysis and depth mapping.

✅ Pass: Live person detected

⚠️ Flag: Inconclusive liveness signal

❌ Fail: Presentation attack detected (photo/video/replay)

3. Sanctions Screening

Screens the customer name against global sanctions lists including OFAC (US), UN, EU, and UK sanctions databases.

✅ Pass: No match on any sanctions list

⚠️ Flag: Name partially matches a sanctioned entity

❌ Fail: Confirmed sanctions match

4. PEP Screening

Checks if the individual is a Politically Exposed Person — someone with a prominent public position who may pose higher corruption risk.

✅ Pass: No PEP match

⚠️ Flag: Possible PEP match detected

❌ Fail: Confirmed PEP match

5. Adverse Media Screening

Searches global news and media sources for negative mentions related to financial crime, fraud, regulatory actions, or reputational risk.

✅ Pass: No adverse media found

⚠️ Flag: Negative media mention detected

❌ Fail: Confirmed adverse media match

6. Watchlist Screening

Cross-references the customer against international law enforcement watchlists, including INTERPOL notices and regulatory warning lists.

✅ Pass: No watchlist match

⚠️ Flag: Name similar to a watchlist entry

❌ Fail: Confirmed watchlist match

How results are aggregated

• All checks passed → status: "approved", overall_result: "pass"
• Some checks flagged (none failed) → status: "approved" (flags indicate manual review is recommended but not required)
• Any check failed → status: "rejected", overall_result: "fail"

Test Names

During development and testing, use these known names to trigger specific verification outcomes. Clean names (like "John Smith" or "Jane Doe") pass all checks.

Name	Check Affected	Result	Description
"John Smith"	All	Passed	Clean name — all checks pass
"Jane Doe"	All	Passed	Clean name — all checks pass
"Osama Bin Laden"	Sanctions	Flagged	OFAC SDN sanctions match
"Vladimir Putin"	PEP	Flagged	Global PEP database hit
"Bernie Madoff"	Adverse Media	Flagged	Financial fraud adverse media
"Edward Snowden"	Watchlist	Flagged	International watchlist match
"Fake Identity"	Document	Failed	Document forgery detected
"Deep Fake"	Biometric	Failed	Liveness/presentation attack
"High Risk"	Adverse Media	Flagged	Regulatory negative press
"Flagged"	Sanctions	Flagged	Sanctions algorithm flag

Rate Limits & Errors

🚧 Rate limiting is not yet implemented.

We will add rate limiting (X-RateLimit-* headers) and standard error codes in a future release. For now, please be considerate with your request volume.

HTTP Status Code Summary

Code	Description
200	OK — successful GET request
201	Created — verification submitted successfully
400	Bad Request — invalid or missing parameters
404	Not Found — verification ID not found
500	Internal Server Error — something went wrong

← Back to Home Go to Dashboard →