Results

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. Possible error values: errorClassification, noFacesFound, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, 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. Possible error values: errorClassification, noFacesFound, errorGlare, errorReadability, errorSharpness, errorTypeMismatch, userCancelled, unknownError, 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.

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

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.

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"
}

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"
}

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.

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

Email

This module enables the user to enter their email.

Example response for completion of the step:

{
  "result": { "email": "email@example.com", "status": "success" },
  "step": "Email"
}

Signature

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

Example response for completion of the step:

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

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"
  }
}

Approve

Example response for completion of the module:

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

UserScore

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"
}

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 accepts 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.

Example response for completion of the step:

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