API Documentation

Base URL

https://evandalize.com/api

Authentication

Pass your API key as a Bearer token in the Authorization header. Unauthenticated requests use the free tier rate limit.

Authorization: Bearer YOUR_API_KEY

Create Challenge

Start a new verification session. Returns a session ID and challenge image URL. Authentication is optional but recommended for tracking.

Request

POST /api/challenge
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "region": "DPRK",        // optional: DPRK, RU, CN
  "callbackUrl": "https://yoursite.com/webhook"  // optional
}

Response

{
  "sessionId": "evdl_sess_abc123",
  "imageUrl": "https://evandalize.com/api/challenge/abc123/image",
  "expiresAt": "2026-04-08T12:05:00Z",
  "region": "DPRK"
}

Submit Verification

Submit the defaced image data for verification. The system checks that sufficient defacement was applied to the face region.

Request

POST /api/verify
Content-Type: application/json

{
  "sessionId": "evdl_sess_abc123",
  "imageData": "data:image/png;base64,..."
}

Response

{
  "verified": true,
  "clearanceCode": "evdl_clr_xyz789",
  "expiresAt": "2026-04-08T12:10:00Z"
}

Check Status

Check whether a session has been verified. Use this server-side to confirm a user passed the challenge before processing their form submission.

Request

GET /api/verify?sessionId=evdl_sess_abc123

Response

{
  "sessionId": "evdl_sess_abc123",
  "status": "verified",
  "clearanceCode": "evdl_clr_xyz789",
  "verifiedAt": "2026-04-08T12:03:22Z"
}

Widget Session

Create a session scoped to the embeddable widget. Returns a widget token for client-side initialization.

Request

POST /api/widget/session
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "origin": "https://yoursite.com"
}

Response

{
  "widgetToken": "evdl_wt_def456",
  "sessionId": "evdl_sess_abc123",
  "expiresAt": "2026-04-08T12:05:00Z"
}

Embeddable Widget

Drop this into any HTML page. The widget handles the full challenge flow and fires a callback with the clearance code on success.

<div id="evandalize-widget"></div>
<script src="https://evandalize.com/widget.js"></script>
<script>
  Evandalize.init({
    container: "#evandalize-widget",
    apiKey: "YOUR_PUBLIC_KEY",
    onVerified: function(clearanceCode) {
      // Send clearanceCode to your server
      document.getElementById("clearance").value = clearanceCode;
    },
    onError: function(error) {
      console.error("EVANDALIZE error:", error);
    }
  });
</script>

Webhook Payload

If you provide a callbackUrl when creating a challenge, EVANDALIZE sends a POST request to that URL when verification completes.

POST https://yoursite.com/webhook
Content-Type: application/json
X-Evandalize-Signature: sha256=...

{
  "event": "verification.completed",
  "sessionId": "evdl_sess_abc123",
  "clearanceCode": "evdl_clr_xyz789",
  "region": "DPRK",
  "verifiedAt": "2026-04-08T12:03:22Z"
}

Rate Limits

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.