User Verification Response

πŸ“˜

For all user verifications:

  • KYC
  • Govt Check
  • AML Check
  • Fraud Check
  • Biometric Check
  • Custom Template

AiPrise returns a streamlined response.

This document shows the structure of that response:

KeyValuePresence
aiprise_summaryAn overall summary of the response. Contains the final verification result.Present
statusThe run status of the verification.Present
status_reasonsIf for some reason, the verification failed, this populates the reasons.Optional
id_infoContains all the information extracted from the identity document.Optional
face_match_infoContains information about the face match between selfie and the identity document.Optional
face_liveness_infoContains information about user liveness.Optional
aml_infoContains AML checks of the user.Optional
client_reference_idAn ID you have associated with your verification request.Present
verification_session_idVerification Session ID (unique to every verification session).Present
template_idThe template ID against which verification was run.Present
environmentIn the sandbox, returns SANDBOX, in production, returns nullOptional
created_atCreation time of the verification session.

Stored as Unix timestamp in milliseconds.
Present

Response properties explained

aiprise_summary

This object contains the summary of results from AiPrise.

aiprise_summary is an object containing the following fields:

  • verification_result: string This is one of APPROVED, DECLINED, REVIEW, UNKNOWN.
Verification ResultDescription
APPROVEDThe end user or business has been verified. The verification process successfully completed.
DECLINEDThe end user or business has not been verified. The verification process successfully completed.
REVIEWThe end user or business needs to be manually looked at. The verification process successfully completed.
UNKNOWNUnknown status. The verification process is not started or has failed.

status

The status corresponds to the run status of the verification process.

status is a string which can be one of NOT_STARTED, RUNNING, PENDING, FAILED, COMPLETED.

StatusDescription
NOT_STARTEDThe verification process has not started yet. Most likely pre-conditions are being checked.
RUNNINGThe verification process is running.
PENDINGThe verification process is waiting for a third-party API to complete its processing.
FAILEDThe verification process failed. status_reasons(explained below) should have more details.
COMPLETEDThe verification process successfully completed.

status_reasons

This object is populated when the above status is set to FAILED

status_reasons is an array of objects. Example :

"status_reasons": [
  {
    "code": "API_DATA_REQUIREMENTS_NOT_MET",
    "message": "Invalid user data. identity_number_type missing."
  }
],

A full list of status_reasons can be found in Status Error Codes

id_info

This object contains ID data extracted from the document.

