Results

API results

This section lists the success results and errors returned by each top-level SDK API method. Per-module step results (delivered through callbacks such as onSelfieScanCompleted) are listed separately under Module result objects.

Error enums

Errors are delivered as a String to the onError callback. The String can be converted to one of the following enums:

• IncodeSdkInitError (via error.toIncodeSdkInitError()) — returned by init:
  • simulatorDetected
  • testModeEnabled
  • jailbreakDetected
  • unknown
• IncodeSdkFlowError (via error.toIncodeSdkFlowError()) — returned by flow APIs such as startOnboarding:
  • permissionsDenied
  • badEnvDetected (deprecated, no longer reported. The native SDK terminates the process when a compromised device environment is detected, so this case is never delivered.)
  • jailbreakDetected
  • faceAuthenticationFailed
  • unknown

init

• Success: onSuccess is called with no result object. Safe to start onboarding.
• Error: onError(String error). Convert with error.toIncodeSdkInitError() to an IncodeSdkInitError.

startOnboarding

• Success: onSuccess is called with no result object once all steps are completed.
• Error: onError(String error). Convert with error.toIncodeSdkFlowError() to an IncodeSdkFlowError.
• Canceled: onUserCancelled is called if the user cancels the flow.
• Per-step results are delivered through the optional module callbacks (see Module result objects).

setupOnboardingSession

• Success: onSuccess(OnboardingSessionResult result) is called once the onboarding session is created.
• Error: onError(String error).

startNewOnboardingSection

• Section completed: onOnboardingSectionCompleted(String flowTag) is called with the flowTag identifier of the completed section.
• Error: onError(String error).
• Per-step results are delivered through the optional module callbacks (see Module result objects).

finishFlow

• Returns no result and reports no errors.

startFlow

• Success: onSuccess is called with no result object once the flow completes.
• Error: onError(String error).
• Canceled: onUserCancelled is called if the user cancels the flow.

startFlowFromDeepLink

• Success: onSuccess is called with no result object once the flow completes.
• Error: onError(String error).
• Canceled: onUserCancelled is called if the user cancels the flow.

faceMatch

• Success: onSuccess is called with no result object.
• Result: onFaceMatchCompleted(FaceMatchResult result) delivers the match result (see FaceMatch under Module result objects).
• Error: onError(String error).
• Canceled: onUserCancelled is called if the user cancels.

startFaceLogin

• Success: onSuccess(FaceLoginResult result).
• Error: onError(String error).

FaceLoginResult contains:

• image: selfie image
• spoofAttempt: boolean that indicates if user tried to spoof the system
• base64Images: base64 representations of the selfie image
• faceMatched: boolean that indicates if the faces matched
• customerUUID: unique user identifier if the user successfully authenticated
• interviewId: sessionId in which the user got approved
• interviewToken: session token in which the user got approved
• token: token that can be used for further API calls
• transactionId: unique identifier of face login attempt
• hasLenses: indicator if login attempt failed due to person wearing lenses (1:1 Face Login only)
• hasFaceMask: indicator if login attempt failed due to person wearing a face mask (1:1 Face Login only)

idProcess

• Success: onSuccess(IdProcessResult result).
• Error: onError(String error).

IdProcessResult contains:

• ocrData: String?. Raw JSON containing full OCR data i.e. exteriorNumber, interiorNumber, typeOfId, documentFrontSubtype

addFace

• Success: onSuccess(bool result).
• Error: onError(String error).

removeFace

• Success: onSuccess(bool result).
• Error: onError(String error).

getFaces

• Success: onSuccess(List<FaceInfo> faceInfos).
• Error: onError(String error).

setFaces

• Success: onSuccess(bool result).
• Error: onError(String error).

deleteLocalUserData

• Returns a Future that completes once locally stored user data is deleted. No result object or error is reported.

getUserScore

• Success: onSuccess(UserScoreResult result).
• Error: onError(String error).

UserScoreResult has the extendedUserScoreJsonData String field which contains full user data in a JSON format (see UserScore under Module result objects for the full structure).

addNOM151Archive

• Success: onSuccess(AddNom151Result addNom151Result).
• Error: onError(String error).

AddNom151Result contains two String fields:

• signature: String?
• archiveUrl: String?

getUserOCRData

• Success: onSuccess(GetUserOCRDataResult result).
• Error: onError(String error).

GetUserOCRDataResult contains:

• ocrData: String. Full OCR data in a JSON format.

isInitialized

• Returns a Future<bool> that resolves to true when the SDK is ready to be used, and false otherwise. The method never throws — any platform error is handled internally and reported as false.

onEvents

• When onboarding has been started, the optional onEvents callback delivers OnEventsResult for every tracked user step:
  • event: String — Unique identifier of the event
  • data: String? — JSON string with additional event details

Methods without a result

The following methods return no result object and report no errors: setSdkMode, setTheme, setString, setLocalizationLanguage, and showCloseButton.

Module result objects

This section lists the result objects returned by the SDK, organized by module.

Phone

Specify onAddPhoneNumberCompleted to one of the start methods, to receive PhoneNumberResult:

• phone : String, the phone number user entered

FullName

