10-minute quickstart

This guide gets you from zero to a working v1 verification flow. You will: get a tenant API key, start a verification, and check its status. No SDK required — only curl (or any HTTP client).

Prerequisites

A Loom API account (sign up at dashboard.loomapi.com)
curl and jq (optional, for parsing JSON) installed

Step 1: Get your tenant API key

Sign in at dashboard.loomapi.com
Go to API Keys (or Keys)
Click Create New Key, name it (e.g. "Quickstart"), then copy the key immediately

The key is shown only once. If you lose it, create a new key. See Key Management.

Set it in your environment:

export LOOM_TENANT_API_KEY="your_key_here"

Step 2: Start a verification

Call the v1 start endpoint with your tenant key in the x-tenant-api-key header:

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 '{}'

The request body is optional. You may pass userAgent and/or ip as strings; all other fields are rejected. You should get a 201 response:

{
  "verificationId": "cjld2cjxh0000qzrmn831i7rn",
  "status": "started",
  "provider": "idenfy",
  "sessionUrl": "https://ui.idenfy.com/?authToken=...",
  "config": {
    "pollingIntervalMs": 3000,
    "tokenType": "jwt"
  }
}

Save the verificationId; you need it for the next step. Send the user to sessionUrl to complete their identity check.

Step 3: Check verification status

Poll the status endpoint with the verificationId from the start response:

curl -s "https://api.loomapi.com/verify/status?verificationId=cjld2cjxh0000qzrmn831i7rn" \
  -H "x-tenant-api-key: $LOOM_TENANT_API_KEY"

Replace the example ID with your actual verificationId. Response example when approved:

{
  "verificationId": "cjld2cjxh0000qzrmn831i7rn",
  "status": "approved",
  "confidence": 0.95,
  "createdAt": "2024-01-15T14:30:00.000Z",
  "completedAt": "2024-01-15T14:31:00.000Z"
}

Possible status values: pending, started, approved, denied, resubmission, submitted, rejected.

In a real integration use webhooks instead of polling — you receive a verification.completed event when the session finishes.

Step 4 (optional): Validate a token

When the user completes the session, you may receive a token (e.g. in a redirect or callback). Validate it on your backend:

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"}'

This confirms the verification result server-side. A valid response looks like:

{ "valid": true, "over18": true, "reason": "OK" }

An invalid token returns:

{ "valid": false, "over18": false, "reason": "TOKEN_EXPIRED" }

Possible reason values: OK, TOKEN_EXPIRED, TOKEN_REVOKED, TOKEN_NOT_FOUND, UNDERAGE_OR_UNKNOWN.

See Verification for full request/response details.

Summary

Step	Endpoint	Purpose
1	—	Get tenant API key from dashboard (show-once)
2	`POST /verify/start`	Create session; get `verificationId` and URL
3	`GET /verify/status?verificationId=...`	Poll or check status
4	`POST /tokens/validate`	Validate token from session (optional)

All API requests use the x-tenant-api-key header. Base URL: https://api.loomapi.com.

Next steps

Authentication — tenant key vs console (Clerk)
Key Management — show-once, rotate, revoke
Verification — full reference for start, status, tokens
Billing & Usage — how usage is counted and quotas
Webhooks — receive verification events without polling
Examples — more curl and Node.js samples