DocumentationAPI Reference
Integrate by platform · Backend / How To Fetch Onboarding Results And Data

Fetch Score Data

What is score data?

Score data includes all results associated with the checks and validations included in a given flow configuration.

How can I see score data?

You can see this data by either:

  • Going to Dashboard > Sessions, locating the session you want to review, and selecting it.
  • Using the fetch scores API endpoint to obtain the data as a JSON response. You can also test this endpoint yourself at the preceding link. This is the same API endpoint used by the Incode Dashboard.

To fetch score data for a given onboarding session, you must pass the session's unique interview ID, also called the Session ID, to the fetch scores API endpoint. If you do not pass the interview ID, Incode attempts to extract it from the session token.

When is score data available?

Scores are calculated once an onboarding is finished and after rules have been applied. The associated score data can be viewed or fetched once the onboarding session has been marked as complete via the finish-status endpoint

How should I interpret score data?

In the Incode Dashboard, the Overall Status score is presented using the model of a traffic signal:

  • Green: OK; a passing score; that is, a go
  • Yellow: WARN; there are concerns in the data score; that is, a caution
  • Red: FAIL; that is, a stop

Even when you choose to directly fetch the data, keep this model in mind. While there may be dozens of scores and tests in every session, the most important score is always Overall Status. This is a composite score which factors in all the tests included in the settings of your configured flow.

Due to the complex nature of flow's and score calculations, we do not recommend you consider the numeric values of individual validations. Although this might be tempting, the Overall Status should be your guide to the outcome of the completed session.

Sample JSON File

Following is a sample JSON file as retrieved using the fetch scores API endpoint. This sample reflects the settings and results of a given flow. Your files will be based on your flows and may not look exactly like this one. However, the sample gives an idea of how you can use it to check the onboarding session's overall status, as well as the overall status per module validation. It also provides an explanation of the different JSON response parameters.

{
  ..., // subscores fields
  "idValidation": {
    "photoSecurityAndQuality": [
      ...
    ],
    "idSpecific": [
             ...
    ],
    "overall": {
      "value": "100.0", // avoid validating against this value
      "status": "OK" // this is the value you care about
    }
  },
    "liveness": {
    ...,
    "overall": {
      "value": "100.0", // avoid validating against this value
      "status": "OK" // this is the value you care about
    }
  },
  "faceRecognition": {
    "existingUser": true, // If true. this tells you if the user had a previous approved onboarding session
    "existingInterviewId": "", // this is the original approved session from this user
    ...,
    "overall": {
      "value": "83.2", // avoid validating against this value
      "status": "OK" // this is the value you care about
    }
  },
  "appliedRule": { // When a rule is applied it appears here
    "name": "Undeage Rule", // Name of the rule that got applied
    "expression": "underageCheck_STATUS == 'FAIL'", // The expression that got applied
    "ruleType": "total", // Type of the rule
    "status": "FAIL", // The new score that got applied
    "incodeScoreOverall": { // The score before it got triggered
      "value": "94.4",
      "status": "OK"
    }
  },
  "overall": {
    "value": "94.4", // avoid validating against this value
    "status": "OK" // this is the value you care about
  },
  "reasonMsg": "" // reason for the obtained overall score
}

Scores and OCR Data

Optical Character Recognition (OCR) data shows in the Incode Dashboard along with some scoring. This scoring relates solely to the level of confidence on the data extracted from the captured image of the ID. Level of confidence for OCR data does not directly affect or alter the score of a session.

