Results

This page describes promise results, listener payloads, and common error codes.

API results

Error enums

IncodeSdk.initialize() can reject with IncodeSdkInitError.

type IncodeSdkInitErrorCode =
  | 'simulatorDetected'
  | 'testModeEnabled'
  | 'invalidInitParams'
  | 'configError'
  | 'activityNotPresent'
  | 'unknown';

Flow APIs can reject with IncodeSdkFlowError.

type IncodeSdkFlowErrorCode =
  | 'simulatorDetected'
  | 'rootDetected'
  | 'hookDetected'
  | 'virtualEnvDetected'
  | 'permissionsDenied'
  | 'jailbreakDetected'
  | 'faceAuthenticationFailed'
  | 'unknown';

startOnboarding, startFlow, and startWorkflow

Successful completion resolves with:

{ "status": "success" }

User cancellation resolves with:

{ "status": "userCancelled" }

Some legacy documentation and native payloads may refer to the same state as user_cancelled.

setupOnboardingSession

{
  interviewId: string;
  token: string;
}

startOnboardingSection

{
  status: 'success' | 'userCancelled';
  sectionTag: string;
}

startFaceLogin

{
  faceMatched: boolean;
  spoofAttempt: boolean;
  image?: { pngBase64?: string; encryptedBase64?: string };
  customerUUID?: string;
  interviewId?: string;
  interviewToken?: string;
  token?: string;
  transactionId?: string;
  hasFaceMask?: boolean;
}

Example Face Login response:

{
  "faceMatched": true,
  "spoofAttempt": false,
  "image": {
    "pngBase64": "...PNG Base 64 encoded",
    "encryptedBase64": "...PNG Encrypted Base 64 encoded"
  },
  "customerUUID": "exampleCustomerUUID",
  "interviewId": "exampleInterviewID",
  "interviewToken": "exampleInterviewToken",
  "token": "exampleToken",
  "transactionId": "Unique Authentication attempt ID",
  "hasFaceMask": false
}

For 1:1 Face Login, faceMatched can be false when faces do not match or when the user with the supplied customer token and customerUUID is not found. For 1:N Face Login, faceMatched can be false when the captured face is not associated with an approved user in the database.

hasFaceMask is available on iOS only; Android forces the user to remove the mask before login is performed.

getUserScore

Returns the same UserScore data that the UserScore module provides:

{
  overallScore: string;
  status: 'ok' | 'warn' | 'unknown' | 'fail' | 'manual';
  facialRecognitionScore: string;
  existingUser: boolean;
  idVerificationScore: string;
  livenessOverallScore: string;
}

await IncodeSdk.getUserScore({ mode: 'accurate' });

Compact form: {mode: 'accurate'}.

approve

{
  status: 'approved' | 'failed';
  id: string;
  customerToken: string;
}

Use the forceApproval argument when calling approve(). Some older text called this forceApprove.

faceMatch

Returns a FaceMatch completion event payload.

Methods without a meaningful payload

finishOnboardingFlow, deleteLocalUserData, showCloseButton, setTheme, setUXConfig, setString, setQuantityStrings, setLocalizationLanguage, setFaceAuthenticationHint, setSdkMode, downloadOnDemandResources, removeOnDemandResources, and checkOnDemandResourcesDownloaded are primarily command-style methods.

Listener results

The SDK offers several types of listeners:

• user cancellation
• tracking events
• SSL pinning failed
• step completion, for each module individually
• step error, for each module individually
• step update, for each module individually

User cancellation

If the user cancels onboarding, startOnboarding, startFlow, and startWorkflow return status: 'userCancelled'.
On both platforms, the user can cancel by pressing the close button that can be enabled using IncodeSdk.showCloseButton(true). On Android, the user can also cancel by pressing the back key.

Session created

When an onboarding session gets created, the information about the session can be obtained via IncodeSdk.onSessionCreated.

IncodeSdk.onSessionCreated((session) => {
  console.log('Onboarding session created, interviewId: ' + session.interviewId);
});

The session event includes:

• interviewId: string. Unique identifier of the onboarding session.
• token: string. Token created for this onboarding session.

Tracking events

When onboarding has started, tracking events can be obtained using onEvents.

IncodeSdk.onEvents((eventBatch) => {
  for (const event of eventBatch.events) {
    console.log(event.event, event.data);
  }
});

The listener receives:

• events: EventDetails[]. Array of emitted events.
• event: string. Unique identifier of the event.
• data: string. JSON string with additional event details.

