Verification flow (v1)

Verification in Loom API v1 is a multi-step flow: you start a verification session, the user completes the session (e.g. via a redirect or embedded flow), you poll status or receive a webhook, then you validate tokens to confirm the result in your backend.

Overview

1. POST /verify/start — Create a verification session; receive verificationId and sessionUrl or redirectUrl.
2. GET /verify/status — Poll verification status by verificationId.
3. POST /tokens/validate — Validate a token (e.g. from the session) to confirm verification result.

All endpoints require the tenant API key in the x-tenant-api-key header.

POST /verify/start

Start a new verification session. The response includes a verificationId and a URL to send the user to (sessionUrl or redirectUrl).

Request

POST https://api.loomapi.com/verify/start

Headers

Body (example)

Request body fields depend on the API spec; a typical example:

{
  "metadata": {
    "user_id": "user_123",
    "session_id": "session_456"
  },
  "callback_url": "https://your-app.com/verify/callback"
}

Response (200)

{
  "verificationId": "verif_abc123",
  "sessionUrl": "https://verify.loomapi.com/session/xyz",
  "redirectUrl": "https://verify.loomapi.com/session/xyz"
}

• verificationId: Use this to poll status or correlate webhooks.
• sessionUrl / redirectUrl: Send the user here to complete verification.

GET /verify/status

Check the status of a verification by ID.

Request

GET https://api.loomapi.com/verify/status?verificationId=verif_abc123

Headers

Query parameters

Response (200)

Example when verification is completed:

{
  "verificationId": "verif_abc123",
  "status": "completed",
  "result": {
    "verified": true,
    "verifiedAge": 25
  }
}

Status values depend on the API (e.g. pending, in_progress, completed, expired, failed). Use the exact values from the API spec.

POST /tokens/validate

Validate a token (e.g. issued at the end of the verification session) to confirm the user’s verification result in your backend.

Request

POST https://api.loomapi.com/tokens/validate

Headers

Body (example)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200)

{
  "valid": true,
  "verificationId": "verif_abc123",
  "verifiedAge": 25
}

If the token is invalid or expired, the API returns an error (e.g. 400 or 401) per the spec.

Example: minimal flow

# 1. Start verification
RESP=$(curl -s -X POST https://api.loomapi.com/verify/start \
  -H "x-tenant-api-key: $LOOM_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}')

VERIFICATION_ID=$(echo "$RESP" | jq -r '.verificationId')
SESSION_URL=$(echo "$RESP" | jq -r '.sessionUrl // .redirectUrl')

# 2. Send user to SESSION_URL; after they complete, poll status
curl -s "https://api.loomapi.com/verify/status?verificationId=$VERIFICATION_ID" \
  -H "x-tenant-api-key: $LOOM_TENANT_API_KEY"

# 3. When you have a token from the session, validate it
curl -s -X POST https://api.loomapi.com/tokens/validate \
  -H "x-tenant-api-key: $LOOM_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_TOKEN_FROM_SESSION"}'

Webhooks

You can receive events when verification status changes (e.g. completed or failed) instead of or in addition to polling. Configure a webhook URL in the dashboard and verify signatures. See Webhooks for payload format and verification.

Error responses

• 401: Invalid or missing x-tenant-api-key. See Authentication.
• 404: verificationId not found.
• 429: Rate limit exceeded. See Rate Limits.

Full error format and codes are in Errors.

Next steps

• Quickstart — run the full flow in under 10 minutes
• Billing & Usage — how verification usage is counted
• Webhooks — event payload and signature verification