id_info is an object with the following structure

  • result: string: One of APPROVED, DECLINED, REVIEW, UNKNOWN.
  • warnings: Array of objects | null: A list of warnings associated with this ID.
  • status: string: One of COMPLETED, FAILED, PENDING.
  • status_reasons: Array of objects | null: A list of status reasons. Only present when the status is FAILED.
  • id_type: string | null: The type of identity document detected.
  • id_number: string | null: The document number or ID number.
  • personal_number: string | null: Many documents have 2 numbers, a document number, and a person's number. This field has information about the person's number.
  • id_expiry_date: string | null: ID expiry date in YYYY-MM-DD.
  • id_issue_date: string | null: ID issue date in YYYY-MM-DD.
  • first_name: string | null: First name extracted from the document.
  • middle_name: string | null: Middle name extracted from the document.
  • last_name: string | null: Last name extracted from the document.
  • second_last_name: string | null: Second last name extracted from the document. (Only returned in Latin American region.)
  • full_name: string | null: Full name extracted from the document. Only present if the first and last names were not extracted separately from the document.
  • birth_date: string | null: Birth date in YYYY-MM-DD.
  • gender: string | null: Gender of the user. It is not guaranteed to be of the form "M"/"F".
  • nationality: string | null: Nationality of the user.
  • nationality_code: string | null: Nationality of the user as an ISO 2-letter country code.
  • issue_country: string | null: Document issue country.
  • issue_country_code: string | null: Document issue country as an ISO 2-letter country code.
  • address: object | null: Contains address extracted from the document.
    • full_address: string | null: Address as a single string.
    • parsed_address: object | null: Parsed address.
      • address_street_1: object | null
      • address_street_2: object | null
      • address_city: object | null
      • address_state: object | null
      • address_country: object | null
      • address_zip_code: object | null
  • document_details: object | null: Contains details extracted from the document.
    • mrz_data: object | null: Contains details extracted from the document MRZ. It's a key-value pair where the key is of type string and value is of type string.
    • barcode_data: object | null: Contains details extracted from the document barcode. It's a key-value pair where the key is of type string and value is of type string.
    • ocr_data: object | null: Contains all data extracted from the document. It's a key-value pair where the key is of type string and value is of type string.
  • lookup_details: object| null: Contains details about ID from third-party and government databases.
    • lookup_list: Array of objects: A list containing ID lookup details
      • lookup_source: string | null: Name of third-party or government database.
      • lookup_type: string | null: One of CURP(Mexico), NIN(Nigeria), BVN(Nigeria), AADHAAR (India), PAN (India), VOTER_ID, PASSPORT, DRIVER_LICENSE, NATIONAL_ID.
      • issuer_country_code: string | null: 2-letter country code.
      • lookup_data: object | null: Raw data from the lookup. It's a key-value pair where the key is of type string and value is of type object.
      • result: string: One of APPROVED, DECLINED, REVIEW, UNKNOWN.
      • warnings: Array of objects | null: A list of warnings associated with this ID.
      • status: string: One of COMPLETED, FAILED, PENDING.
      • status_reasons: Array of objects | null: A list of status reasons. Only present when the status is FAILED.
  • field_info: object | null: Contains information about KYC fields and whether the extracted data is crosschecked with any other source. It is a key-value pair where the key is of type string and value if of type object.
    • key: the key is of type string and is one of id_number, id_expiry_date, id_issue_date, first_name, middle_name, last_name, second_last_name, full_name, personal_number, birth_date, gender.
    • value: value is of type object.
      • matched: Crosscheck databases for the key matches.
      • unmatched: Crosscheck databases the key does not match.

face_match_info

This object contains face-match data.

face_match_info is an object with the following structure

  • result: string: One of APPROVED, DECLINED, REVIEW, UNKNOWN.
  • warnings: Array of objects | null: A list of warnings associated with this ID.
  • status: string: One of COMPLETED, FAILED, PENDING.
  • status_reasons: Array of objects | null: A list of status reasons. Only present when the status is FAILED.
  • face_match_score: float: Face match score of the selfie provided and the selfie from the ID. The value is out of 100.

face_liveness_info

This object contains face liveness data.

face_liveness_info is an object with the following structure

  • result: string: One of APPROVED, DECLINED, REVIEW,UNKNOWN.
  • warnings: Array of objects | null: A list of warnings associated with this ID.
  • status: string: One of COMPLETED, FAILED, PENDING.
  • status_reasons: Array of objects | null: A list of status reasons. Only present when the status is FAILED.
  • source: string: | null: Only present in cases when AiPrise screens are used and in-screen liveness is enabled.

aml_info

This object contains AML data.

  • result: string: One of APPROVED, REVIEW, UNKNOWN.
  • warnings: Array of objects | null: A list of warnings associated with this ID.
  • status: string: One of COMPLETED, FAILED, PENDING.
  • status_reasons: Array of objects | null: A list of status reasons. Only present when the status is FAILED.
  • num_hits: int: Number of AML hits found.
  • entity_hits: Array of objects | null: A list of hits.
    • entity_type: string: One of PERSON, COMPANY, ORGANISATION, UNKNOWN.
    • name: string: Name against which the Hit has occurred.
    • name_match_score: float: Name match score. The value is out of 100.
    • date_of_birth: string | null: The date of birth. There is no defined format for the date.
    • date_of_birth_match_score: string | null: Date of birth match score. The value is out of 100.
    • also_known_as: Array of string: A list of alternate names for this entity.
    • aml_hits: Array of objects: A list of AML hits for this entity.
      • hit_type: string: One of PEP, SANCTION, ADVERSE_MEDIA, WARNING, FITNESS_PROBITY, CRIMINAL_RECORD, LEGAL_BACKGROUND, UNKNOWN.
      • source_details: object | null:
        • name: string | null: Source name.
        • source_id: string | null: Source id.
        • url: string | null: Source URL.
        • listing_started: string | null: Listing start date.
        • listing_ended: string| null: Listing end date.
        • country_codes: Array of strings | null: List of countries.
        • aml_types: Array of strings | null: Detailed AML types.
      • fields: Array of objects | null
        • name: string: The field key.
        • value: string | object: The field value.
        • type: string | null: The type of this field. One of date_of_birth, place_of_birth, date_of_death, country_codes, country_names, url.
      • media: Array of objects | null: A list of media objects.
        • title: string | null: Media listing title.
        • url: string| null: Media listing url.
        • date: string | null: Media listing date.
        • snippet: string | null: Media listing snippet.