Step completion

When a step in the configured onboarding flow is completed, register a listener via IncodeSdk.onStepCompleted. The listener config takes the module name and callback.

const unsubscribe = IncodeSdk.onStepCompleted({
  module: 'SelfieScan',
  listener: (event) => {
    console.log(event.result);
  },
});

Step completion events are delivered through onStepCompleted(). In-progress events are delivered through onStepUpdated().

Step update

When a step in the configured flow is updated, register a listener via IncodeSdk.onStepUpdated. The listener config takes the module name and callback.

IncodeSdk.onStepUpdated({
  module: 'IdScanFront',
  listener: (event) => {
    console.log('ID Scan Front Attempt: ', event.result);
    console.log('ID Scan Front Attempt allAttemptsExhausted:', event.result.allAttemptsExhausted);
  },
});

onStepUpdated currently emits updates for Conference, IdScanFront, IdScanBack, and SelfieScan.

Module callback payloads

IdScanFront

• image: IncdImage object, containing pngBase64 of the captured front ID
• croppedFace: IncdImage object, containing pngBase64 of the cropped face from the front ID
• classifiedIdType: the String - Classified ID type by Incode, ie. Voter Identification
• chosenIdType: the String - what did the user choose to capture id or passport
• idCategory: String, category of the ID verified primary or secondary
• status: the String . If value is other than ok you can consider the ID scan and/or validation did not come through successfully. The Incode UI will clearly inform the user about these errors and will attempt the scan several times, before responding with an error. Possible error values: errorClassification, noFacesFound, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorClassification, errorShadow, errorPassportClassification.
• failReason: (optional) String - The reason for the scan failure, if applicable.
• issueName: (optional) String - The name of the issuing authority of the document.
• issueYear: (optional) number - The year the document was issued.
• countryCode: (optional) String - The country code of the document.
• allAttemptsExhausted: (optional) boolean - Indicates whether all capture attempts have been exhausted.

IdScanBack

• image: IncdImage object, containing pngBase64 of the captured back ID
• croppedFace: IncdImage object, containing pngBase64 of the cropped face from the back ID
• classifiedIdType: the String - Classified ID type by Incode, ie. Voter Identification
• chosenIdType: the String - what did the user choose to capture id or passport
• idCategory: String, category of the ID verified primary or secondary
• status: the String . If value is other than ok you can consider the ID scan and/or validation did not come through successfully. The Incode UI will clearly inform the user about these errors and will attempt the scan several times, before responding with an error. Possible error values: errorClassification, noFacesFound, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorClassification, errorShadow, errorPassportClassification.
• failReason: (optional) String - The reason for the scan failure, if applicable.
• issueName: (optional) String - The name of the issuing authority of the document.
• issueYear: (optional) number - The year the document was issued.
• countryCode: (optional) String - The country code of the document.
• allAttemptsExhausted: (optional) boolean - Indicates whether all capture attempts have been exhausted.

Notes:

• result.data.birthDate is the epoch time.
• result.status.back and result.status.front can take one of following values: ok or several others indicating an issue with the scanning. The Incode UI will clearly inform the user about these errors and will attempt the Scan several times, before responding with an error. Other errors are: errorClassification, noFacesFound, errorCropQuality, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, errorClassification, shadow, errorAddress, errorPassportClassification, errorReadability.

ProcessId

• data: the basic IdScanOcrData object, containing most important data
• ocrData: the String object, raw JSON containing full OCR data ie. exteriorNumber, interiorNumber, typeOfId, documentFrontSubtype

Notes:

• result.data.birthDate is the epoch time.

Conference

This module starts a video conference call with the executive.

Example response for completion of the step:

{
  "step": "Conference",
  "result": {
    "status": "success"
  }
}

Example response for error of the step:

{
  "step": "Conference",
  "result": {
    "status": "error"
  }
}

The field result.status can have values userCancelled, invalidSession or error;

DocumentScan

The DocumentScan will attempt reading address from the provided document.

Note: If the user decides to skip this step, you will get a response with blank values, instead of nil/error.

Example response for completion of the step:

{
  "result": {
    "address": { // parsed OCR data
      "city": "Springfield",
      "colony": "Springfield",
      "postalCode": "555555",
      "state": "Serbia",
      "street": "Evergreen terrace"
    },
    "data": {"raw JSON OCR data"},
    "type": "addressStatement",
    "image": {"pngBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD/4..."},
  },
  "step": "DocumentScan"
}

