Best Practices

General guidelines for integrating with the platform effectively.

API Integration

Use the Sandbox First

Always develop and test your integration in the sandbox environment before going live. The sandbox behaves identically to production but keeps test data isolated.

Handle Errors Gracefully

• Expect and handle all HTTP response codes (2xx success, 4xx client errors, 5xx server errors)
• Implement exponential backoff for retries
• Log validation errors to understand what needs to be corrected
• Display user-friendly messages based on error responses

Use Idempotency

Verification lifecycle endpoints (approve, reject, cancel) are designed to be safe to retry. If you receive a timeout or network error, it is generally safe to retry the request.

Monitor Webhooks

• Set up webhook endpoints early and test them in the sandbox
• Verify webhook signatures to ensure authenticity
• Implement idempotent webhook handlers (you may receive the same event more than once)
• Monitor webhook delivery logs and address failures promptly

Verification Workflow

Set Meaningful Vendor References

Use the vendor_reference field to correlate verifications with your internal records. This makes it easier to:

• Look up verifications by your own identifiers
• Cross-reference in reports and analytics
• Debug integration issues

Handle the Full Lifecycle

A complete verification integration should handle:

1. Creation — Create verification with expected data
2. Redirection — Send the user to the widget or handle document upload via API
3. Monitoring — Listen for webhook events or poll for status changes
4. Resolution — Act on the final decision (approved, rejected, double-check)

Plan for Manual Review

Not all verifications will pass automated processing. Plan for:

• Double Check — Flagged for review; may still be approved by a human
• Rejected — User needs to resubmit with corrected documents
• Hold — Verification is paused; may require customer support interaction

Security

Protect API Tokens

• Store API tokens securely (environment variables, secret manager)
• Never expose tokens in client-side code (browser, mobile app)
• Rotate tokens periodically
• Delete unused tokens

Verify Webhook Signatures

Always verify the HMAC-SHA256 signature on incoming webhook requests to confirm they originated from Colleckt.

Use HTTPS

All API requests must be made over HTTPS. HTTP requests will be rejected.

User Experience

Make Instructions Clear

Before redirecting users to the verification widget:

• Tell them what documents they need (photo ID, proof of address)
• Explain the process steps
• Set expectations about how long it will take
• Provide contact information for support

Handle Rejections Gracefully

When a verification is rejected:

• Notify the user with a clear explanation of what went wrong
• Explain what they need to do differently
• Provide a link or button to restart the process

Test on Multiple Devices

The verification widget works on desktop and mobile browsers. Test your integration across:

• Desktop Chrome, Firefox, Safari
• Mobile Safari (iOS)
• Mobile Chrome (Android)
• Different screen sizes and orientations

Operations

Monitor Your Dashboard

Check the dashboard regularly for:

• Unfinished verifications that may indicate user drop-off
• Retried verifications that may indicate document quality issues

Review Activity Logs

Use activity logs to:

• Audit changes to verification data
• Track user actions
• Investigate issues
• Support compliance requirements