From Zero to First Verification
in 10 Minutes

What We're Building

FaceVault is an identity verification API. You send us an ID document and a selfie, and we tell you whether the face on the document matches the person in the selfie — in under 30 seconds.

Here's the full flow we'll walk through:

The free tier includes 100 verifications per month. No credit card required.

Step 1: Create Your Account

Head to the FaceVault Dashboard and create an account. You'll need an email address and a password (minimum 8 characters).

Or register via the API:

curl -X POST https://api.facevault.id/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

You'll receive a verification email. Click the link in the email — your API keys won't work until your email is verified. If using the dashboard, you'll see a banner reminding you to check your inbox.

Step 2: Generate an API Key

Once your email is verified, open the dashboard and click Create API Key. Give it a name (e.g. "Development") and hit create.

You'll see your full API key exactly once. It looks like this:

fv_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0...

Copy it somewhere safe. We hash the key server-side — there's no way to retrieve it later. If you lose it, just create a new one and deactivate the old one.

Step 3: Create a Verification Session

A session represents one verification attempt. Create one for each user you want to verify:

curl -X POST https://api.facevault.id/api/v1/sessions \
  -H "X-API-Key: fv_live_YOUR_KEY_HERE"

{
  "session_id": "a1b2c3d4e5f6...",
  "steps": ["id", "straight"]
}

The response tells you the session_id and the required steps: id (upload an ID document) and straight (upload a selfie).

Here's the same call in Python and Node.js:

import requests

API_KEY = "fv_live_YOUR_KEY_HERE"
BASE = "https://api.facevault.id/api/v1"

# Create session
resp = requests.post(f"{BASE}/sessions",
    headers={"X-API-Key": API_KEY})
session = resp.json()
session_id = session["session_id"]
print(f"Session: {session_id}")

const API_KEY = "fv_live_YOUR_KEY_HERE";
const BASE = "https://api.facevault.id/api/v1";

// Create session
const resp = await fetch(`${BASE}/sessions`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY },
});
const session = await resp.json();
console.log("Session:", session.session_id);

Step 4: Upload Photos

Upload two photos to the session: the ID document and a selfie. Both must be JPEG images under 5MB.

Upload the ID document

curl -X POST "https://api.facevault.id/api/v1/sessions/$SESSION_ID/upload" \
  -H "X-API-Key: fv_live_YOUR_KEY_HERE" \
  -F "step=id" \
  -F "file=@/path/to/id-document.jpg"

{ "valid": true, "error": "" }

The API validates the image immediately: checks brightness, readability, and runs face detection. If the photo is too dark, blurry, or doesn't contain a detectable face, you'll get "valid": false with a specific error message.

Upload the selfie

curl -X POST "https://api.facevault.id/api/v1/sessions/$SESSION_ID/upload" \
  -H "X-API-Key: fv_live_YOUR_KEY_HERE" \
  -F "step=straight" \
  -F "file=@/path/to/selfie.jpg"

# Upload ID document
requests.post(f"{BASE}/sessions/{session_id}/upload",
    headers={"X-API-Key": API_KEY},
    files={"file": open("id-document.jpg", "rb")},
    data={"step": "id"})

# Upload selfie
requests.post(f"{BASE}/sessions/{session_id}/upload",
    headers={"X-API-Key": API_KEY},
    files={"file": open("selfie.jpg", "rb")},
    data={"step": "straight"})

Step 5: Run the Verification

Once both photos are uploaded, trigger the verification. This is a blocking call that runs the full AI pipeline: face detection, ArcFace embedding comparison, and liveness checks. It typically takes 10–30 seconds.

curl -X POST "https://api.facevault.id/api/v1/sessions/$SESSION_ID/complete" \
  -H "X-API-Key: fv_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmed_data": {
      "full_name": "John Smith",
      "date_of_birth": "15/03/1990",
      "nationality": "British"
    }
  }'

The confirmed_data field is optional but recommended. It lets you pass in the details your user provided (e.g. from a form) so FaceVault can cross-reference them against the data extracted from the document.

{
  "passed": true,
  "error": "",
  "document_check": {
    "name_match": true,
    "dob_match": true,
    "nationality_match": true
  }
}

{
  "passed": false,
  "error": "Face match failed.",
  "document_check": null
}

That's it. Three API calls: create → upload → complete. You now have a verified identity.

Step 6: Check the Results

You can fetch the full session details at any time:

curl "https://api.facevault.id/api/v1/sessions/$SESSION_ID" \
  -H "X-API-Key: fv_live_YOUR_KEY_HERE"

{
  "session_id": "a1b2c3d4e5f6...",
  "status": "passed",
  "steps": {
    "id": "completed",
    "straight": "completed"
  },
  "face_match_passed": true,
  "error": "",
  "created_at": "2026-02-15T14:30:00Z",
  "completed_at": "2026-02-15T14:30:22Z"
}

The status field will be one of:

The Easier Way: Verification Links

Don't want to build upload UI? FaceVault can generate a shareable verification link that handles the entire flow — ID capture, selfie with built-in liveness — in a hosted web app. Just send the link to your user.

curl -X POST https://api.facevault.id/api/v1/links \
  -H "X-API-Key: fv_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user-123",
    "expires_in_hours": 24
  }'

{
  "id": 42,
  "token": "a1b2c3d4...",
  "url": "https://app.facevault.id/v/a1b2c3d4...",
  "external_ref": "user-123",
  "status": "pending",
  "expires_at": "2026-02-16T14:30:00Z"
}

Send the url to your user via email, SMS, or in-app. When they open it, they'll see the FaceVault verification flow: upload ID, take a selfie with built-in liveness detection. No code on your side.

You can poll the session status afterwards, or set up a webhook to get notified instantly when the verification completes. The external_ref field ties the result back to the user in your system.

What's Next