API Endpoint

QR Code Generation

Generate QR codes for verification links that can be emailed or printed for easy mobile access.

Use Case

The QR Code endpoint allows you to generate a scannable QR code image for a verification that has been created but not yet started. This is useful for:

Email Invitations

Embed QR codes in emails so recipients can scan and start verification on their phone

Mobile Handoff

Start verification on desktop, scan QR to continue on mobile with camera access

Printed Materials

Include QR codes in physical documents or kiosks for in-person verification

State Validation

QR codes can only be generated for verifications in the generated state. Once a user has started the verification, this endpoint will return an error to prevent QR code generation for in-progress or completed verifications.

Typical Workflow

Generate Verification

POST /api/generate-verification

Returns verification_id

Get QR Code

GET /api/get-verification-qrcode/{id}

Returns PNG image

Send to User

Email, display, or print

User scans to start

User Verifies

Scans QR → Mobile browser

Verification begins

Endpoint Reference

GET

/api/get-verification-qrcode/{verification_id}

X-SDK-Key Required

Generates a QR code image containing the verification URL. The QR code points to the verification portal where the user can begin their verification process.

Request Headers

X-SDK-Key: your-api-key-here

Path Parameters

verification_id: string (required) # The ID returned from generate-verification

Success Response

HTTP/1.1 200 OK Content-Type: image/png Content-Length: <size> (Binary PNG data)

The response is a PNG image (400x400 pixels) containing:

QR code encoding the verification URL
Error correction level: M (15%)
2px margin

State Requirement

The verification must be in generated state. If the verification has already been started, is in progress, completed, or expired, the endpoint returns a 409 Conflict error.

Error Responses

400

Bad Request

Missing verification_id in path

404

Not Found

Verification does not exist

409

Conflict

Verification is not in 'generated' state

{ "error": "Verification must be in 'generated' state...", "current_status": "in_progress" }

500

Server Error

No API key configured or internal error

Code Examples

curl - Download QR Code

# Download QR code as PNG file curl -H "X-SDK-Key: your-api-key-here" \ https://verify.stage.okid.io/api/get-verification-qrcode/ver_abc123 \ --output verification-qr.png

Node.js - Email with QR Code

// Server-side only! async function sendVerificationEmail(userEmail: string, verificationId: string) { // Fetch QR code image const qrResponse = await fetch( `https://verify.stage.okid.io/api/get-verification-qrcode/${verificationId}`, { headers: { 'X-SDK-Key': process.env.API_KEY } } ); if (!qrResponse.ok) { const error = await qrResponse.json(); throw new Error(`Failed to get QR code: ${error.error}`); } // Convert to base64 for email embedding const qrBuffer = await qrResponse.arrayBuffer(); const qrBase64 = Buffer.from(qrBuffer).toString('base64'); // Send email with embedded QR code (using your email provider) await sendEmail({ to: userEmail, subject: 'Complete Your Identity Verification', html: ` <h2>Identity Verification Required</h2> <p>Scan the QR code below with your phone to begin verification:</p> <img src="data:image/png;base64,${qrBase64}" alt="Verification QR Code" /> <p>Or click <a href="https://verify.stage.okid.io/verify?verification_id=${verificationId}">here</a> to verify on this device.</p> ` }); }

Python - Generate and Save QR Code

import requests import os def get_verification_qr_code(verification_id: str) -> bytes: """Fetch QR code image for a verification.""" response = requests.get( f"https://verify.stage.okid.io/api/get-verification-qrcode/{verification_id}", headers={"X-SDK-Key": os.environ["API_KEY"]} ) if response.status_code == 409: error = response.json() raise ValueError(f"Cannot generate QR: verification is {error['current_status']}") response.raise_for_status() return response.content # Example usage qr_image = get_verification_qr_code("ver_abc123") # Save to file with open("verification-qr.png", "wb") as f: f.write(qr_image) # Or use in email attachment, PDF generation, etc.

Complete Workflow - Generate + QR + Email

// Server-side complete workflow async function initiateVerificationWithQR(userEmail: string, userId: string) { const baseUrl = 'https://verify.stage.okid.io'; const apiKey = process.env.API_KEY; // Step 1: Generate verification const genResponse = await fetch(`${baseUrl}/api/generate-verification`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-SDK-Key': apiKey }, body: JSON.stringify({ extra_data: { user_id: userId, email: userEmail } }) }); const { verificationId } = await genResponse.json(); console.log(`Created verification: ${verificationId}`); // Step 2: Get QR code (verification is in 'generated' state) const qrResponse = await fetch( `${baseUrl}/api/get-verification-qrcode/${verificationId}`, { headers: { 'X-SDK-Key': apiKey } } ); if (!qrResponse.ok) { throw new Error('Failed to generate QR code'); } const qrBuffer = await qrResponse.arrayBuffer(); const qrBase64 = Buffer.from(qrBuffer).toString('base64'); // Step 3: Send email with QR code await sendEmail({ to: userEmail, subject: 'Complete Your Verification', html: ` <p>Scan this QR code with your phone camera:</p> <img src="data:image/png;base64,${qrBase64}" width="300" /> ` }); return verificationId; }

Best Practices

Do

Generate QR codes immediately after creating verification

Include a text link alongside QR for accessibility

Handle 409 errors gracefully - user may have already started

Cache QR codes if sending to multiple channels

Set appropriate email expiration messaging

Don't

Expose your API key in client-side code

Generate QR codes for verifications that may have expired

Retry on 409 errors - the verification is no longer in the correct state

Pre-generate QR codes long before they're needed