Onboarding with ID

SDK Installation

Before integrating, install the SDK in Getting Started → Install the SDK →

POST /api/kyc/onboard

When to use this flow

Account opening, user registration, card activation — any onboarding case where you need to verify the user against a physical document.

Flow

Environment validation

RASP checks before any capture.

Face capture

Face capture with liveness check.

Document capture

OCR on the government-issued ID and 1:1 face match against the document photo.

Encrypted payload

The SDK returns template + payload (face + document data).

Onboard request

Your backend forwards template + payload + DNI to /api/kyc/onboard.

SDK call

Kotlin

// Onboarding flow — also scans the ID document
SmartId
    .getInstance()
    .captureBiometric(getApplicationContext())
    .withDocument()
    .onSuccess { template, payload ->
        // template + payload include the face capture
        // AND the OCR data from the document
    }
    .onFailure { message, errorCode ->
        // capture failed — surface a retry to the user
    }
    .start()

Swift

SID.shared.startLocation()

SID.shared
    .captureBiometric()
    .withDocument()
    .onSuccess(success: { template, payload in
        // face + document captured
    })
    .onFailure(failure: { message, errorCode in
        // capture failed
    })
    .start()

Backend call

cURL

curl -X POST https://<api-url>/api/kyc/onboard \\
  -H "Content-Type: application/json" \\
  -H "X-Api-Key: <your-api-key>" \\
  -d '{
    "User": "[email protected]",
    "DNI": "23154613543134",
    "Template": "<template from SDK>",
    "PayLoad": "<payload from SDK>",
    "OverWrite": "true"
  }'

Request body

Field	Type	Required	Description
`User`	string	Required	Unique user identifier
`DNI`	string	Required	Government-issued ID number
`Template`	string	Required	Encrypted biometric template from the SDK
`PayLoad`	string	Required	Document data + metadata from the SDK
`OverWrite`	string	Optional	"true" to replace an existing enrollment for the user

Response codes

Code	Meaning
`200`	Onboarding successful
`403`	User or DNI cannot be null or empty
`407`	Template validation failed
`408`	User already enrolled
`412`	Template format invalid
`413`	Face↔document similarity below threshold
`420`	No valid data extracted from document
`421`	Failed to generate template from document image
`425/426`	Timestamp invalid / template expired
`500/701`	Internal error / service call error

Continue: Biometric Verification Step-up auth for login and operations → Biometric Enrollment Enrollment without document verification →