Example response for error of the step:

{
  "status": "userCancelled",
  "step": "DocumentScan"
}

The field status can have one of the following values: permissionsDenied, simulatorDetected or unknown.

Geolocation

The Geolocation steps yields the current location of the user. Example response for completion of the step:

{
  "result": {
    "city": "Springfield",
    "colony": "Springfield",
    "postalCode": "555555",
    "state": "Serbia",
    "street": "Evergreen terrace"
  },
  "step": "Geolocation"
}

The field status can have one of the following values: permissionsDenied, unknownError, noLocationExtracted or locationUnavailable.

UserConsent

In case the user has given the consent:

{
  "status": "success",
  "step": "UserConsent"
}

If the user declined to give the consent, the onboarding flow will be ended with a status userCancelled.

MLConsent

In case the user has given the machine learning consent:

{
  "status": "success",
  "step": "MLConsent"
}

CombinedConsent

In case the user has given the data sharing consent:

{
  "status": "success",
  "step": "CombinedConsent"
}

If the user declined to give the data sharing consent, the onboarding flow will be ended with a status userCancelled.

The field status can have one of the following values: success or fail.

GovernmentValidation

This module enables your user to input their information to validate with Government services as a part of your flow.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "GovernmentValidation"
}

The field status can have one of the following values: success or fail.

Antifraud

This module gives ability to compare current interview with existing interviews and customers and detect anomalies that could be signs of fraud.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "Antifraud"
}

The field status can have one of the following values: success or fail.

Name

This module enables to capture user's name as a part of your flow.

On module completion, the result returned will look like this:

{
  "status": "success",
  "name": "exampleName",
  "step": "Name"
}

The field status can have one of the following values: success or fail.

CURP

This module enables your user to input their CURP information to validate with RENAPO service as a part of your flow. (CURP is a person identifier in México)

On module completion, the result returned will look like this:

{
  "status": "success",
  "curp": "exampleCurp",
  "step": "CURP"
}

The field status can have one of the following values: success or fail.

OCREdit

This module will show to the user parsed OCR from his ID, which can be optionally edited.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "OCREdit"
}

The field status can have one of the following values: success or fail.

eKYB

This module enables a step of KYB validation with the business information and an option of source for this information which includes business name, addresses, city, state, postal code and bank account number.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "eKYB"
}

The field status can have one of the following values: success or fail.

eKYC

This module enables a step of kyc validation with the user's information and an option of source for this information which includes data obtained from id, proof of address, or a manual capture.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "eKYC"
}

The field status can have one of the following values: success or fail.

GlobalWatchlist

This module checks customer identities against sources of Sanctions, Politically Exposed Persons (PEPs), & Watchlists.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "GlobalWatchlist"
}

The field status can have one of the following values: success or fail.

CustomWatchlist

This module checks if the user is found on the watchlist. Watchlist is configured in incode's dashboard.

On module completion, the result returned will look like this:

{
  "status": "success",
  "step": "CustomWatchlist"
}

The field status can have one of the following values: success or fail.

Aes

This module enables an advanced electronic signature to ensure legally binding and compliant document signing with enhanced security and authentication measures.

On successfull module completion, the result returned will look like this:

{
  "status": "success",
  "step": "Aes"
}

The field status can have one of the following values: success or fail.

Example response for error of the step:

{
  "status": "fail",
  "error": "noDocuments",
  "step": "Aes"
}

NFCScan

The NFC Scanning module reads and verifies chip data from ePassports or ID cards to validate document authenticity, detect tampering, and enhance anti-spoofing.

Example response for completion of the step:

{
  "status": "success",
  "birthDate": "900101",
  "compositeCheckDigit": "7",
  "dateOfBirthCheckDigit": "3",
  "documentCode": "TD3",
  "documentNumber": "123456789",
  "documentNumberCheckDigit": "5",
  "expirationDateCheckDigit": "2",
  "expireAt": "300101",
  "gender": "M",
  "issuingStateOrOrganization": "USA",
  "nationality": "USA",
  "optionalData1": "ABCDEFGHI",
  "optionalData2": null,
  "personalNumber": "987654321",
  "personalNumberCheckDigit": "4",
  "primaryIdentifier": "DOE",
  "secondaryIdentifier": "JOHN MICHAEL"
}

FaceAuthentication

The Incode Face Authentication functionality allows you to identify previously registered users using face recognition. Depending on your use case, this is an excellent way to grant access to certain parts of your application or authorize high-value operations with very low friction.