client_reference_id

An ID you have associated with your verification request.

client_reference_id is a string

verification_session_id

Verification Session ID (unique to every verification session).

verification_session_id is a string

template_id

Template ID against which this verification was processed.

template_id is a string

environment

In the Sandbox environment, returns SANDBOX. In the production environment, the field is not present.

created_at

Unix timestamp in milliseconds at which the verification response was created.

created_at is an integer

Sample verification response:

{
    "aiprise_summary": {
        "verification_result": "APPROVED"
    },
    "aml_info": {
        "entity_hits": [],
        "num_hits": 0,
        "result": "APPROVED",
      	"status": "COMPLETED"
    },
    "client_reference_id": null,
    "created_at": 1681751214017,
    "face_match_info": {
        "face_match_score": 98.59,
        "result": "APPROVED",
      	"status": "COMPLETED"
    },
    "face_liveness_info": {
        "result": "APPROVED",
      	"status": "COMPLETED"
    },
    "id_info": {
        "address": {
            "full_address": "TEST_FULL_ADDRESS",
            "parsed_address": {
                "address_city": "TEST_CITY",
                "address_country": "USA",
                "address_state": "TEST_STATE",
                "address_street_1": "TEST_ADDRESS_STREET_1",
                "address_street_2": "TEST_ADDRESS_STREET_2",
                "address_zip_code": "TEST_ZIP_CODE"
            }
        },
        "birth_date": "1990-01-31",
        "document_details": {
            "ocr_data": {
                "Date of Birth": "1990-01-31",
                "Document Country": "MX",
                "Document Number": "TEST123",
                "Driver License Category": true,
                "Driver License Category From": "2019-10-06",
                "Driver License Category Until": "2025-10-05",
                "Expiry Date": "2030-12-31",
                "First Name": "TEST_FIRST_NAME",
                "Gender": "M",
                "Issue Date": "2015-12-31",
                "Issue Number": "1523",
                "Issued By": "ISSUER",
                "Last Name": "TEST_FIRST_NAME",
                "Nationality": "TEST_COUNTRY",
                "Place of Birth": "MADRID",
                "Year of Birth": "1990"
            },
            "mrz_data": {
                "Date of Birth": "1990-01-31",
                "Document Country": "MX",
                "Document Number": "TEST123",
            },
            "barcode_data": {
                "Date of Birth": "1990-01-31",
                "Document Country": "MX",
                "Document Number": "TEST123",
            },
        },
        "first_name": "TEST_FIRST_NAME",
        "gender": "M",
        "id_expiry_date": "2030-12-31",
        "id_issue_date": "2015-12-31",
        "id_number": "TEST123",
        "id_type": "DRIVER_LICENSE",
        "issue_country": "Mexico",
        "issue_country_code": "MX",
        "last_name": "TEST_LAST_NAME",
        "nationality": "TEST_COUNTRY",
        "result": "APPROVED",
      	"status": "COMPLETED"
    },
    "status": "COMPLETED",
    "template_id": "5fd6dddd-4bb1-4d31-8bd7-27801a176c8f",
    "verification_session_id": "2479f0221-517e-4f60-8dff-14a906098ad1"
}