Integration Best Practices

1. Use secure communication

All VeraFi API interactions must take place over HTTPS to ensure encrypted data transmission. Use the application/json content type for standard API calls and multipart/form-data for file uploads such as documents, images, or videos. Never transmit sensitive data, tokens, or passwords through unsecured channels or plain query strings.

2. Handle authentication safely

Always use token-based authentication to access VeraFi resources. Obtain your access token through the /auth/login endpoint and include it in the request header as Authorization: Bearer <token>. Avoid placing tokens in URLs or query parameters, as these can appear in server logs and compromise security. Use the /auth/session endpoint to validate active tokens and monitor user or tenant subscription information.

3. Maintain session consistency

The VeraFi API uses a session-based flow for all verification operations. When uploading a document through /upload, the response includes a session_id. This identifier should be used consistently in all subsequent calls—such as /face, /verify_face, /verify_phrase, and /api/liveness—to maintain traceability and data integrity throughout the verification process.

4. Integrate document and face verification

Use the /upload endpoint to initiate verification workflows, followed by /face and /verify_face for facial matching and /api/liveness for live detection. Retrieve color-coded confidence indicators using /fetchconfidencecode to visually represent data accuracy and system confidence levels in your application’s UI.

5. Manage configuration effectively

System-wide verification rules can be retrieved or updated through the /verification-config endpoint. For tenant-specific overrides or bulk parameter changes, use /config-store. Keep environment-specific settings separated to maintain scalability and minimize misconfiguration risks across tenants.

6. Observe rate limiting and OTP policies

VeraFi enforces rate limits across several endpoints to ensure fair and stable usage. OTP operations—both phone and email—are rate-limited per user. Always adhere to these restrictions and use /resend-timer or /email-resend-timer to manage retry intervals gracefully within the UI.

7. Implement robust logging and auditing

Record verification events through /insert-logs and use /retrieve-logs or /retrieve-logs-count to access historical records. Logs provide the foundation for reporting, analytics, and compliance tracking. Use /user-verification-count to monitor verification frequency and trends per user or tenant.

8. Validate responses and handle errors

All API responses follow standardized HTTP codes with structured JSON payloads. Implement proper error handling for common responses such as 400 (Bad Request), 401 (Unauthorized), 422 (Validation Error), 429 (Rate Limit Exceeded), and 500 (Server Error). Ensure that client applications parse and respond gracefully to these conditions.

9. Monitor platform health

Use the /health endpoint to verify system uptime and API availability. This endpoint helps confirm connectivity between your application and VeraFi’s backend, ensuring that automated monitoring tools can detect and alert issues proactively.

10. Follow secure and scalable design

Adopt consistent naming conventions, modular API integration layers, and standardized error handling. Ensure that sensitive logs exclude personally identifiable information (PII) and that all stored data follows your organization’s data protection and compliance policies.