{
  "status": "success",
  "customerUUID": "1234567890",
  "selfieBase64": "abcdefg",
  "selfieEncryptedBase64": "abcdefg",
  "error": null
}

FaceMatch

This module checks if the face from the scanned ID/passport and the face obtained from the SelfieScan module are a match.

Example response for completion of the step:

{
  "result": {
    "status": "match",
    "confidence": 1,
    "nameMatched": false,
    "existingUser": false,
    "existingInterviewId": "exampleInterviewID",
    "idCategory": "primary"
  },
  "step": "FaceMatch"
}

The field result.status can take values match or mismatch.
Example response for error of the step:

{
  "status": "userCancelled",
  "step": "FaceMatch"
}

The field status can have one of values: unknownError or simulatorDetected.

Phone

This module enables the user to enter their phone number.
Example response for completion of the step:

{
  "result": { "phone": "+15555555555", "resultCode": "success" },
  "step": "Phone"
}

The field result.resultCode can take the value success.

Example response for error of the step:

{
  "status": "error",
  "step": "Phone"
}

The field status can take one of the values: invalidSession, userCancelled, error.

Email

This module enables the user to enter their email.
Example response for completion of the step:

{
  "result": { "email": "[email protected]", "status": "success" },
  "step": "Email"
}

Example response for error of the step:

{
  "status": "fail",
  "step": "Email"
}

Signature

This module enables user to add a digital signature by signing on a canvas.

Besides sepcifying title and description keys it is needed to provide texts for Android and iOS in their res/values/strings.xml and Localizable.strings files.

{
  module: 'Signature',
  title: 'onboard_sdk_signature_title',
  description: 'onboard_sdk_signature_description',
  descriptionMaxLines: 2
}

For Android:

<string name="onboard_sdk_signature_title">Example title</string>
<string name="onboard_sdk_signature_description">Description example</string>

For iOS:

"onboard_sdk_signature_title" = "Example title";
"onboard_sdk_signature_description" = "Description example";

Example response for completion of the step:

{
  "result": { "status": "success", "image": "...PNG Base 64 encoded" },
  "step": "Signature"
}

Example response for error of the step:

{ "status": "error", "step": "Signature" }

The field status can take one of following: error or invalidSession.

SelfieScan

• allAttemptsExhausted: (optional) boolean - Indicates whether all capture attempts have been exhausted.

Example result:

{
  "result": { "spoofAttempt": false, "status": "success", "allAttemptsExhausted": false },
  "step": "SelfieScan",
  "image": {
    "pngBase64": "...PNG Base 64 encoded",
    "encryptedBase64": "...PNG Encyrpted Base 64 encoded"
  }
}

Example response for error of the step:

{
  "status": "success",
  "step": "SelfieScan"
}

The field status can take one of the values: none, permissionsDenied, simulatorDetected, spoofDetected.

Approve

Adding this module to the flow instructs the Incode server to perform the approval of the user.

Example response for completion of the module:

{ "result": { "status": "approved", "id": "customerUUID", "customerToken": "customerToken"}}, "step": "Approve" }

• The field status can take values: approved and failed.

Example response for error of the module: there is no error.

UserScore

This module displays the user score using the UI.

Example response for completion of the module:

{
  "result": {
    "data": {
      "existingUser": true,
      "facialRecognitionScore": "0.0/100",
      "idVerificationScore": "79.0/100",
      "livenessOverallScore": "95.2/100",
      "overallScore": "0.0/100",
      "status": "fail"
    },
    "extendedUserScoreJsonData": "{..}"
  },
  "step": "UserScore"
}

data will contain basic parsed users core data.
extendedUserScoreJsonData will contain raw JSON containing full user score data.

Example response for error of the module:
The field result.data.status can have one of the following values: warning, unknown, manual and fail.

QrScan

This module captures the QR code on the back of the ID, extracts the valuable data out of it and sends it to the server.

VideoSelfie

This module records the device's screen while the user needs to do a selfie, show his ID, answer a couple of questions and confirms that he accept the terms and conditions. The recorded video is then uploaded and stored for later usage.

Captcha

This module asks the user to enter OTP generated for current session.
If the user doesn't enter correct OTP multiple times the flow will be terminated.
On module completion, the result given to the listener will take the shape of:

{
  "result": {
    "status": "success",
    "response": "ABCDEF"
  }
}

Note: Captcha failure will result in rejection of Onboarding promise. There is no module error listener here.