Requirements
| Requirement | Minimum Version |
|---|
| Android | minSdk 24 (Android 7.0+) |
| Kotlin | 1.9+ |
| Kotlin Coroutines | 1.7+ |
| AGP | 8.0+ |
Installation
Add the Verilock SDK to your module-level build.gradle.kts:
dependencies {
implementation("io.verilock:verilock-sdk:1.0.0")
}
dependencyResolutionManagement {
repositories {
mavenCentral()
}
}
Configuration
Create a Verilock client with your API key. All API calls are made through this instance.
import io.verilock.sdk.Verilock
val verilock = Verilock(apiKey = "qi_live_...")
val verilock = Verilock(
apiKey = "qi_live_...",
baseUrl = "https://verilock.io/api/v1", // default
timeout = 30_000, // milliseconds, default
maxRetries = 2, // retries on 429/5xx, default
)
Keep your API key secure. Never embed production keys in client-side code or commit them to version control. All API calls should originate from your backend or a secure context.
Quick Start
Create a KYC session, upload a document and selfie, then submit for verification. All methods are suspend functions.
import io.verilock.sdk.*
val verilock = Verilock(apiKey = "qi_live_...")
// 1. Create a session
val session = verilock.sessions.create(
CreateSessionParams(
applicant_email = "john@example.com",
redirect_url = "https://example.com/callback",
)
)
println(session.sessionUrl) // Redirect user here, or upload docs directly
// 2. Upload document (front)
verilock.sessions.uploadDocument(
UploadDocumentParams(
sessionId = session.id,
fileData = frontImageBytes,
side = DocumentSide.FRONT,
documentType = DocumentType.PASSPORT,
)
)
// 3. Upload selfie
verilock.sessions.uploadSelfie(
UploadSelfieParams(
sessionId = session.id,
fileData = selfieBytes,
)
)
// 4. Submit for verification
val result = verilock.sessions.submit(session.id)
Coroutine Integration
All SDK methods are suspend functions. Call them from a coroutine scope such as viewModelScope or lifecycleScope.
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.launch
import io.verilock.sdk.*
class VerificationViewModel : ViewModel() {
private val verilock = Verilock(apiKey = "qi_live_...")
fun startVerification(email: String) {
viewModelScope.launch {
try {
val session = verilock.sessions.create(
CreateSessionParams(
applicant_email = email,
redirect_url = "https://example.com/callback",
)
)
// Navigate to session URL or upload docs
} catch (e: VerilockException) {
// Handle error
}
}
}
}
KYC Sessions
The sessions resource manages the full verification lifecycle.
// Create a session
val session = verilock.sessions.create(
CreateSessionParams(
applicant_email = "jane@example.com",
redirect_url = "https://example.com/done",
)
)
// List sessions with pagination
val list = verilock.sessions.list(
ListSessionsParams(page = 1, limit = 20)
)
// Retrieve a session by ID
val details = verilock.sessions.retrieve("sess_abc123")
println(details.decision) // "approved", "declined", or "review"
// Upload address proof
verilock.sessions.uploadAddressProof(
UploadAddressProofParams(
sessionId = "sess_abc123",
fileData = proofBytes,
documentType = AddressDocumentType.UTILITY_BILL,
)
)
AML Screening
Screen individuals against global sanctions, PEP, and watchlists.
val screening = verilock.aml.screen(
ScreenPersonParams(name = "John Doe")
)
println(screening.risk) // risk classification
println(screening.matches) // matched watchlist entries
Transaction Monitoring
Screen transactions for suspicious activity.
val tx = verilock.transactions.screen(
ScreenTransactionParams(
transaction_ref = "TX-001",
sender_name = "Alice",
receiver_name = "Bob",
amount = 5000.0,
currency = "USD",
)
)
println(tx.risk)
println(tx.flags)
Premium Features
The SDK provides access to premium verification services through dedicated resource properties.
// Biometric face authentication
val biometricResult = verilock.biometric.verify(params)
// Government database validation
val dbResult = verilock.database.validate(params)
// 1:N face duplicate detection
val searchResult = verilock.faceSearch.search(params)
// Crypto wallet compliance screening
val walletResult = verilock.wallet.screen(params)
// Reusable KYC credentials
val credential = verilock.credentials.create(params)
// Age verification from selfie
val ageResult = verilock.ageVerify.check(params)
Premium features require an active subscription. See the Premium Features docs for details. Error Handling
All methods are suspend functions that throw VerilockException subclasses. Use try/catch to handle errors.
try {
val session = verilock.sessions.retrieve("sess_invalid")
} catch (e: AuthenticationException) {
println("Auth failed: ${e.message}")
} catch (e: InsufficientBalanceException) {
println("Need ${e.required}, have ${e.balance}: ${e.message}")
} catch (e: NotFoundException) {
println("Not found: ${e.message}")
} catch (e: ValidationException) {
println("Invalid input: ${e.message}")
e.errors.forEach { (field, messages) ->
println(" $field: ${messages.joinToString()}")
}
} catch (e: RateLimitException) {
println("Slow down: ${e.message}, retry in ${e.retryAfter}s")
} catch (e: VerilockException) {
// Catch-all for other Verilock errors
println("Error ${e.statusCode}: ${e.message} (${e.code})")
}
Exception Hierarchy
| Exception | HTTP Status | Description |
|---|
AuthenticationException | 401 | Invalid or missing API key |
InsufficientBalanceException | 402 | Account balance too low |
NotFoundException | 404 | Resource does not exist |
ValidationException | 422 | Request parameters failed validation |
RateLimitException | 429 | Too many requests |
VerilockException | * | Base class for all SDK errors |
VerilockException, which provides code, statusCode, and body properties.
The SDK automatically retries requests on 429 and 5xx errors up to maxRetries times (default: 2) with exponential backoff. You only need to handle errors that persist after retries.
