quickstart

Quickstart — VEREID Identity

Create a hosted verification session, redirect the end user, and receive a signed result via webhook.

Last updated 2026-05-20

VEREID Identity is a hosted verification API competing with Persona, Veriff, and Onfido. The flow is identical to those services: you create a session server-side, redirect the end user to a hosted URL, and receive a webhook when the result is in. The difference is the honesty of our tier labels — see Verification tiers.

1. Create a session

A session bundles the tiers you want checked. T1 is included in every session; everything above is opt-in and additively priced.

curl -sS -X POST https://api.vereid.com/v1/verify/sessions \
  -H "Authorization: Bearer $VEREID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tiers": ["T1", "T2"],
    "reference": "user_42",
    "redirect_url": "https://yourapp.com/verify/complete"
  }'

import { Vereid } from "@vereid/js";
 
const vereid = new Vereid({ apiKey: process.env.VEREID_API_KEY });
const session = await vereid.verify.sessions.create({
  tiers: ["T1", "T2"],
  reference: "user_42",
  redirect_url: "https://yourapp.com/verify/complete",
});
res.redirect(session.hosted_url);

from vereid import Vereid
client = Vereid(api_key=os.environ["VEREID_API_KEY"])
session = client.verify.sessions.create(
    tiers=["T1", "T2"],
    reference="user_42",
    redirect_url="https://yourapp.com/verify/complete",
)

session, err := client.Verify.Sessions.Create(ctx, &vereid.CreateSessionInput{
    Tiers:       []string{"T1", "T2"},
    Reference:   "user_42",
    RedirectURL: "https://yourapp.com/verify/complete",
})

Response:

{
  "id": "vs_01HZ3K8R4D9NPCRVF7G6Y0WMBQ",
  "status": "pending",
  "hosted_url": "https://id.vereid.com/s/01HZ3K8R...",
  "tiers": ["T1", "T2"],
  "expires_at": "2026-05-20T16:00:00Z",
  "reference": "user_42"
}

2. Redirect the user

hosted_url is mobile-optimised, brandable per tenant, and supports both same-tab redirect and <iframe> embed. Pass it directly to res.redirect() or open it in a popup.

window.location.href = session.hosted_url;

The hosted flow runs the user through document upload, selfie capture, and (if T2 was requested) a randomised liveness challenge. T5 — passport chip — additionally requires the mobile SDK, since web browsers do not have NFC.

3. Receive the webhook

Register a webhook endpoint that subscribes to verification.completed. Each request carries a vereid-signature header:

vereid-signature: v1,t=1716220800,sig=8a7d…f0c2

Verify the signature before parsing the body. The full HMAC scheme is documented in Verifying webhook signatures.

app.post("/webhooks/vereid", express.raw({ type: "*/*" }), (req, res) => {
  if (!verify(req.body, req.header("vereid-signature"), SECRET)) {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body);
  if (event.type === "verification.completed") {
    db.users.update(event.data.reference, {
      verification_tier: event.data.tier,
      verification_badges: event.data.badges,
    });
  }
  res.status(204).end();
});

@app.post("/webhooks/vereid")
async def webhook(request: Request):
    raw = await request.body()
    if not verify(raw, request.headers.get("vereid-signature"), SECRET):
        raise HTTPException(400)
    event = json.loads(raw)
    ...

4. Poll as a fallback

Webhooks should always be your primary path, but if you want a fallback for development you can poll the session by id:

curl -sS https://api.vereid.com/v1/verify/sessions/$ID \
  -H "Authorization: Bearer $VEREID_API_KEY"

Test-mode sessions resolve deterministically after 10 seconds, so you can drive an end-to-end flow without ever capturing a real document.

5. Read the result

{
  "id": "vs_01HZ3K8R...",
  "status": "completed",
  "decision": "approved",
  "tier": "T2",
  "badges": ["photo", "liveness"],
  "confidence": 0.94,
  "signals": [
    { "source": "rekognition_compare_faces", "score": 0.97 },
    { "source": "liveness_challenge", "score": 0.92 }
  ],
  "completed_at": "2026-05-20T15:42:11Z"
}