Idova
← All docs

Quickstart

Quickstart

Run your first verification end-to-end in under five minutes.

1. Get an API key

Create one at Developers → API keys → Create key. You'll see the secret once — copy it immediately.

Keys follow the format:

idv_test_<ulid>.<secret>   (sandbox)
idv_live_<ulid>.<secret>   (production)

2. Create a verification

curl -X POST https://api.idova.id/v1/kyc-requests \
  -H "Authorization: Bearer idv_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-1234" \
  -d '{
    "applicant": {
      "firstName": "Jane",
      "lastName":  "Smith",
      "email":     "jane@example.com",
      "dob":       "1990-06-15",
      "country":   "CA"
    },
    "environment": "sandbox",
    "callbackUrl": "https://yourapp.example.com/kyc-callback",
    "redirectUrl": "https://yourapp.example.com/verification-complete"
  }'

You get back:

{
  "id":              "kyc_01KP4FAA2YZ9Q4HCWRJK2FV7HG",
  "publicId":        "kyc_A5X7Q2P4NJ",
  "applicantId":     "app_01KP47W4G6RBS3B5M8CHKE0EAM",
  "applicantPublicId": "app_B8K2R9T4NM",
  "status":          "link_generated",
  "decision":        "pending",
  "environment":     "sandbox",
  "portalUrl":       "https://idova.id/portal/abc123def456ghi789",
  "portalExpiresAt": "2026-04-17T12:00:00Z",
  "createdAt":       "2026-04-15T12:00:00Z"
}

3. Redirect your user to the portal

Open portalUrl in a browser. The applicant captures their document and selfie. Idova runs screenings + the decision engine, then emits a webhook.

4. Receive the webhook

POST /your-webhook-url HTTP/1.1
Content-Type:        application/json
X-Idova-Event:       idova.kyc.request.approved
X-Idova-Signature:   v1,t=1729000000,sig=a1b2c3...

Body:

{
  "eventId":    "kev_01KP4FAB3XYZ9Q4HCWRJK2FV7HG",
  "eventType":  "idova.kyc.request.approved",
  "resourceId": "kyc_01KP4FAA2YZ9Q4HCWRJK2FV7HG",
  "publicId":   "kyc_A5X7Q2P4NJ",
  "status":     "approved",
  "decision":   "approved",
  "riskScore":  0.10,
  "createdAt":  "2026-04-15T12:05:00Z"
}

Verify the signature (see Webhooks) before trusting the payload.

5. Fetch the result

curl https://api.idova.id/v1/kyc-requests/kyc_A5X7Q2P4NJ \
  -H "Authorization: Bearer idv_test_YOUR_KEY"

6. Download the compliance report

# PDF
curl -o report.pdf \
  -H "Authorization: Bearer idv_test_YOUR_KEY" \
  https://api.idova.id/v1/kyc-requests/kyc_A5X7Q2P4NJ/report.pdf

# Structured JSON
curl -H "Authorization: Bearer idv_test_YOUR_KEY" \
  https://api.idova.id/v1/kyc-requests/kyc_A5X7Q2P4NJ/report.json

That's it. Keep using sandbox keys for testing — all data is isolated. Switch to idv_live_* + "environment": "live" when you're ready to go live.

Next steps