Specify onAddFullNameCompleted to one of the start methods, to receive AddFullNameResult:

• name : String, the name user entered

Email

Specify onAddEmailCompleted to one of the start methods, to receive AddEmailResult:

• email : String, the email user entered

IdScan

Specify onIdFrontCompleted and/or onIdBackCompleted and/or onIdFrontAttemptCompleted and/or onIdBackAttemptCompleted to one of the start methods, to receive IdScanResult result:

• image: Captured ID image
• base64Image: String?. Captured front ID in base64 format
• croppedFace: Cropped face from captured ID image
• chosenIdType: User chosen type on ID selection screen- id or passport
• classifiedIdType: type of the captured ID
• idCategory: IdCategory. Category of the scanned ID
• failReason: String?. Reason why ID scan failed
• issueName: String?. Detailed type of the ID
• issueYear: int?, year when the ID was issued
• countryCode: String?, Country code where the ID was issued
• scanStatus: If status has a value other than IdValidationStatus.ok you can consider the ID scan and/or validation did not come through successfully. Other status messages are: errorClassification, noFacesFound, errorCropQuality, errorGlare, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorAddress, errorPassportClassification, errorUnacceptableID.
• allAttemptsExhausted: Indicates whether all retry attempts have been exhausted. Reflects the outcome of the current side (front or back) independently.

Specify onIdProcessed to one of the start methods, to receive String OCR result:

• ocrData: String?. Raw JSON containing full OCR data i.e. exteriorNumber, interiorNumber, typeOfId, documentFrontSubtype

SelfieScan

Specify onSelfieScanCompleted and/or onSelfieScanAttemptCompleted to one of the start methods, to receive SelfieScanResult:

• image: Uint8List?. Captured Selfie image
• spoofAttempt: bool. false means that person trying to do selfie is a real person. true means it is a spoof attempt, meaning that person is trying to spoof the system by pretending to be someone else using a physical paper, digital photo or other methods. nil means that unexpected error happened so it couldn't be determined if the selfie scan was a spoof attempt or not.
• base64Images: SelfieScanBase64Images. Contains image, in different formats, taken during Selfie Scan
  • selfieBase64: String?. Captured Selfie base64 image
  • selfieEncryptedBase64: String?. Captured Selfie encrypted base64 image
• allAttemptsExhausted: Indicates whether all retry attempts have been exhausted.

FaceMatch

Specify onFaceMatchCompleted to one of the start methods, to receive FaceMatchResult:

• confidence: double?
• existingInterviewId: String?. If user is existing user this field is populated with existing interview id.
• idCategory : IdCategory. Category of the ID that was used for face match.
• isExistingUser: bool. Indicates whether the user is new or existing one.
• isFaceMatched: bool. true means person's selfie matched successfully with the front ID. false it means that person's selfie isn't matched with the front ID image. null it means that front ID image wasn't uploaded at all, so the face match service didn't have data to compare with selfie
• isNameMatched: bool?
• nfcVsIdConfidence: double?
• nfcVsSelfieConfidence: double?
• secondIdConfidence: double?

Geolocation

Specify onGeolocationCompleted to one of the start methods, to receive GeoLocationResult:

• city: String?
• colony: String?
• postalCode: String?
• state: String?
• street: String?

GovernmentValidation

Specify onGovernmentValidationCompleted to one of the start methods, to receive GovernmentValidationResult:

• success: bool, true if the government validation was performed successfully, false otherwise.

VideoSelfie

Specify onVideoSelfieCompleted to one of the start methods, to receive VideoSelfieResult:

• success: bool, true if the video selfie was performed successfully, false otherwise.

Antifraud

Specify onAntifraudCompleted to one of the start methods, to receive AntifraudResult:

• success: bool, true if the antifraud was passed successfully, false otherwise.

UserScore

Specify onUserScoreFetched to one of the start methods, to receive UserScoreResult.

• extendedUserScoreJsonData: String?.
• overall: _UserScore?. Contains value and status of overall user score.
  • value: String?.
  • status: UserScoreStatus?.
• faceRecognition: _UserScore?. Contains value and status of face recognition user score.
  • value: String?.
  • status: UserScoreStatus?.
• liveness: _UserScore?. Contains value and status of liveness user score.
  • value: String?.
  • status: UserScoreStatus?.
• idValidation: _UserScore?. Contains value and status of id validation user score.
  • value: String?.
  • status: UserScoreStatus?.

Example UserScoreResult for completion of the module:

{
  ovarall: {
    value: '0.0/100',
    status: 'ok'
  },
  faceRecognition: {
    value: '0.0/100',
    status: 'warn',
  },
  liveness: {
    value: '95.2/100',
    status: 'manual',
  },
  idValidation: {
    value: '79.0/100',
    status: 'fail',
  },

}

The field status can have one of the following values: warning, unknown, manual, fail and ok.

Approve

Specify onApproveCompleted to one of the start methods, to receive ApprovalResult.

• success: bool. true if the approval was successful, false otherwise.
• uuid : String?. Customer ID of newly created customer if approval was successful, null otherwise.
• customerToken : String?. Customer token for newly created customer if approval was successful, null otherwise.