{/*

Sample Response

{
  "idValidation": {
    "photoSecurityAndQuality": [
      {
        "value": "PASSED",
        "status": "OK",
        "key": "tamperCheck"
      },
      {
        "value": "PASSED",
        "status": "OK",
        "key": "alignment"
      },
      {
        "value": "PASSED",
        "status": "OK",
        "key": "fakeCheck"
      },
      {
        "value": "OK",
        "status": "OK",
        "key": "screenIdLiveness"
      },
      {
        "value": "OK",
        "status": "OK",
        "key": "paperIdLiveness"
      },
      {
        "value": "PASSED",
        "status": "OK",
        "key": "idAlreadyUsedCheck"
      },
      {
        "value": "99",
        "status": "OK",
        "key": "balancedLightFront"
      },
      {
        "value": "85",
        "status": "OK",
        "key": "balancedLightBack"
      },
      {
        "value": "97",
        "status": "OK",
        "key": "sharpnessFront"
      },
      {
        "value": "80",
        "status": "OK",
        "key": "sharpnessBack"
      }
    ],
    "idSpecific": [
      {
        "value": "100",
        "status": "OK",
        "key": "documentTypeSideCrosscheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "barcode2DDetected"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "visiblePhotoFeatures"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "expirationDateValidity"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "sexCrosscheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "documentNumberCrosscheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "issueDateValidity"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "birthDateCrosscheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "underageCheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "documentClassification"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "expirationDateCrosscheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "birthDateValidity"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "2DBarcodeContent"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "fullNameCrosscheck"
      },
      {
        "value": "100",
        "status": "OK",
        "key": "documentExpired"
      }
    ],
    "overall": {
      "value": "100.0",
      "status": "OK"
    }
  },
  "liveness": {
    "livenessScore": {
      "value": "100.0",
      "status": "OK"
    },
    "digitalAttack": {
      "status": "OK"
    },
    "evasionAttack": {
      "status": "FAIL"
    },
    "overall": {
      "value": "100.0",
      "status": "OK"
    }
  },
  "faceRecognition": {
    "existingUser": true,
    "existingInterviewId": "12345678920ed1c1234de223d",
    "maskCheck": {
      "value": "0",
      "status": "OK"
    },
    "lensesCheck": {
      "status": "OK"
    },
    "faceBrightness": {
      "status": "OK"
    },
    "overall": {
      "value": "83.2",
      "status": "OK"
    }
  },
  "idOcrConfidence": {
    "overallConfidence": {
      "value": "100.0",
      "status": "OK"
    }
  },
  "retryInfo": {
    "stepsToRetry": []
  },
  "overall": {
    "value": "94.4",
    "status": "OK"
  },
  "reasonMsg": "This session passed because it passed all of Incode's tests: Face Recognition, Liveness Detection, ID Verification"
}

Response Descriptions

The response payload is composed of subsections. See below for descriptions of each property.

  1. idValidation: Id validation of its overall score and two lists of executed tests and checks.
    1. photoSecurityAndQuality: List of tests. Each test contains:
      1. value: String
      2. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN", "MANUAL"
      3. key: String. Not all off the following data are always present. List of possible keys: "tamperCheck", "postitCheck", "alignment", "fakeCheck", "ocrIdentityCheck", "screenIdLiveness", "paperIdLiveness", "readabilityCheck", "balancedLightFront", "balancedLightBack", "sharpnessFront", "sharpnessBack"
    2. idSpecific: List of tests. Each test contains:
      1. value: String
      2. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      3. key: String. Not all off the following data are always present. List of possible keys: "documentClassification", "visiblePhotoFeatures", "issueDateValidity", "documentExpired", "documentSeriesExpired", "birthDateValidity", "expirationDateValidity", "issuingStateValidity", "qrScan", "documentNumberCheckDigit", "birthDateCheckDigit", "expirationDateCheckDigit", "compositeCheckDigit", "iliterationCheck", "birthDateCrosscheck", "expirationDateCrosscheck", "sexCrosscheck", "fullNameCrosscheck", "emissionNumberCrosscheck", "documentNumberCrosscheck", "personalNumberCrosscheck", "2DBarcodeContent", "barcode2DDetected", "documentTypeSideCrosscheck", "dD/ReferenceNumberCrosscheck", "underageCheck"
    3. customFields: List of custom field validations (only if custom fields are used in the onboarding process). Each validation contains:
      1. value: String
      2. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      3. key: String. Possible keys: "firstNameMatch", "lastNameMatch"
    4. appliedRule: Specific rule from rule engine for idValidation:
      1. name: String. Name of the rule.
      2. expression: String. A logical expression of the rule.
      3. ruleType: String. "idValidation"
      4. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      5. overall: see below. Composite result for id validation score.
  2. antifraud: The result antifraud-chek where we compare the current interview with existing interviews and customers and detect anomalies than could be signs of fraud.
    1. overall: see below. Result for antifraud score.
  3. secondIdValidation: Same as idValidation only applicable if onboarding is configured to capture a second id.
  4. liveness:
    1. livenessScore: Shows confidence that person is real.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      2. value: String. From 0 to 100
    2. photoQuality:
      1. value: String.
      2. overall: see below. Composite result for liveness score.
  5. faceRecognition:
    1. existingUser: Boolean. Flag indicating if a user is already enrolled.
    2. existingInterviewId: String. Session ID, in case the user, is approved in another session.
    3. existingExternalId: String. External ID, in case the user, is approved in another session.
    4. maskCheck: Shows info if the user was wearing a mask during selfie capture.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      2. value: String. From 0 to 100.
    5. lensesCheck: Shows info if the user was wearing lenses during selfie capture.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    6. faceBrightness: Shows status and level of brightness during selfie capture.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      2. value: String. Shows the level of brightness during selfie capture.
    7. nameMatch: Shows if the name matches the previously used (only in case the user is already approved in another session)
      1. status: String. Status can have one of the following values: "OK", "FAIL"
      2. appliedRule: Specific rule from rule engine for faceValidation:
      3. name: String. Name of the rule.
      4. expression: String. A logical expression of the rule.
      5. ruleType: String. "faceValidation"
      6. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    8. overall: see below. Shows how much face from ID matches the selfie.
  6. faceRecognitionSecondId: Same as faceRecognition only applicable if onboarding is configured to capture a second id.
  7. videoConference:
    1. speechTranscript: String. Extracted text from speech, during video recording.
    2. speechRecognition: This shows how much the recognized speech matches the expected result.
      1. status: String. Status can have one of the following values: "OK", "FAIL"
      2. value: String. From 0 to 100.
    3. videoSelfieLiveness: Shows liveness confidence that the person is real based on video conference.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      2. value: String. From 0 to 100.
    4. videoSelfieFaceRecognition: Shows how much face from id matches the video conference capture.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
      2. value: String. From 0 to 100.
    5. score: Overall video recording score.
      1. status: String. Status can have one of the following values: "OK", "FAIL"
      2. value: String, optional. Only in case status is "FAIL", value is "0.0".
  8. governmentValidation:
    1. recognitionConfidence: Optional. Only present in case face validation is performed as a part of government check.
      1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL"
      2. value: String. From 0 to 100
    2. validationStatus:
      1. status: String. Status can have one of the following values: "OK", "FAIL", "UNKNOWN"
      2. value: String. String representation of integer status code. Possible values: -1, 0-14, 99.
      3. key: String. Possible values: processingIne, ok, validationError, ineConnectionError, ineInfrastructureError, moduleNotSupported, missingDocumentId, missingSelfie, userNotFound, userNotFoundInIneDb, notEnoughData, livenessFail, ineNotCurrent, ineReportedLost, ineReportedStolen, ineSignaturError, geographicRegionNotSupported key-value mapping:
        -1: processingIne
        0: ok
        1: validationError
        2: ineConnectionError
        3: ineInfrastructureError
        4: moduleNotSupported
        5: missingDocumentId
        6: missingSelfie
        7: userNotFound
        8: userNotFoundInIneDb
        9: notEnoughData
        10: livenessFail
        11: ineNotCurrent
        12: ineReportedLost
        13: ineReportedStolen
        14: ineSignaturError
        99: geographicRegionNotSupported
    3. ocrValidation: List of value, status, key objects. Each test contains:
      1. value: String. Could be true or false
      2. status: String. Status can have one of the following values: "OK", "FAIL", "UNKNOWN"
      3. key: String. Not all off the following keys are always present: issueDate firstName, maternalLastName, paternalLastName, ocr, personalId, electorsKey, emissionNumber, registrationDate
    4. ocrValidationOverall: Composite result for ocrValidation score.
      1. status: String. Status can have one of the following values: "OK", "FAIL"
      2. value: String. From 0 to 100
    5. overall: Composite result for government validation score.
      1. status: String. Status can have one of the following values: "OK", "FAIL", "UNKNOWN"
      2. value: String. From 0 to 100
  9. externalVerification
    1. nameAddressCorrelation: Float. Shows the score of correlation between the name and address based on external sources.
    2. nameEmailCorrelation: Float. Shows the score of correlation between the name and email based on external sources.
    3. namePhoneCorrelation: Float. Shows the score of correlation between the name and phone based on external sources.
    4. addressRisk: Float. Shows the risk of address being a fraud based on external sources.
    5. emailRisk: Float. Shows the risk of the email is a fraud based on external sources.
    6. phoneRisk: Float. Shows the risk of the phone is a fraud based on external sources.
  10. curpVerification (only for Mex documents, in case curp validation was performed)
    1. success: Boolean. Flag indicating if the process finished successfully.
    2. curp: String. CURP value.
    3. sex: String. Gender
    4. nationality: String. Nationality.
    5. result: String. Result: success or error message.
    6. renapo_valid: Boolean. Flag indicating if the process finished successfully.
    7. names: String. Given names.
    8. paternal_surname: String. Paternal surname.
    9. mothers_maiden_name: String. Mother's maiden name.
    10. birthdate: String. Birthdate in format "DD/MM/YYYY",
    11. entity_birth: String.
    12. probation_document: String.
    13. status_curp: String.
    14. probation_document_data:
      1. foja: String.
      2. numEntidadReg: String.
      3. libro: String.
      4. NumRegExtranjeros: String.
      5. cveEntidadNac: String.
      6. numActa: String.
      7. CRIP: String.
      8. tomo: String.
      9. cveEntidadEmisora: String.
      10. anioReg: String.
      11. cveMunicipioReg: String.
      12. FolioCarta: String.
  11. ineScrapingValidation: (only for Mex documents in case INE scraping was performed)
    1. scrapingStatus: String. Scraping status. Possible values: IN_PROGRESS, FINISHED, ERROR
    2. success: Boolean. Flag indicating if the process finished successfully.
    3. result: String. Result: success or error.
    4. screenshotUrl: String.
    5. cic: String. Cic value.
    6. claveElector: String. Clave de elector.
    7. numeroEmision: String. Emission number.
    8. ocr: String. Ocr number.
    9. anioRegistro: String. Registration year.
    10. anioEmision: String. Emission year.
  12. idOcrConfidence: Confidence level for read ocr data from ID.
    1. overallConfidence:
      1. status: String. Status can have one of the following values: "OK", "FAIL"
      2. value: String. From 0 to 100
  13. idOcrConfidenceSecondId: Same as idOcrConfidence only applicable if onboarding is configured to capture a second id.
  14. retryInfo: Info about failed onboarding attempts (only if 'Onboarding flow attempts' > 0 in ID Capture module):
    1. failedAttemptsCounter: Object with counter of failed attempts per step
    2. stepsToRetry: Array of stepts retried. Possible values in array: frontId, backId, selfie, poa, governmentValidation
  15. appliedRule: Specific rule from rule engine for total:
    1. name: String
    2. expression: String
    3. ruleType: String. "total"
    4. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
  16. needsReviewReason: String, optional. In case the overall score status is MANUAL (Needs Review), returns reason. Possible values MANUAL_CAPTURE, RULE_APPLIED, OLD_ID
  17. incodeWatchlistScore: Incode watchlist score.
    1. watchlistScore:
      1. value: String. A number that represents a score.
    2. dataMatches: Array of fields used as data matching. Possible values: face, birthDate, name, idNumber, phone, email
  18. overall: Composite result for previous sections.
    1. status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN", "MANUAL"," MANUAL_OK",,"MANUAL_FAIL","MANUAL_PENDING"
    2. value: String. From 0 to 100

*/}

Was this page helpful?