Widget Integration

The Colleckt widget is an embeddable end-user verification flow that guides users through capturing and uploading their identity documents. The widget is a browser-based SPA (Single Page Application) that can be integrated into your website or application.

Overview

The widget handles:

1. Instructions — Shows the user what documents are needed
2. Document capture — Front and back side photo capture (via camera or file upload)
3. Data confirmation — User confirms extracted information
4. Submission — Sends all data for processing

How It Works

Loading diagram...

Integration Steps

1. Create a Verification

Use the API to create a verification with the expected person and document details:

POST /api/v1/usps1583/verifications
Authorization: Bearer {token}
Content-Type: application/json

{
  "vendor_reference": "CUST-001",
  "person": {
    "first_name": "Homer",
    "last_name": "Simpson",
    "date_of_birth": ""
  },
  "address": {
    "street": "742 Evergreen Terrace",
    "city": "Springfield",
    "state": "Tennessee",
    "postal_code": "92026",
    "country": "USA"
  },
  "documents": {
    "photo_id": {
      "type": "Passport",
      "number": "AB123456",
      "country": "USA"
    },
    "proof_of_address": {
      "type": "Driver License",
      "number": "",
      "country": "USA"
    }
  }
}

The response includes:

{
  "data": {
    "id": "ver_xxxxx",
    "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
    "qr_code": "https://{workspace}.colleckt.io/qr/...",
    ...
  }
}

2. Direct the User to the Widget

Redirect the user to the url returned in the response. The widget will:

1. Display instructions based on the required document types
2. Guide the user through document capture
3. Let the user confirm and submit

3. Scan a QR Code (Mobile)

The qr_code URL in the response redirects to the same widget flow. Print this on a QR code for in-person verification scenarios where the user scans the code with their mobile device.

4. Monitor for Completion

Listen for webhook events to know when the verification is finished:

• verification.finished — Verification reached a final decision
• verification.canceled — Verification was canceled

Widget Data Flow

Browser Support

The widget supports:

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Mobile browsers (iOS Safari, Android Chrome)
• Camera capture on mobile and desktop devices
• File upload as an alternative to camera capture

Security Considerations

• The widget runs over HTTPS
• PII data is encrypted
• Document images are stored in encrypted S3 buckets

Best Practices

• Provide clear instructions to users before redirecting to the widget
• Handle the return flow by listening for webhook events rather than polling
• Test on mobile devices to ensure the camera capture works correctly