Signature

Specify onSignatureCollected to one of the start methods, to receive SignatureResult.

• signature: Uint8List?. Collected signature image.

Document

Specify onDocumentScanCompleted to one of the start methods, to receive DocumentScanResult.

• image: Uint8List?. Document scan image.
• documentType: DocumentType. Type of scanned document.
• address: Map<String, dynamic>?. Address fetched from the document. Will be available only for DocumentType.addressStatement
• ocrData: Raw JSON containing full OCR data

Captcha

Specify onCaptchaCompleted to one of the start methods, to receive CaptchaResult.

• captcha: String?. Entered captcha.

CURP

Specify onCurpValidationCompleted to one of the start methods, to receive CurpValidationResult.

• curp: String?. User's CURP.
• valid: bool?. Tells if user's CURP is valid. Null means there is no result (user decided to skip).
• data: Map<String, dynamic>?. User's CURP data.

OCREdit

Specify onOCREditCompleted to one of the start methods, to receive OCREditResult.

• success: bool. true if OCREdit completed successfully, false otherwise.

EKYB

Specify onEKYBCompleted to one of the start methods, to receive EKYBResult.

• success: bool. true if eKYB scan completed successfully, false otherwise.

EKYC

Specify onEKYCCompleted to one of the start methods, to receive EKYCResult.

• success: bool. true if eKYC scan completed successfully, false otherwise.

MLConsent

Specify onMLConsentCompleted to one of the start methods, to receive MLConsentResult.

• success: bool. true if the user has given the machine learning consent, false otherwise.

UserConsent

Specify onUserConsentCompleted to one of the start methods, to receive UserConsentResult.

• success: bool. true if the user has given consent, false otherwise.

CombinedConsent

Specify onCombinedConsentCompleted to one of the start methods, to receive CombinedConsentResult.

• success: bool. true if the user has given the data sharing consent, false otherwise.

QRScan

Specify onQRScanCompleted to one of the start methods, to receive QRScanResult.

• success: bool. true if QR scan completed successfully, false otherwise.

GlobalWatchlist

Specify onGlobalWatchlistCompleted to one of the start methods, to receive GlobalWatchlistResult.

• success: bool. true if GlobalWatchlist completed successfully, false otherwise.

CustomWatchlist

Specify onCustomWatchlistCompleted to one of the start methods, to receive CustomWatchlistResult.

• success: bool. true if CustomWatchlist completed successfully, false otherwise.

Aes

Specify onAesCompleted to one of the start methods, to receive AesResult.

• success: bool. true if Aes completed successfully, false otherwise.
• error: AesError.

NFCScan

Specify onNFCScanCompleted to one of the start methods, to receive NFCScanResult:

• success: bool?. A bool value stating if the NFC scan was successful.
• birthDate: String?. A String in "yyMMdd" format of the date of birth of the document owner.
• compositeCheckDigit: String?. A character representing the digit used to check the integrity of all the data in the MRZ of the document.
• dateOfBirthCheckDigit: String?. A character representing the digit used to check the integrity of the birthDate field.
• documentCode: String?. A String representing what type of ICAO 9303 compliant document this is. For example, a passport booklet is TD3. Can be one of: TD1-3, MRVA, or MVRB.
• documentNumber: String?. A String representing the 9 most significant digits of the passport number, CIC, etc.
• documentNumberCheckDigit: String?. A character representing the digit used to check the integrity of the documentNumber field.
• expirationDateCheckDigit: String?. A character representing the digit used to check the integrity of the expireAt field.
• expireAt: String?. A String in "yyMMdd" format of the document's expiration date.
• gender: String?. A String representing the gender of the document owner. Can be one of: M, F, UNKNOWN, or UNSPECIFIED.
• issuingStateOrOrganization: String?. A String containing the 3-letter Code of which authority issued this document. For example, for US Passports, this code is: USA.
• nationality: String?. A String containing the 3-letter Code of the document owner's nationality. For example, for UK Passports, this code is: GBR.
• optionalData1: String?. A String with the contents of the first optional data for TD-1 and 3 style MRZs.
• optionalData2: String?. An optional String with the contents of the second optional data for TD-1 style MRZs only.
• personalNumber: String?. A String with the personal number of the document owner if it's encoded in optionalData1.
• personalNumberCheckDigit: String?. An optional Char representing the digit used to check the integrity of the personalNumber field. This is only populated if documentCode is TD3.
• primaryIdentifier: String?. A String representing the primary means of identifying the document. Typically, this is the document owner's last name.
• secondaryIdentifier: String?. A String representing secondary means of identifying the document. Typically, this is the document owner's other names besides the last.

FaceAuthentication

Specify onFaceAuthenticationCompleted to one of the start methods, to receive FaceAuthenticationResult:

• status: A bool value stating if the face authentication was successful.
• customerUUID: String?. The unique identifier of the customer if the face authentication was successful.
• selfieBase64: String?. The base64 representation of the selfie image taken during face authentication.
• selfieEncryptedBase64: String?. The encrypted base64 representation of the selfie image taken during face authentication.
• error: String?. A String describing the error if the face authentication was not successful.