Incode Omni

Introduction

The Incode Omni API is organized around REST. In general our API uses standard secure HTTP requests with JSON arguments and JSON responses.

Authentication

REST API calls must be authenticated using a custom HTTP header X-Incode-Hardware-Id — along with a JSON web token. Additionally, every API call has to contain x-api-key header with valid client API key.

Headers

Custom headers in request:

• api-version: This header is mandatory for each request. Value must be set to 1.0
• x-api-key: This header is mandatory for each request. Client specific API key which should be issued by Incode sales support.
• X-Incode-Hardware-Id: The value for this header is should be set after start authentication endpoint.

Custom headers in response:

• Processing-Time: The value of this header represents server time needed for executing request (in milliseconds).

Error responses

Incode Omni uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g. missing required parameter).
• Codes in the 5xx range indicate server side errors (these are rare).

Some 4xx errors that could be handled programmatically include status of an error and message that briefly explains the error reported.

Arguments:

• timestamp: Long, UTC timestamp in milliseconds
• status: Integer, custom error code or http status code
• error: String, Http status error
• message: String, custom error message
• path: Stirng, endpoint path

Custom error codes are given for each endpoint.

Example:

 { 
 "timestamp": 1584639032757,
 "status": 4005,
 "error": "Spoof attempt detected",
 "message": "BadRequestException: Spoof attempt detected.",
 "path": "/omni/add/face"
}

HTTP status code summary:

• 200 (OK) - Everything worked as expected.
• 400 (Bad Request) - The request was unacceptable, often due to missing a required parameter.
• 401 (Unauthorized) - Invalid or missing access token.
• 403 (Forbidden) - Invalid or missing api key.
• 404 (Not Found) - The requested resource doesn't exist.
• 405 (Method Not Allowed) - Unacceptable HTTP method for requested resource.
• 406 (Not Acceptable) - Unacceptable request.
• 500, 502, 503, 504 (Server Errors) - Something went wrong on server side. (These are rare.)

API limitations

• Maximum Request Size: There is a limitation of 10Mb as the maximum possible request size in all our API, for that reason it is not possible to upload images or files larger than 10 Mb.

Start onboarding

POST /omni/start

This endpoint is mandatory to start any onboarding session in Incode omni and session can be monitored on the Incode dashboard. And it generates token which should be used for the authentication of future subsequent calls.

Request Body:

• countryCode: String, optional. Valid ISO alpha-2 or alpha-3 code of the country, or 'ALL'. This parameter should be used if document needs to be issued by given country. If not specified, general classifier will be used.

• language: String, optinal. Language code to be used when doing speech to text. Possible values: en-US, es-ES.

• externalId: String, optional. Id that identifies user in clients system should be used for externalId. (Deprecated as of Jan, 1 2024)

• externalCustomerId: String, optional. Similar to externalId, but instead of restarting session we would create new one each time. Should replace externalId eventually.

• interviewId: String, optional. InterviewId from a previous onboarding, including it helps get a new token for that id. (Deprecated as of Jan, 1 2024)

• uuid: String, optional. uuid key used in redis, can be used as an alternative to sending interviewId.

• configurationId: String, optional. Id of the flow to be used for this onboarding.

• redirectionUrl: String, optional. Url the user will be redirected to after finishing the onboarding successfully.

• customFields: JSON, optional. Used to send any additional information in key value pair format.

Eg:

{
  "countryCode": "ALL",
  "configurationId": "0000000000000",
  "externalId": "client34598",
  //"redirectionUrl": "https://example.com/",
  "customFields": {
    "firstName": "Mike",
    "lastName": "Larson"
  }
}

Response:

• token: String. Up to 256 characters. Internal JWT token used for the future subsequent calls. It is the value for X-Incode-Hardware-Id header in all other calls.

• interviewCode: String. 6 characters. This value is used for connecting to conference call.

• interviewId: String. 24 characters. Identifies the onboarding session that is initialized. Can be used for fetching data about that session in future calls.

• flowType: String, optional (only if configurationId is sent in request). Type of the flow used. Could be flow (in most cases), or legacy type configuration (not used anymore).

• idCaptureTimeout: Integer. Number of seconds after which manual capture button should be shown to the user, while capturing ID.

• selfieCaptureTimeout: Integer. Number of seconds after which manual capture button should be shown to the user, while capturing selfie.

• idCaptureRetries: Integer. Number of ID captures after which user should be taken to next screen.

• selfieCaptureRetries: Integer. Number of selfie captures after which user should be taken to next screen.

• curpValidationRetries: Integer. Number of curp validations after which user should be taken to next screen. (only for Mexico)

• clientId: String. Customer specific clientId that corresponds to api key.

• env: Sting. Server environment. Could be one of: stage, demo, saas.

• existingSession: Boolean. It's true if interviewId corresponds to an existing Onboarding Session.

Custom error statuses:

• 4026: Invalid uuid parameter
• 4027: Invalid configurationId
• 4028: Flow is not activated For more details about error format see errors section.

Fetch flow configuration

GET /omni/onboarding/flow

Fetches flow configuration relevant for mobile/web onboarding applications. Returned configuration belongs to flow attached to the session embedded in token. If no flow is attached to that session, 400 is returned with Flow not found for interview <interviewId> error message. This endpoint should replace GET /omni/flow/onboarding.

Response:

• name: String. Flow name.
• autoApproveEnabled: Boolean. Enable auto approve.
• autoApproveLevel: String. Auto approve level (secure, medium, conversion).
• questionsCount: String. Number of questions.
• checkTutorials: Boolean. Check tutorials.
• checkAuthorization: Boolean. Check authorization.
• redirectDesktopToMobile: Boolean. Redirect desktop user to mobile.
• addContinueToDesktop: Boolean. Add continue to desktop.
• redirectOriginOnly: Boolean. Redirect origin only.
• displayOnboardingResultOnDesktop: Boolean. Display onboarding result on desktop.
• enableMultipleOnboardings: Boolean. Enable multiple onboardings.
• disableLaunchScreen: Boolean. Disable launch screen.
• flowModules: Array. Relevant configuration per flow module.

Example:

{
    "name": "Maximum Example",
    "autoApproveEnabled": false,
    "autoApproveLevel": "conversion",
    "questionsCount": "3",
    "checkTutorials": true,
    "checkAuthorization": false,
    "redirectDesktopToMobile": false,
    "addContinueToDesktop": false,
    "redirectOriginOnly": false,
    "displayOnboardingResultOnDesktop": false,
    "enableMultipleOnboardings": false,
    "disableLaunchScreen": false,
    "disableMandatoryConsentCheck": false,
    "flowModules": [
        {
            "configuration": {
              "title": "title",
              "text": "text"
            },
            "key": "USER_CONSENT"
        },
        {
            "configuration": {},
            "key": "CHECKBOX_SIGNATURE"
        },
        {
            "configuration": {
                "consentType": "WORLDWIDE_CONSENT"
            },
            "key": "ML_CONSENT"
        },
        {
            "configuration": {
                "otpVerification": true,
                "otpExpirationInMinutes": 10
            },
            "key": "PHONE"
        },
        {
            "configuration": {
                "otpVerification": false,
                "otpExpirationInMinutes": 10
            },
            "key": "EMAIL"
        },
        {
            "configuration": {},
            "key": "NAME_CAPTURE"
        },
        {
            "configuration": {
                "showTutorial": false,
                "enableId": true,
                "enablePassport": true,
                "onlyFront": false,
                "secondId": true,
                "thirdId": false,
                "autoCaptureTimeout": 16,
                "captureAttempts": 3,
                "enableIdRecording": true,
                "overrides": {
                    "MEX": {
                        "VoterIdentification": {
                            "onlyFront": false
                        }
                    },
                    "SRB": {
                        "IdentificationCard": {
                            "onlyFront": true
                        }
                    }
                }
            },
            "key": "TUTORIAL_ID"
        },
        {
            "configuration": {
                "editableOcr": false
            },
            "key": "ID_OCR"
        },
        {
            "configuration": {},
            "key": "ID"
        },
        {
            "configuration": {
                "facialValidation": false,
                "alternativeFacialValidation": false,
                "fallbackEnabled": false,
                "scrapingMethod": false,
                "scrapingV2": false,
                "scrapingV3": false,
                "failUnsupportedId": false,
                "dataValidation": false,
                "mockConnectionError": false,
                "mockUserNotFoundError": false,
                "mockOK": false
            },
            "key": "INE_VALIDATION"
        },
        {
            "configuration": {
              "nfcAvailability": true,
              "nfcValidation": false
            },
            "key": "NFC_SCAN"
        },
        {
            "configuration": {
              "curpDataMatch": true
            },
            "key": "CURP_VALIDATION"
        },
        {
            "configuration": {
                "disableSkipPoa": false,
                "title": "PoA",
                "text": "Capture"
            },
            "key": "ADDRESS"
        },
        {
            "configuration": {
                "title": "Document",
                "text": "Capture"
            },
            "key": "DOCUMENT_CAPTURE"
        },
        {
            "configuration": {
                "showTutorial": false,
                "showPreview": false,
                "assistedOnboarding": false,
                "enableFaceRecording": true,
                "autoCaptureTimeout": 25,
                "captureAttempts": 3
            },
            "key": "SELFIE"
        },
        {
            "configuration": {
                "disableFaceMatchAnimation": false
            },
            "key": "FACE_MATCH"
        },
        {
            "configuration": {
                "checkName": true,
                "nameSource": "userInput",
                "checkEmail": true,
                "emailSource": "userInput",
                "checkAddress": true,
                "addressSource": "userInput",
                "checkPhone": true,
                "phoneSource": "userInput",
                "checkSsn": true,
                "ssnSource": "userInput",
                "checkDob": true,
                "dobSource": "userInput",
                "checkNationality": true,
                "nationalitySource": "userInput"
            },
            "key": "EXTERNAL_VERIFICATION"
        },
        {
            "configuration": {
                "checkBusinessName": true,
                "businessNameSource": "userInput",
                "checkAddress": true,
                "address": "userInput",
                "checkTaxId": true,
                "taxIdSource": "userInput"
            },
            "key": "EKYB"
        },
        {
            "configuration": {
                "useAsSelfie": false,
                "companyName": "",
                "checkLiveness": true,
                "checkIdScan": true,
                "checkDocumentScan": true,
                "compareIdEnabled": true,
                "compareOcrEnabled": true,
                "compareBackIdEnabled": true,
                "compareBackOcrEnabled": true,
                "checkVoiceConsent": true
            },
            "key": "VIDEO_ONBOARDING"
        },
        {
            "configuration": {},
            "key": "FISCAL_QR"
        },
        {
            "configuration": {},
            "key": "GEOLOCATION"
        },
        {
            "configuration": {},
            "key": "IP_ADDRESS"
        },
        {
            "configuration": {
              "title": "Title",
              "subTitle": "Sub Title"
            },
            "key": "SIGNATURE"
        },
        {
            "configuration": {
              "enableConferenceOtp": "true"
            },
            "key": "CONFERENCE"
        },
        {
            "configuration": {},
            "key": "SHOW_RESULTS"
        },
        {
            "configuration": {},
            "key": "FIELD_COMPARISON"
        },
        {
            "configuration": {},
            "key": "STADIUM_SELECTOR"
        },
        {
            "configuration": {},
            "key": "GENERATE_QR"
        },
        {
            "configuration": {},
            "key": "WATCHLIST"
        },
        {
            "configuration": {
                "failIfFaceOnBlocklist": false,
                "addSuspectedFraudAutomatically": false
            },
            "key": "INCODE_WATCHLIST"
        },
        {
            "configuration": {},
            "key": "FACE_ONBOARDING"
        },
        {
            "configuration": {
              "title": "Fields",
              "customFields": [
                {
                  "name": "first",
                  "alias": "1st",
                  "type": "STRING"
                },
                {
                  "name": "second",
                  "alias": "2nd",
                  "type": "INTEGER"
                },
                {
                  "name": "third",
                  "alias": "4rd",
                  "type": "DOUBLE"
                },
                {
                  "name": "fourth",
                  "alias": "4th",
                  "type": "BOOLEAN"
                }
              ]
            },
            "key": "CUSTOM_FIELDS"
        },
        {
            "configuration": {},
            "key": "ANTIFRAUD"
        },
        {
            "configuration": {
              "bavVendorCountry": "Mexico",
              "bavNumberOfRetries": 3
            },
            "key": "INSTANT_BAV"
        },
        {
            "configuration": {},
            "key": "DYNAMIC_FORMS"
        },
        {
            "configuration": {
                "finishgptCompanyName": "Deploy"
            },
            "key": "FINISH_GPT"
        },
        {
            "configuration": {
              "uploadDocument": false,
              "downloadDocument": true
            },
            "key": "AE_SIGNATURE"
        },
        {
            "configuration": {},
            "key": "UNIVERSAL_IDENTITY"
        },
        {
            "configuration": {},
            "key": "INSTANT_VERIFY"
        },
        {
            "configuration": {},
            "key": "CROSS_DOCUMENT_DATA_MATCH"
        }
    ]
}

Add device fingerprint

POST /omni/add/device-fingerprint

Sends information about device from which endpoint is called. All fields in request are mandatory.

Request Body:

• deviceType: String, mandatory. Platform of device. Possible values: IOS, ANDROID, WEBAPP
• hash: String, mandatory. Hash code of the device fingerprint.
• ip: String, mandatory. IP address of the device.
• data: String, mandatory. Additional data about device.
• osVersion: String, optional. OS verion. If omitteded it is parsed from user agent.
• deviceModel: String, optional. Device model. If omitteded it is parsed from user agent.
• sdkVersion: String, optional. Version of SDK used.

Eg:

{
    "deviceType": "IOS",
    "hash": "42ecaaf4a16e626gt",
    "ip": "0.0.0.0",
    "data": "[{\"key\":\"userAgent\", \"value\":\"Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1\"}]",
    "osVersion": "iOS 14",
    "deviceModel": "iPhone 12",
    "sdkVersion": "1.0",
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Add geolocation

POST /omni/add/geolocation

Send location to store in database, or send coordinates and fetch location and store it. Longitude and latitude fields are mandatory, location field is optional.

Request Body:

• longitude: Float, mandatory. User's geolocation longitude.
• latitude: Float, mandatory. User's geolocation latitude.
• location: String, optional. User's current location.
• mAdminArea: String, optional. State, eg. CA
• mSubAdminArea: String, optional. County, eg. Santa Clara
• mLocality: String, optional. City.
• mSubLocality: String, optional. Neighborhood, common name, eg. Mission District
• mThoroughfare: String, optional. Street name.
• mSubThoroughfare: String, optional. Number.
• mPostalCode: String, optional. Zip code, eg. 95014
• mCountryCode: String, optional. US
• mCountryName: String, optional. United States

Eg:

  {
      "longitude": 22.3456,
      "latitude": 44.56783

  }

Response:

• success: Boolean. Flag indicating request passed successfully.

Add front side of ID

POST /omni/add/front-id/v2?onlyFront=false

This endpoint is used for storing front side of id for further processing. Image quality check is performed during that call. Number of retries is not limited. Once process-id is finished, this endpoint cannot be called for retries.

Note: Front side of id should be uploaded before back-side.

Request parameters:

• onlyFront: Boolean, optional. Flag stating if document is one-sided (like Passport). Default value is false, in case it is not sent.

Request Body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.
• imageUrl: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.

Eg:

{
  "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
}

Response:

• classification: Boolean. If true, server classified image as a front side of an id. If false, server failed to classify image as valid front side of an id or passport and other parameters can be ignored.

• readability: Boolean. If true, server can properly read ID. If false server failed to read some key places of the ID.

• sharpness: Integer. Value can be 0 or 100. Value 100 means it is good quality and the image is sharp, while value 0 represents that image is blurry and bad quality. We recommend to retry capture if value is below 10.

• correctSharpness: Boolean. It's true if the sharpness of the ID meets the requirements.

• glare: Integer. Value can be 0 or 100. Value 100 means it is good quality and no glare or reflections on image, while value 0 represents bad quality of image. We recommend to retry capture if value is below 10.

• correctGlare: Boolean. It's true if the glare of the ID meets the requirements.

• horizontalResolution: Integer. Value is based on the resolution of the cropped photo. Low value means after performing the crop we have a bad quality of image. We recommend to retry capture if value is below 155.

• typeOfId: String. Image was classified as one of the following: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard

• issueYear: Integer. Issue year of the ID. N/A for Brazilian ids.

• countryCode: String. Valid ISO alpha-2 or alpha-3 code of the ID issuing country.

• issueName: String. Description of the ID. Could contain country code, state, type of ID, subtype of ID. N/A for Brazilian ids.

• curpCheck: Boolean. Only for Mexican IDs. Flag stating if curp was properly read.

• sessionStatus: Session Status: Alive, Closed or Deleted.

• failReason: String. Classification fail reason.

Possible values for fail reason:

• UNKNOWN_DOCUMENT_TYPE: document classification failed
• WRONG_DOCUMENT_SIDE: can happen when uploading back side of id when front id is required or the other way around
• WRONG_ONE_SIDED_DOCUMENT: uploading wrong document with only one side
• DOCUMENT_NOT_READABLE: document couldn't be read, probably due to image quality
• UNABLE_TO_ALIGN_DOCUMENT: alignment failed
• ID_TYPE_UNACCEPTABLE: invalid type of id
• UNEXPECTED_ERROR_OCCURRED: unexpected error

Custom error statuses:

• 1003: Face cropping failure

• 4004: Could not find user

• 4019: Face not found

  For more details about error format see errors section.

In case there's some issue when calling the endpoint due to classification failed, an issue such as bad quality, or any of the fail reasons the response will always have the field:

• classification
• failReason
• sharpness
• glare
• horizontalResolution

We recommend considering the call as failed if there's a failReason in the response or if the classification is false.

Whenever the classification is done successfully the fields that will always be present are:

• classification
• sharpness
• glare
• horizontalResolution
• readibility
• typeOfId
• sessionStatus

The remaining fields could be optional depending on the specific type of id and country of origin.

Add back side of ID

POST /omni/add/back-id/v2?retry=false

This endpoint is used for storing back side of id for further processing. Image quality check is performed during that call. Number of retries is not limited.

Once process-id is finished, this endpoint cannot be called for retries.

Note: Front-side of id should be uploaded before back side.

In case of passport or only front sided documents, this endpoint should not be called.

Request parameters:

• retry: Boolean, optional. Flag stating that this is retry attempt for add/back-id

Request Body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Back side of id represented in base64.
• imageUrl: String, mandatory (one of base64Image or imageUrl). Back side of id represented as image url.

Eg:

{
  "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
}

Response:

• classification: Boolean. If true, server classified image as a back side of an id. If false, server failed to classify image as valid back side of an id or passport and other parameters can be ignored.

• readability: Boolean. If true, server can properly read ID. If false server failed to read some key places of the ID.

• sharpness: Integer. Value can be 0 or 100. Value 100 means it is good quality and the image is sharp, while value 0 represents that image is blurry and bad quality. We recommend to retry capture if value is below 10.

• correctSharpness: Boolean. It's true if the sharpness of the ID meets the requirements.

• glare: Integer. Value can be 0 or 100. Value 100 means it is good quality and no glare or reflections on image, while value 0 represents bad quality of image. We recommend to retry capture if value is below 10.

• correctGlare: Boolean. It's true if the glare of the ID meets the requirements.

• horizontalResolution: Integer. Value is based on the resolution of the cropped photo. Low value means after performing the crop we have a bad quality of image. We recommend to retry capture if value is below 155.

• typeOfId: String. Image was classified as one of the following: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard

• issueYear: Integer. Issue year of the ID.

• countryCode: String. Valid ISO alpha-2 or alpha-3 code of the ID issuing country.

• issueName: String. Description of the ID. Could contain country code, state, type of ID, subtype of ID.

• sessionStatus: Session Status: Alive, Closed or Deleted.

• failReason: String. Classification fail reason.

Possible values for fail reason:

• UNKNOWN_DOCUMENT_TYPE: document classification failed
• WRONG_DOCUMENT_SIDE: can happen when uploading back side of id when front id is required or the other way around
• WRONG_ONE_SIDED_DOCUMENT: uploading wrong document with only one side
• DOCUMENT_NOT_READABLE: document couldn't be read, probably due to image quality
• UNABLE_TO_ALIGN_DOCUMENT: alignment failed
• ID_TYPE_UNACCEPTABLE: invalid type of id
• UNEXPECTED_ERROR_OCCURRED: unexpected error

In case there's some issue when calling the endpoint due to classification failed, an issue such as bad quality, or any of the fail reasons the response will always have the field:

• classification
• failReason
• sharpness
• glare
• horizontalResolution

We recommend considering the call as failed if there's a failReason in the response or if the classification is false.

Whenever the classification is done successfully the fields that will always be present are:

• classification
• sharpness
• glare
• horizontalResolution
• readibility
• typeOfId
• sessionStatus

The remaining fields could be optional depending on the specific type of id and country of origin.

Custom error statuses:

• 4004: Could not find user

• 5003: Unsatisfied image size.

For more details about error format see errors section.

Add face/Selfie image

POST /omni/add/face/third-party?imageType=videoSelfie

Uploads selfie image for onboarding session. Response will contain data regarding liveness — if that is the photo of a real person. Number of retries is not limited.

Note: After selfie and front-id are uploaded, endpoint for comparing faces process-face on those two images can be called.

It is required that person is alone on the photo.

Request parameter:

• imageType: String, optional. Possible values: selfie, videoSelfie. Default is selfie.

Request body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Image of user's face represented in base64.

Eg:

{
  "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
}

Response:

• confidence: Float. Value can be 0 or 1. Value 0 means that person on photo is alive. We recommend capturing another photo if value is 1.
• isBright: Boolean. We recommend capturing another photo if value is false.
• hasLenses: Boolean. We recommend capturing another photo if value is true.
• hasFaceMask: Boolean. Checked only if configured in the session flow. We recommend capturing another photo if value is true.
• age: Integer. Age of th person in the photo.
• sessionStatus: SessionStatus: Alive, Closed or Deleted

Custom error statuses:

• 4010: More than one face detected

• 4019: Face not found

• 1001: Face cropping failure

• 1003: Face cropping failure

• 3002: Face cropping failure

• 3004: Face cropping failure

• 3005: Unsatisfied face size

• 3006: Unsatisfied blurriness level

• 3007: Unsatisfied brightness level

• 3008: Unsatisfied image size

• 3009: Unsatisfied image orientation

• 3010: Unsatisfied image compression level

  For more details about error format see errors section.

Add document V2

POST /omni/add/document/v2?type={type}

Upload document image and store data.

Request parameter:

• type: String, mandatory. Possible values: signature, document, medicalDoc, thirdId, contract

  • signature: Upload user's digital signature. This can be later fetched in get images endpoint.
  • document: Upload user's proof of address document. This can be later fetched in get images endpoint.
  • addressStatement: (Legacy) Upload user's proof of address document. Used for backward compatibility. Use type 'document' instead.
  • medicalDoc: Upload user's medical document.
  • thirdId: Upload user's third ID.
  • contract: Upload contract image.

• format: String, optional. Only if type is document. Possible values are image (jpg and png supported) or pdf. Default is image.

• title: String, optional. Only if type is contract. Title of contract.

Request Body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Image of a document represented in base64.
• imageUrl: String, mandatory (one of base64Image or imageUrl). Image as image url.

Eg:

{
  "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
}

Response:

• success: Boolean. Flag indicating request passed successfully.

• additionalInformation: JSON, optional (only if type is contract), with following structure:

  • contractId: String. Id of contract. Used later when adding signature to contract.

• sessionStatus: Session Status: Alive, Closed or Deleted.

Add document

POST /omni/add/document?type={type}

Upload document image and store data.

Request parameter:

• type: String, mandatory. Possible values: signature, document, medicalDoc, thirdId, contract

  • signature: Upload user's digital signature. This can be later fetched in get images endpoint.
  • document: Upload user's proof of address document. This can be later fetched in get images endpoint.
  • addressStatement: (Legacy) Upload user's proof of address document. Used for backward compatibility. Use type 'document' instead.
  • medicalDoc: Upload user's medical document.
  • thirdId: Upload user's third ID.
  • contract: Upload contract image.

• format: String, optional. Only if type is document. Possible values are image (jpg and png supported) or pdf. Default is image.

• title: String, optional. Only if type is contract. Title of contract.

Request Body:

• <binary jpeg/png image>: Binary Image.

Response:

• success: Boolean. Flag indicating request passed successfully.

• additionalInformation: JSON, optional (only if type is contract), with following structure:

  • contractId: String. Id of contract. Used later when adding signature to contract.

• sessionStatus: Session Status: Alive, Closed or Deleted.

Note. Make sure to put the 'Content-Type' header as 'Content-Type: image/jpeg' or 'Content-Type: image/png'.

Add phone

POST /omni/add/phone

Add phone to interview.

Request Body:

• phone: String, mandatory. User's phone number. E.164 number convention.

Eg:

  {
    "phone": "+1111111"
  }

Response:

• success: Boolean. Flag indicating request passed successfully.
• sessionStatus: Session Status: Alive, Closed or Deleted.
• existingCustomer: Boolean. Flag indicating if this user with given phone already exists in the system.

Add email

POST /omni/add/email

Add email to interview.

Request Body:

• email: String, mandatory. User's email. Has to be in valid format.

Eg:

{
  "email": "john.doe@example.com"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Add Barcode

POST /omni/add/barcode

Add raw barcode and parse it to interview.

Request Body:

• rawBarcode: String, mandatory. Barcode in raw format

Eg:

{
  "rawBarcode": "string representation of barcode"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Add Base64 Barcode

POST /omni/add/barcode/v2

Add Base64 barcode and parse it to interview.

Request Body:

• base64Barcode: String, mandatory. Barcode in base64 format.

Eg:

{
  "base64Barcode": "Base64 of barcode"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Add curp

POST /omni/add/curp

Add curp and the validation process result to interview.

Request Body:

• curp: String, optional. User's curp. Has to be in valid format. If it isn't present, then curp value from interview is used.

Eg:

{
  "curp": "COHJ950918HCMVRS09"
}

Response:

• success: Boolean. Flag indicating if CURP validation passed successfully.

• error: Key/Value Structure. If an error occurs while validating the curp with Renapo, details can be found here. See below how to handle errors.

  • tipoError : Determines the type of error. You want to consider combinations of tipoError and codigoError for error handling. See below
  • codigoError : The error subtype. You want to consider combinations of tipoError and codigoError for error handling. See below
  • statusOper : Will always be 'NO EXITOSO' (unsuccessfull), since this was an error
  • message: Detailed error description
  • resultCURPS: The response from Renapo

• sessionStatus: String "Active" or "Closed" or "Deleted"

• renapo_valid: Boolean. Flag indicating if CURP validation passed - tipoError present in response

• curp: String. Curp

• paternal_surname: String. Paternal surname

• mothers_maiden_name: String. Mother maiden name

• names: String. Names

• sex: String - Mujer or Hombre

• birthdate: String. Birth Date in format DD/MM/YYYY

• nationality: String. Nationality

• probation_document: String. Probation Document

• probation_document_data: Key/Value structure. All keys are type of string. Available Key values:

  • anioReg
  • foja
  • tomo
  • libro
  • numActa
  • CRIP
  • numEntidadReg
  • cveMunicipioReg
  • numRegExtranjeros
  • folioCarta
  • cveEntidadNac
  • cveEntidadEmisora

• status_curp: String. Status Curp

• entity_birth: String. Birth State

Error codes:

Errors are divided in 3 groups. You can identify them by the tipoError and codigoError fields inside the error object.

• Group 1: Errors Most likely to be found. Might be due to incorrect curp input in the session.
• Group 2: Connectivity Errors. Most of these should be transient and might require you to retry.
• Group 3: Internal Errors. These should not be found. Please reach out to incode technical support if you find any of these.

Group 1

tipoError	codigoError	Meaning
01	04	CURP previamente dada de baja
01	06	La CURP no se encuentra en la base de datos.
01	09	La llave de la CURP no está bien formada.
01	20	Más de una CURP para estos datos
03	01	[Nombre campo]: No cumple con el formato especificado

For Group 2 and Group 3, you can handle the same meaning for all combinations:

tipoError	codigoError	Meaning	Group
01	13	Error de conexión	Group 2
01	14	Error de conexión	Group 2
01	18	Error de conexión	Group 2
02	01	Error de conexión	Group 2
02	02	Error de conexión	Group 2
02	03	Error de conexión	Group 2
04	01	Error de conexión	Group 2
01	99	Error de conexión	Group 2
02	99	Error de conexión	Group 2
01	01	Error interno	Group 3
01	02	Error interno	Group 3
01	03	Error interno	Group 3
01	05	Error interno	Group 3
01	07	Error interno	Group 3
01	08	Error interno	Group 3
01	10	Error interno	Group 3
01	11	Error interno	Group 3
01	12	Error interno	Group 3
01	15	Error interno	Group 3
01	16	Error interno	Group 3
01	17	Error interno	Group 3
01	19	Error interno	Group 3
03	02	Error interno	Group 3
05	01	Error interno	Group 3

Add curp v2

POST omni/add/curp/v2

Add CURP and validation result based on a person data.

Valid birthDate is dd/mm/yyy. Ex: february 5th 2020 -> 05/02/2020

Valid gender values are "H" (Hombre, male) and "M" (mujer, female).

Valid values for state are the ones listed by renapo in this link: https://es.wikipedia.org/wiki/Plantilla:Abreviaciones_de_los_estados_de_México

Request Body:

Eg:

{
  "name": "abcd",
  "firstLastName": "xyz",
  "secondLastName": "ghj",
  "gender": "M",
  "birthDate": "07/06/1995",
  "state": "CM"
}

Response - Look at Add Curp

Add front side of Second ID

POST /omni/add/front-second-id/v2?onlyFront=false

This endpoint is used for storing front side of second id for further processing. Request parameters, request body and response are the same as for Front side of id

Request parameters:

• onlyFront: Boolean, optional. Flag stating if document is one-sided (like Passport). Default value is false, in case it is not sent.

Request Body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.
• imageUrl: String, mandatory (one of base64Image or imageUrl). Front side of id represented as url

Eg:

{
  "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
}

Response:

• classification: Boolean. If true, server classified image as a front side of an id. If false, server failed to classify image as valid front side of an id or passport and other parameters can be ignored.
• readability: Boolean. If true, server can properly read ID. If false server failed to read some key places of the ID.
• sharpness: Integer. Value can be 0 or 100. Value 100 means it is good quality and the image is sharp, while value 0 represents that image is blurry and bad quality. We recommend to retry capture if value is below 10.
• glare: Integer. Value can be 0 or 100. Value 100 means it is good quality and no glare or reflections on image, while value 0 represents bad quality of image. We recommend to retry capture if value is below 10.
• horizontalResolution: Integer. Value is based on the resolution of the cropped photo. Low value means after performing the crop we have a bad quality of image. We recommend to retry capture if value is below 155.
• shadowConfidence: Float. Value is in range 0 to 1. Value 0 means it is no shadow on the image and image quality is good, while value 1 represents bad quality of image with a lot of shadow. We recommend to retry capture if value is 1.
• typeOfId: String. Image was classified as one of the following: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard

Custom error statuses:

• 4019: Face not found
• 1003: Face cropping failure For more details about error format see errors section.

Add back side of Second ID

POST /omni/add/back-second-id/v2

This endpoint is used for storing back side of second id for further processing. Request parameters, request body and response are the same as for Back Side of Id

Image quality check is performed during that call. Number of retries is not limited. Once id processing is finished, this endpoint cannot be called for retries. Front side of id should be uploaded before back side. In case of passport, this endpoint should not be called.

Request Body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Back side of id represented in base64.
• imageUrl: String, mandatory (one of base64Image or imageUrl). Back side of id as url.

Eg:

{
    "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
    "imageUrl": "http://..."
}

Response:

• classification: Boolean. If true, server classified image as a back side of an id. If false, server failed to classify image as valid back side of an id or passport and other parameters can be ignored.

• readability: Boolean. If true, server can properly read ID. If false server failed to read some key places of the ID.

• sharpness: Integer. Value can be 0 or 100. Value 100 means it is good quality and the image is sharp, while value 0 represents that image is blurry and bad quality. We recommend to retry capture if value is below 10.

• glare: Integer. Value can be 0 or 100. Value 100 means it is good quality and no glare or reflections on image, while value 0 represents bad quality of image. We recommend to retry capture if value is below 10.

• horizontalResolution: Integer. Value is based on the resolution of the cropped photo. Low value means after performing the crop we have a bad quality of image. We recommend to retry capture if value is below 155.

• shadowConfidence: Float. Value is in range 0 to 1. Value 0 means it is no shadow on the image and image quality is good, while value 1 represents bad quality of image with a lot of shadow. We recommend to retry capture if value is 1.

• typeOfId: String. Image was classified as one of the following: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard

Add QR code raw text

POST /omni/add/qr-code-text

Add QR code raw text to interview. It will be saved in custoFields named 'qrCodeText', this fields needs to be present in organization's custom fields schema.

Request Body:

• qrCodeText QR code raw text.

Eg:

{
    "status":"negative"
    "type":"covid-19"
}

Response:

• success Boolean

Fetch ocr data for second id

GET /omni/get/ocr-data-second-id?id=4390u032r

Returns data about user read from the second id.

Request parameters:

• id: String, optional. Id of onboarding for which data are requested. If not present, it will be extracted from token.

Response: Same as response for Fetch-Id-OCR, just for second id.

Send SMS with the link for onboarding

POST /omni/external/send-sms?id=61c3052f00b917001a801321

Used by Admins or Executives to send SMS containing generated onboarding link.

Request parameters:

• id: String, mandatory. Id of onboarding session for which link is being generated.

Request Body:

• clientId: String, mandatory.
• smsText: String, optional. Text to be shown with URL. Needs to have {0} placeholder inside for URL.

Eg:

{
  "clientId": "incode",
  "smsText": "Here is the link to finish onboarding {0}"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Custom error status:

• 4004: Could not find user. For more details about error format see errors section.

Send SMS with One Time Password for onboarding

GET /omni/send/sms-otp

Send SMS with an OTP (One Time Password) code to validate an onboarding. Phone number is obtained from interview data, so phone step it's required.

Response:

• success: Boolean. Flag indicating sms was sent successfully.

Compare/Validate OTP code obtained through SMS for onboarding

GET /omni/compare/sms-otp?code=123456

Send OTP code obtained through SMS to validate an onboarding. Phone number is obtained from interview data, so phone step it's required.

Success will be false if code sent doesn't match.

Response:

• success: Boolean. Flag indicating if otp comparison was successful.

Add name

POST /omni/add/name

This endpoint is used for adding user's name for current onboarding session.

Request Body:

• name:String, mandatory. User's name.

Eg:

{
  "name": "John Doe"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Add custom fields

POST /omni/add/custom-fields

This endpoint is used for adding custom fields to current onboarding session. The key must match one of the keys that are defined for the Organization, and the value must be of the type that is defined for the corresponding key.

Request Body:

• customFields:Map<String, Object>, mandatory.

Eg:

{
  "customFields": {
    "watchlistName": "Name"
  }
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Get custom fields

GET /omni/get/custom-fields

This endpoint is used for fetching custom fields for current session.

Response:

• customFields: Map<String, Object>. Map of custom fields with type that was inserted.

Add front side of Credit Card

POST /omni/add/credit-card-front/v2

This endpoint is used for storing front side of credit card for further processing. Number of retries is not limited.

Request:

• base64Image: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.

• imageUrl: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.

Response:

• success: Boolean. Flag indicating request passed successfully.

Add back side of Credit Card

POST /omni/add/credit-card-back/v2

This endpoint is used for storing back side of credit card for further processing.

Request Body:

• base64Image: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.

• imageUrl: String, mandatory (one of base64Image or imageUrl). Front side of id represented in base64. In case of passport, this should be page with all data about user.

Eg:

{
  "base64Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEB..."
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Process credit card

POST /omni/process/credit-card

Note :This endpoint should be called only after the upload of front-side-card and back-side-card of credit card is over.

Incode validations and ocr parsing are processed during this endpoint. To fetch credit card ocr data call Fetch-creditCard_OCR.

Response:

• success: Boolean. Flag indicating request passed successfully.

Fetch credit card ocr data

GET /omni/get/credit-card-ocr-data

Returns data about user read from credit card.

Request parameters:

• id: String, optional. Id of onboarding for which data are requested. If not present, it will be extracted from token.

Response:

• cardOwner: String, name of the credit card owner.

• cardNumber: String, credit card number.

• cardExpirationDate: String, credit card expiration date UTC timestamp.

• cardCvv String, credit card's cvv number, only available if user uploaded back image of the credit card.

• cardProcessingStatus String, internal information about credit card processing.

Add document id

POST /omni/add/document-id

Upload document identifier. For Mexican id it is cicfrom the back of id.

Request Body:

• documentIdentifier: String, mandatory. Document id.

Eg:

{
  "documentIdentifier": "123456789"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Update — interview

PUT /omni/update?id=123456

If upload of front, back side of id or selfie, was not successful after retries, use this endpoint to specify that additional manual check is needed.

Request parameters:

• id: String, optional. Id of onboarding for which data will be updated. If not present, it will be extracted from token.

Request Body:

• manualIdCheckNeeded: Boolean, optional. If set to true, indicates that manual check is needed for validating id.

• manualSelfieCheckNeeded: Boolean, optional. If set to true, indicates that manual check is needed for validating selfie image.

Note: The following parameters have been deprecated (please use Update editable Ocr Data to update OCR data):

• name: String, optional. Name of the person obtained from ocr can be updated here.

• birthDate: String, optional. Birth date of the person obtained from ocr can be updated here (UTC milliseconds timestamp).

• address: String, optional. Address of the person obtained from ocr can be updated here.

• gender: String, optional. Gender of the person obtained from ocr can be updated here (M/F).

Eg:

{
    "manualIdCheckNeeded": true,
    "manualSelfieCheckNeeded": false,
    "name": "John Smith",
    "birthDate": "-23587200000",
    "address": "221B Baker Street",
    "gender": "M",
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Update editable OCR data

PUT /omni/update/editable-ocr-data

Use this enpoint to update the editable OCR data fetched during onboarding process.

Request Body:

• name: String, optional. Name of the person obtained from ocr can be updated here.

• firstName: String, optional. Firstname of the person obtained from ocr can be updated here.

• lastName: String, optional. Lastname of the person obtained from ocr can be updated here.

• documentNumber: String, optional. Document number of the document can be updated here.

• birthDate: String, optional. Birth date of the person obtained from ocr can be updated here (UTC milliseconds timestamp).

• expireAt: String, optional. Expiration date of the document obtained from ocr can be updated here (UTC milliseconds timestamp).

• address: String, optional. Address of the person obtained from ocr can be updated here.

• gender: String, optional. Gender of the person obtained from ocr can be updated here (M/F).

• email: String, optional. Email of the person can be updated here.

• curp: String, optional. CURP number can be updated here.

Eg:

{
    "name": "John Smith",
    "birthDate": "-23587200000",
    "address": "221B Baker Street",
    "gender": "M",
    "email": "john.doe@email.com",
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Update editable OCR data second Id

PUT /omni/update/editable-ocr-data-second-id

Use this enpoint to update the editable OCR data fetched during onboarding process from the second Id. Request parameters, request body and response are the same as for Update editable Ocr Data

Request Body:

• name: String, optional. Name of the person obtained from ocr can be updated here.

• firstName: String, optional. Firstname of the person obtained from ocr can be updated here.

• lastName: String, optional. Lastname of the person obtained from ocr can be updated here.

• documentNumber: String, optional. Document number of the document can be updated here.

• birthDate: String, optional. Birth date of the person obtained from ocr can be updated here (UTC milliseconds timestamp).

• expireAt: String, optional. Expiration date of the document obtained from ocr can be updated here (UTC milliseconds timestamp).

• address: String, optional. Address of the person obtained from ocr can be updated here.

• gender: String, optional. Gender of the person obtained from ocr can be updated here (M/F).

• email: String, optional. Email of the person can be updated here.

• curp: String, optional. CURP number can be updated here.

Eg:

{
    "name": "John Smith",
    "birthDate": "-23587200000",
    "address": "221B Baker Street",
    "gender": "M",
    "email": "john.doe@email.com",
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Process Id

POST /omni/process/id?queueName=diogenes

Note:This process-id endpoint should be called only after the front-side and back-side is over. And in case of passports or only front sided documents, only front-side should be over.

Incode validations and ocr parsing are processed during this endpoint. To fetch ocr data call Fetch-OCR.

Parameter queueName is needed so it can be determined in wich queue interview should go. Once this is called, user is no longer able to upload ID (front or back side).

Request parameters:

• queueName: String, optional. The name of the queue, user is entering in case conference call will be used. If not set, default queue will be used. Possible values: aristotle, buddha, confucius, diogenes.

Response:

• success: Boolean. Flag indicating request passed successfully.

Process Second Id

POST /omni/process/second-id?queueName=diogenes

Note:This endpoint should be called only after the upload of front-side-secondId and back-side-secondId is over.And in case of passports or only front sided documents, only front-side-secondId should be over.

Incode validations and ocr parsing are processed during this endpoint. To fetch ocr data call Fetch-SecondId_OCR. Parameter queueName is needed so it can be determined in wich queue interview should go. Once this is called, user is no longer able to upload ID (front or back side).

Request parameters:

• queueName: String, optional. The name of the queue, user is entering in case conference call will be used. If not set, default queue will be used. Possible values: aristotle, buddha, confucius, diogenes.

Response:

• success: Boolean. Flag indicating request passed successfully.

External Verification (eKYC)

POST /omni/externalVerification/ekyc

The Know Your Customer (eKYC) endpoint can verify an individual’s full name, phone, email, address, date of birth and tax ID. When making a request use "kyc" in the plugins array.

Request parameters for kyc:

• *plugins: Mandatory string array, must be ["kyc"]
• *firstName: String, The following special characters are not supported: ^±!@£$%&*_+¡€#¢§¶•ªº«<>?\/:;|=.
• *surName: String, The following special characters are not supported: ^±!@£$%&*_+¡€#¢§¶•ªº«<>?\/:;|=.
• houseNo: String
• email: String (US coverage only)
• street: String
• postalCode: String
• *country: String ISO 3166-1 alpha-2 format (eg. US or BR)
• phone: String, Use E.164 format. Hyphens are optional. ie: +14156067603 (US Only)
• state: String
• city: String
• taxId: Brazil CPF, US SSN, China PRC with no spaces or dashes, ie: 123456789
• dateOfBirth: String, ie: YYYY-MM-DD
• nationality Integer or String. (Brazil Only) It is either a string BRAZILIAN, NATURALIZED_BRAZILIAN, FOREIGNER, BRAZILIAN_BORN_ABROAD or an integer ex. 2 or 3
• passportNumber String. (China Only) ie: EB1489444
• dlNumber: alpha numeric string. (US Only) Driver’s license number
• dlState: String. Two letter US State code. ie: CA (US Only)

Note: * indicates a required field in order to make a successful request

~ When fields are provided they will override field values derived from a document scan.

Example US requests

US address example request

{
    "plugins": ["kyc"],
    "firstName": "Jon",
    "surName": "Hasselhoff",
    "street": "101 Beach Highway",
    "postalCode": "90210",
    "state": "CA",
    "city": "Beverly Hills",
    "country": "US"
}

US email example request

{
    "plugins": ["kyc"],
    "firstName": "Jon",
    "surName": "Hasselhoff",
    "email": "david.hasselhoff@email.com"
}

US phone example request

{
    "plugins": ["kyc"], //required field
    "firstName": "Jon",  
    "surName": "Hasselhoff",  
    "phone": "+16504463444"
    "street": "101 Beach Highway",
    "postalCode": "90210",
    "state": "CA",
    "city": "Beverly Hills",
    "country": "US" //required field
}

US taxId example request

{
    "plugins": ["kyc"], //required field
    "firstName": "Jon",  
    "surName": "Hasselhoff",  
    "street": "101 Beach Highway",
    "postalCode": "90210",
    "state": "CA",
    "city": "Beverly Hills",
    "country": "US", //required field
    "taxId": "123456789", //required field
    "dateOfBirth": "1980-06-01"
}

Full eKYC US example request

{
    "plugins": ["kyc"], //required field
    "firstName": "Jon", //required field
    "surName": "Hasselhoff", //required field
    "street": "101 Beach Highway",
    "postalCode": "90210",
    "state": "CA",
    "city": "Beverly Hills",
    "country": "US",
    "phone": "+16504463444",
    "email": "david.hasselhoff@email.com"
    "taxId": "123456789", //required field
    "dateOfBirth": "1980-06-01",
    "dlNumber": "T93875533",
    "dlState": "CA"
}

Full eKYC BR example request

{
    "plugins": ["kyc"], //required field
    "firstName": "Renata", // required field
    "surName": "De Maria Santos", //required field 
    "houseNo" : "121",
    "street" : "Rua Luiz Ferreira Dorta",
    "postalCode": "76535000",
    "country": "BR", //required firled
    "state" : "RJ",
    "city" : "Rio de Janerio",
    "dateOfBirth": "1980-06-01",
        "nationality" : "1",
    "taxId" : "23490843490" //required field
}

Note: middle names can be included in surName field

eKYC response

The response will be a JSON object with the kyc key which will contain an array of results for each test. Each item will have the following schema.

• key: String. The name of test.
• status: String. Whether the test passed.
• reasonCodes: String. This is only populated if there is a reason associated to the status. Reference all 300+ reason codes for KYC responses: doc

US example response

{
    "kyc": [
        {
            "key": "addressRiskLevel",
            "status": "medium"
        },
        {
            "key": "emailLevel",
            "status": "low"
        },
        {
            "key": "phoneLevel",
            "status": "low"
        },
        {
            "key": "taxIdDobMatch",
            "status": "exact"
        },
        {
            "key": "taxIdLevel",
            "status": "low",
        },
        {
            "key": "taxIdMatch",
            "status": "exact"
        },
        {
            "key": "taxIdNameMatch",
            "status": "exact"
        },
        {
            "key": "taxIdStateMatch",
            "status": "exact"
        },
        {
            "key": "overallLevel",
            "status": "low"
        }
    ]
}

US Key	Status	Definition
taxIdMatch	Exact, No Match	Submitted taxId (SSN) has a match or no match associated to the taxId (SSN) in the government database
taxIdLevel	Low, High	The risk level of the submitted taxId associated to the taxId in the government database.
taxIdNameMatch	Exact, Approximate Match, No Match	Submitted name has a match, approximate match, or no match associated to the taxId (SSN) in the government database
taxIdDobMatch	Exact, No Match	Submitted date of birth has a match or no match associated to the taxId (SSN) in the government database
addressRiskLevel	Low, Medium, High	The risk level of the customer provided address
taxIdStateMatch	Exact, No Match	Submitted state has a match or no match associated to the taxId (SSN) in the government database
overallLevel	Low, Medium, High	Overall risk level of the customer provided attributes submitted
emailLevel	Low, Medium, High	The risk level of the customer provided email
phoneLevel	Low, Medium, High	The risk level of the customer provided phone number

BR example response

{
    "kyc": [
        {
            "key": "taxIdNationalityMatch",
            "status": "Exact"
        },
        {
            "key": "taxIdDobMatch",
            "status": "Exact" 
        },
        {
            "key": "taxIdMatch",
            "status": "Exact"
        },
        {
            "key": "taxIdAddressMatch",
            "status": "Approximate Match",
            "reasonCodes": [
                "ASCV"
            ]
        },
        {
            "key": "taxIdNameMatch",
            "status": "Exact"
        },
        {
            "key": "taxIdStateMatch",
            "status": "Exact"
        },
        {
            "key": "taxIdLevel",
            "status": "Low",
            "reasonCodes": [
                "TSR"
            ]
        },
        {
            "key": "overallLevel",
            "status": "Low"
        }
    ]
}

BR Key	Status	Definition
taxIdMatch	Exact, No Match	Submitted taxId (CPF) has a match or no match associated to the taxId (CPF) in the government database
taxIdLevel	Low, High	The risk level of the submitted taxId associated to the taxId in the government database. Low Risk: Verified CPF status is regular. High risk: CPF status is suspended, associated with a deceased holder, pending regularization, canceled due to multiplicity, or canceled by authority
taxIdNameMatch	Exact, Approximate Match, No Match	Submitted name has a match, approximate match, or no match associated to the taxId (CPF) in the government database
taxIdDobMatch	Exact, No Match	Submitted date of birth has a match or no match associated to the taxId (CPF) in the government database
taxIdNationalityMatch	Exact, No Match	Submitted nationality has a match or no match associated to the taxId (CPF) in the government database
taxIdAddressMatch	Exact, Approximate Match, No Match	Submitted address has a match, approximate match, or no match associated to the taxId (CPF) in the government database
taxIdStateMatch	Exact, No Match	Submitted state has a match or no match associated to the taxId (CPF) in the government database
overallLevel	Low, Medium, High	Overall risk level of the attributes submitted associated to the taxId in the government database.

KYC Error Responses:

Please refer to error response section in docs to see conventional HTTP response codes to indicate the success or failure of an API request.

For Brazil, custom 400 error messages if taxId, or country is “ “ or null:

• message: taxId, and country are minimum required fields.

External Verification (eKYB)

POST /omni/externalVerification/ekyb

This endpoint performs an eKYB check for the business specified.

Request:

• plugins: must be ["ekyb"]
• businessName: String. Name of the business.
• street: String. Street name of the business.
• houseNo: String. Building or house number on the street.
• addressLine2: String. Address line 2 of the business. (eg. in US apartment or unit number)
• city: String. City of the business of the business address.
• state: String. State of the business of the business address.
• postalCode: String. postalCode formatted based on per-country postalCode basis
• country: String. Two letter Alpha-2 country code. (eg. US, BR, CN)
• taxId: String. Tax ID of the business (eg. TIN in US, CNPJ in Brazil, Unified Social Credit Code in China).
• uboName: String. Full legal name of Unique Beneficial owners or legal representative to check against list of legal business associations

US KYB Request example:

{
  "plugins": [ "ekyb" ], //required field
  "businessName": "Incode Technologies, Inc.",  //required field
  "street": "Market St",
  "houseNo": "225",
  "addressLine2": "Fl 4",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94105",
  "country": "US",  //required field
  "taxId": "123456789",  //required field
  "uboName": "John Smith"
}

BR KYB Request example:

{
  "plugins" : ["ekyb"], //required field
  "businessName" : "RENATA DISTR. DE SUPLEMENTOS LTDA",
  "street" : "Rua Curupaiti",
  "houseNo" : "225",
  "addressLine2" : "",
  "city" : "Rio De Janeiro",
  "state" : "RJ",
  "postalCode" : "20735320",
  "country" : "BR", //required field
  "taxId" : "41111051548164", //required field
  "uboName" : "Renata Silva Dos Santos"
}

Response:
The response will be a JSON object with the kyb key which will contain an array of results for each test. Each item will have the following schema.

• key: String. The name of test. (All countries)
• status: String. Whether the test ows passed. (only US)
• sub_label: String. Additional info on the status. (All countries)
• message: String. Human readeable description of the status. (only US)

Example US KYB Response:

{
    "kyb": [
        {
            "key": "name",
            "status": "success",
            "sub_label": "Verified",
            "message": "Match identified to the submitted Business Name"
        },
        {
            "key": "tin",
            "status": "success",
            "sub_label": "Verified",
            "message": "Submitted Tax ID is verified in the government database"
        },
        {
            "key": "address_verification",
            "status": "success",
            "sub_label": "Verified",
            "message": "Match identified to the submitted Office Address"
        },
        {
            "key": "address_deliverability",
            "status": "success",
            "sub_label": "Deliverable",
            "message": "The USPS is able to deliver mail to the submitted Office Address"
        },
        {
            "key": "address_property_type",
            "status": "success",
            "sub_label": "Commercial",
            "message": "Submitted Office Address is a Commercial property"
        },
        {
            "key": "ubo_name_match",
            "status": "success",
            "sub_label": "verified"
        }
    ]
}

Status codes for US business name:

status	label	sub_label
Success	Match identified to the submitted Business Name	Verified
Warning	Similar match identified to the submitted Business Name	Similar Match
Failure	Unable to identify a match to the submitted Business Name	Unverified
Failure	We believe the submitted TIN is associated with “name”	Alternate Name

Status codes for US address verification:

status	label	sub_label
Success	Match identified to the submitted Business Name	Verified
Warning	Similar match identified to the submitted Business Name	Similar Match
Failure	Unable to identify a match to the submitted Business Name	Unverified
Failure	We believe the submitted TIN is associated with “name”	Alternate Name

Status codes for US address property type:

status	label	sub_label
Success	Submitted Office Address is a Commercial property	Commercial
Warning	Submitted Office Address is a Residential property	Residential

Status codes for address deliverability:

status	label	sub_label
Success	The USPS is able to deliver mail to the submitted Office Address	Deliverable
Failure	The USPS is unable to deliver mail to the submitted Office Address	Undeliverable

Status codes for Tax ID Verification:

status	label	sub_label
Success	Submitted Tax ID is verified in the government database.	Verified
Failure	Submitted Tax ID is not verified in the government database.	Unverified

Example BR KYB Response:

{
  "kyb": [
    {
      "key": "address_verification",
      "sub_label": "Unverified"
    },
    {
      "key": "name",
      "sub_label": "Verified"
    },
    {
      "key": "tin",
      "sub_label": "Verified"
    },
    {
      "key": "ubo_name_match",
      "sub_label": "Verified"
    }
  ]
}

Key: tin (Note: called tin only because we started with US and continued to expand)
Sub_label codes and definitions for BR CNPJ Tax ID:

Definitions	sub_label
Submitted Tax ID (CNPJ) is verified in the government database.	Verified
Submitted Tax ID (CNPJ) is not verified in the government database.	Unverified

Key: name
Sub_label codes and definitions for BR business name

Definitions	sub_label
Submitted business name is an exact match against the business name associated with the CNPJ in the government database.	Verified
Submitted business name is an approximate match against the business name associated with the CNPJ in the government database.	Approximate Match
Submitted business name is not a match against the business name associated with the CNPJ in the government database.	Unverified

Key: address_verification
Sub_label codes and definitions for BR address:

Definitions	sub_label
Submitted address is an exact match against the address associated with the CNPJ in the government database.	Verified
Submitted address is an approximate match against the address associated with the CNPJ in the government database.	Approximate Match
Submitted address is not a match against the address associated with the CNPJ in the government database.	Unverified

Key: ubo_name_match
Sub_label codes and definitions for BR address:

Definitions	sub_label
Submitted UBO is an exact match against the UBO associated with the CNPJ in the government database.	Verified
Submitted UBO is an approximate match against the UBO associated with the CNPJ in the government database.	Approximate Match
Submitted UBO is not a match against the UBO associated with the CNPJ in the government database.	Unverified

KYB Error Responses:

Please refer to error response section in docs to see conventional HTTP response codes to indicate the success or failure of an API request.

Custom 400 error messages if businessName, taxId, or country is “ “ or null:

• message: businessName, taxId, and country are minimum required fields .

Person Global Watchlist result

POST /omni/watchlist-result

This endpoint calls the global watchlist api (currently only Tier 2), and gets the latest gathered result.

Request:

• firstName: String

• surName: String

• birthYear: Integer Year of birth, if known

• countryCodes: (optional) Array of ISO 3166-1 alpha-2 strings. List Results are filtered by the entity nationality or country of residence.

  • Country code filtering applies to:
    • Entity of type PEP only
    • Entity of type PEP with Adverse Media
    • Entity that has 1 country value or more (only one has to match)
  • Country code filtering does not apply to (i.e. results will still appear regardless of the country filter):
    • Entity on sanction lists will always appear regardless of other status (PEP, Adverse media)
    • Entity that has adverse media mentions only
    • Entity that does not have a country assigned

• watchlistTypes: List

  • One or more of: sanction warning fitness-probity pep pep-class-1 pep-class-2 pep-class-3 pep-class-4
  • If you use classic Adverse Media Taxonomy: adverse-media adverse-media-financial-crime adverse-media-violent-crime adverse-media-sexual-crime adverse-media-terrorism adverse-media-fraud adverse-media-narcotics adverse-media-general
  • If you use FATF-aligned Adverse Media Taxonomy: adverse-media-v2-property adverse-media-v2-financial-aml-cft adverse-media-v2-fraud-linked adverse-media-v2-narcotics-aml-cft adverse-media-v2-violence-aml-cft adverse-media-v2-terrorism adverse-media-v2-cybercrime adverse-media-v2-general-aml-cft adverse-media-v2-regulatory adverse-media-v2-financial-difficulty adverse-media-v2-violence-non-aml-cft adverse-media-v2-other-financial adverse-media-v2-other-serious adverse-media-v2-other-minor

• fuzziness: Float Determines how closely the returned results must match the supplied name. Ranges from 0.0 to 1.0. Default is 1.0 (loose matching).

• subscribe: Boolean Subsribes to updates on the watchlists to receive notification for updates on the search.

• search_profile: String Search profile set for the client to use specify what sources they will be searching against.

Updated global watchlist result

GET /omni/updated-watchlist-result?id={{interviewId}}&ref={{refId}}

This endpoint gets the latest result for a previous search created with watch-list with refId from it's response, or gathered from an update notification or with interviewId that the search is associated with.

Add custom watchlist entry

POST /omni/add/watchlist/single-record

Note: Requires admin login token refere api -Admin-Login

Request Body:

• name: String, optional. Name of person that is being uploaded to Watchlist
• birthDate: String, optional. Birthdate (timestamp) of person that is being uploaded to Watchlist
• idNumber: String, optional, unique. Id number of person that is being uploaded to Watchlist
• email: String, optional, unique. Email of person that is being uploaded to Watchlist
• phone: String, optional, unique. Phone of person that is being uploaded to Watchlist
• imageBase64: String, optional, unique. Base64 representation of face image of person that is being uploaded to Watchlist
• frontIdBase64: String, optional. Base64 representation of front side of document image that is being processed to gather OCR data and uploaded to Watchlist
• backIdBase64: String, optional. Base64 representation of back side of document image that is being processed to gather OCR data and uploaded to Watchlist
• watchlistType: String, optional. Defines type of Watchlist to use: WHITELIST, BLACKLIST (case senstive)
• recordExpiresAt: String, optional. Date (timestamp) until the watchlist entry is active. When searched after this date, score of watchlist match will be 0.

Note: Fields marked with unique are used to perform search in watchlist database. At least one of these must be supplied.

Response:

• success: Boolean. Flag indicating request passed successfully.

Delete custom watchlist entry

POST /omni/delete/watchlist/single-record

Note: Requires admin login token refere api - Admin-Login.

Request Body:

• id: String, mandatory. Id of entry in watchlist database.

Response:

• success: Boolean. Flag indicating request passed successfully.

Process custom watchlist

POST /omni/process/watchlist?id=exampleSessionId

Request parameters:

• id: String, optional. Id of onboarding session. If not present, it will be extracted from token.

This endpoint fetches data (photo, email, phone, document number) from onboarding session and tries to find a match in custom watchlist database. If a match on the watchlist is found, then the score influence is calculated based on the number of matched fields.

Response:

• success: Boolean. Flag indicating request passed successfully.
• match: Boolean. Flag indicating if a match in the watchlist has been found.

Process face

POST /omni/process/face?imageType=videoSelfie

Note: This endpoint should be called only after selfie and front-id both are over.

It is validating user's selfie against photo from ID (1:1 recognition). Also, this call validates if user already exists in the system (1:N recognition).

It is highly recommended that before calling this process-face endpoint, one should first finish following endpoints- add-front, add-back(not required in case of passports), process-id and add-selfie in order to get complete result view based on id verification, face recognition and liveness.

Request parameter:

• imageType: String, optional. Possible values: selfie, videoSelfie. Default is selfie.

Response:

• confidence: Float. Value can be 0 or 1. Value 0 means that selfie doesn't match face photo from ID.
• existingUser: Boolean. Flag indicating if this user already exists in the system.
• existingInterviewId: String, optional. Session id where user is approved previously (existingUser=true).
• nameMatched: Boolean, optional. In case user is approved previously (existingUser=true), flag indicating if names are matching.
• existingExternalId: String, optional. In case the session does have an externalId which can be assigned at start call.

Process face vs second id

POST /omni/process/face-vs-second-id?imageType=videoSelfie

Note: This endpoint should be called only after selfie and front-second-id both are over.

It is validating user's selfie against photo from ID (1:1 recognition). Also, this call validates if user already exists in the system (1:N recognition).

It is highly recommended that before calling this process-face endpoint, one should first finish following endpoints- add-front-secondId, add-back-secondId(not required in case of passports), process-secondId and add-selfie in order to get complete result view based on id verification, face recognition and liveness.

Request parameter:

• imageType: String, optional. Possible values: selfie, videoSelfie. Default is selfie.

Response:

• confidence: Float. Value can be 0 or 1. Value 0 means that selfie doesn't match face photo from ID.
• existingUser: Boolean. Flag indicating if this user already exists in the system.

Process address

POST /omni/process/address

Note: This endpoint should be called only after process-id and add-document both are uploaded successfully.

Address from id is compared with address from address statement, and confidence is stored. Result will be visible on conference.

Response:

• success: Boolean. Flag indicating request passed successfully.

Process government validation

POST /omni/process/government-validation

This endpoint reads the country code from the interview which can be set at the moment of calling the start endpoint or is updated based on the processed id. Request body can optionally contain data from id in JSON. If omitted, data from scanned ID is read.

Specific details on the countries supported and the request data needed can be found in the Government Validation section

Process payment proof

Note: This endpoint should be called once the Qr-code is executed.

It will fetch info from add qr code text call and validate payment proof fields rfc issuer, rfc receiver and fiscal invoice and return response.

It will notify Organization's organizationPaymentProofApiUrl with POST request and CFDI data as payload: CFDI data:

• rfcIssuer
• issuerName
• rfcReceiver
• receiverName
• fiscalInvoice
• issueDate
• certificationDate
• rfcPac
• totalCfd
• voucherEffect
• cfdiStatus
• cancellationStatus
• cancellationDate
• validationCode
• messageCode
• status
• errorMessage

Request parameters: None

Response:

• success: Boolean. Flag indicating request status (true, false).
• requestId: String, Id associated with request

Process IMSS

POST /omni/process/imss

Trigger fetching of work history for curp. It will save WorkHistory entity in db when received and also it will notify webhook specified in Organization.organizationWorkHistoryApiUrl by calling POST request with workhistory data:

WorkHistory request data:

• requestId: String. clientRequestId

• errorMessage: String. error message, if exists workHistory is empty

• workHistory: List

  • curp: String CURP associated with interview
  • laborHistoryList: List of labor history records
  • companyName: String
  • state: String
  • startingDate: String
  • endingDate: String
  • baseSalary: String
  • companyIMSSId: String

Request parameters:

• curp String (optional) if not specified it will use one from interview

Eg:

{
"curp":"",
}

Response:

• success: Boolean. Flag indicating request status (true, false).

Process Antifraud

GET /omni/process/antifraud

Important: This endpoint should be called only after process-id and process-face both are over.

Endpoint gives ability to compare current interview with existing interviews and customers and detect anomalies than could be signs of fraud.

Important: the result of the call affects the total score.

Response:

• result: String. Overall result: FAILED, PASSED, NOT_EXECUTED(Returned if the antifraud module is not connected in flow or workflow)
• stepName: String. Failed step FuzzyFieldAntifraudExecutor, IdFaceAntifraudExecutor, SelfieFaceAntifraudExecutor, on which we found fraud signal.

Resolve Antifraud result

PUT /omni/resolve/antifraud

An endpoint that allows you to resolve session that mistakenly prevent you from passing the antifraud check (for example, with a fuzzy ID image). In future antifraud checks, this session will not affect the result.

Request parameter:

• interviewId: String. Session id to be allowed for future antifraud checks.
• reason: String, optional. Reason resolving result.

Response:

• success: Boolean. Flag indicating request passed successfully.

Fetch IMSS, labor history

GET /omni/get/imss

Fetch response from numbarium regarding labor history. Interview id is extracted from jwt token.

Response:

• interviewId
• requestId
• operation Type of operation that is requested, paymentProof or laborHistory
• dataJson Response containing labor history

Eg:

    {
    "interviewId": "61c07475a17c3a0015fec7b0",
    "requestId": "reqId123",
    "operation": "laborHistory",
    "dataJson": "{\"rfcIssuer\":\"refIssuer\",\"issuerName\":\"issuerName\",\"rfcReceiver\":\"rfcReceiver\",\"receiverName\":\"Carlos Martinez\",\"fiscalInvoice\":\"A6444642E-7AE5-40AF-BA-BA3E5FCD\",\"issueDate\":\"2021-09-24T12:37:18\",\"certificationDate\":\"2021-09-24T12:37:26\",\"rfcPac\":\"MAS0513247C5\",\"totalCfdi\":\"$2,750.20\",\"voucherEffect\":\"Nómina\",\"cancellationStatus\":\"Cancelable sin aceptación\",\"validationCode\":\"fd169318.579498\",\"status\":\"OK\"}"
    }

Update manual review

PUT /omni/manual-review?interviewId=123456

Can be used to set an interview as 'needs manual review', 'approved by manual review' or 'rejected by manual review'. In case manualReviewStatus field in request is set to APPROVED or REJECTED, notification to client side is sent for onboarding status change - see notify-status-changed for more details

Request parameters:

• interviewId: String, optional. Id of onboarding for which data will be updated. If not present, it will be extracted from token.

Request Body:

• manualReviewStatus: String (enum), mandatory. Can either be REQUIRED | APPROVED | REJECTED
• newReason: String, optional. Intended to be use when setting manualReviewStatus as required, it will be added to the list of reasons why a session was flagged as needs manual review.

Eg:

{
  "manualReviewStatus": "REQUIRED",
  "newReason": "Failed to capture id after 3 attempts"
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Approve customer

POST /omni/process/approve?interviewId=5ea568d30117kdjdh76824

Approve customer for omnichannel program. Parameter interviewId is required. Body is optional and used for auto approve when only specific features should be approved. It is not possible to approve twice the same user (e.g. with the same phone number).

Request parameters:

• interviewId: String, required. Session id for which approval is requested.

Request Body:

• approveComponents: String array, optional. Contains list of features that should be validated during approval. Supported features: liveness, faceRecognition, id, governmentValidation.

Response:

• success: Boolean. Flag indicating whether approval passed successfully or not.
• uuid: String. I'd of newly created customer if approval was successful.
• token: String. Access token to be used for newly created customer, in case approval was successful.

Custom error status:

• 4006: User with given phonen already exists. For more details about error format see errors section.

Fetch random questions and answers for video selfie

GET /omni/get/questionAndAnswer?numberOfQuestions=3&returnVoiceConsentQuestion=true

Fetch a number random questions and answers for video selfie for given apiKey. If there are no defined QA pairs for the apiKey, a random QA pair is returned from the default set.

Request parameters:

• numberOfQuestions: Number, mandatory. Number of questions to be returned to client.
• returnVoiceConsentQuestion: Boolean, optional. Flag stating if voice consent question should be included in response. If omittid it would be defaulted to true

Response: List of questions and answers with and the pair's ids.

• question: String. Random question to be shown in video selfie.
• answer: String. Corresponding answer to the question.
• id: String. ID of the given Question-Answer pair.

Get upload URL for video recording

GET /omni/generateVideoSelfieUrl?type=videoSelfie

Get URL for uploading video recording of either video selfie or onboarding session. This is temporary pre-signed url, that expires in 1 hour.

Response:

• url: String. URL where recording should be uploaded.

Get download URL of video recording

POST /omni/generateVideoSelfieDownloadUrl?interviewId=614e02c3c8957600149b6b0b

Get URL for downloading video recording of video selfie. This is temporary pre-signed url, that expires in 1 hour.

Request parameters:

• interviewId: String, optional. Session ID for which url is generated. In case not set, interviewId will be determined from token from header.

Response:

• url: String. URL of recorded video.

Compare videoselfie against ID

POST /omni/videoselfie/compare-id

This endpoint is used to compare frame from videoselfie against ID. It classifies ID from videoselfie frame and also does face recognition from videoselfie frame and matches it with face from ID.

Request:

• body: byte array, mandatory: image (frame extracted from videoselfie)

Response:

• typeOfId: String. Type of ID.
• idTypeMatched: Boolean. Type of ID matched.
• issueYear: Integer. Issue year of ID.
• faceRecognitionConfidence: Float. Confidence of face match, either 0 (no match) or 1 (match).

Custom error statuses:

• 1003: Face cropping failure.

• 4019: Face not found.

• 4020: Image to compare not found.

• 5003: Unsatisfied image size.

• 5004: Document alignment failed.

• 5005: Document not found.

  For more details about error format see errors section.

Compare videoselfie against ID v2

POST /omni/videoselfie/compare-id/v2

This endpoint is used to compare frame from videoselfie against ID. It classifies ID from videoselfie frame and also does face recognition from videoselfie frame and matches it with face from ID.

Request:

• base64Image: String, mandatory. Base64 string representation of the image. (frame extracted from videoselfie)

Response:

• typeOfId: String. Type of ID.
• idTypeMatched: Boolean. Type of ID matched.
• issueYear: Integer. Issue year of ID.
• faceRecognitionConfidence: Float. Confidence of face match, either 0 (no match) or 1 (match).

Custom error statuses:

• 1003: Face cropping failure.

• 4019: Face not found.

• 4020: Image to compare not found.

• 5003: Unsatisfied image size.

• 5004: Document alignment failed.

• 5005: Document not found.

  For more details about error format see errors section.

Compare OCR from videoselfie against OCR from ID

POST /omni/videoselfie/compare-ocr

This endpoint is used to compare OCR from videoselefie frame against OCR from ID.

Request:

• body: byte array, mandatory: image (frame extracted from videoselfie)

Response:

• success: Boolean. Flag indicating that OCR from videoselfie matches OCR from ID.

Custom error statuses:

• 5003: Unsatisfied image size.

• 5004: Document alignment failed.

• 5005: Document not found.

  For more details about error format see errors section.

Compare OCR from videoselfie against OCR from ID v2

POST /omni/videoselfie/compare-ocr/v2

This endpoint is used to compare OCR from videoselefie frame against OCR from ID.

Request:

• base64Image: String, mandatory. Base64 string representation of the image. (frame extracted from videoselfie)

Response:

• success: Boolean. Flag indicating that OCR from videoselfie matches OCR from ID.

Custom error statuses:

• 5003: Unsatisfied image size.

• 5004: Document alignment failed.

• 5005: Document not found.

  For more details about error format see errors section.

Fetch onboarding status

GET /omni/get/onboarding/status?id=5e9f3e3e1d0ef70011173fce

Check the status of onboarding session.

Request parameters:

• id: String, optional. Represents interview id for which status is requested. If it is not present it will be read from token.

Response:

• onboardingStatus: String. A flag indicating current status of onboarding session. Possible values:
  • ID_VALIDATION_FINISHED - User finished with capturing of ID,
  • POST_PROCESSING_FINISHED - ID postprocessing finished on server,
  • FACE_VALIDATION_FINISHED - User finished with selfie capture,
  • ONBOARDING_FINISHED - User finished onboarding process,
  • MANUAL_REVIEW_APPROVED - Session that was in Needs Review state, manually approved by Executive,
  • MANUAL_REVIEW_REJECTED - Session that was in Needs Review state, manually rejected by Executive,
  • UNKNOWN - Unable to determine status of onboarding session - user still didn't start onboarding or user is still in the process of capturing ID.

Fetch onboarding url

GET /omni/onboarding-url?clientId=CLIENT_ID

Fetch onboarding URL generated for specific user and specific flow. Only supply a clientId, if a redirect to mobile feature has been added to the flow configuration and SMS and desktop onboarding is needed. Alternatively, if only a QR code is needed, it's recommended to supply clientId, components and tag parameters. The alternative will return a highly performant app launcher screen when redirect to mobile has been enabled.

Request parameters:

• clientId: String, mandatory. Client's id.
• components: URL encode String Array of accepted string values, optional.
  • accepted string values are 'qr'
• tag: String , optional.
  • accepted string values are 'payments', 'verification'

Response:

• url: String. Actual url.

Fetch processing status

GET /omni/get/postprocess/isfinished

Check if session processing is done.

Response:

• finished: Boolean. A flag stating if processing is done or not.

Fetch all passed onboardings for the same person

GET /omni/identity/{customerId}/sessions

Get all passed onboardings for the same person.

Response:

• **[ {interviewId: 'someId', ...}, {interviewId: 'someId', ...}, ... ]

**Note: Requires admin login token refere api - Admin-Login

Fetch device info

GET /omni/get/device-info?id=5e9f3e3e1d0ef70011173fce&returnData=true

Fetch information about device user was using during onboarding.

Request parameters:

• id: String, optional. Represents interview id for which device data are requested. If it is not present it will be read from token.
• returnData: Boolean, optional. If it is set to true, string representation of map which contains all data that enters the hash will be returned.

Response:

• ipAddress: String, Up to 15 characters. Ip address of the device from which onboarding is being executed.
• hash: String, Up to 64 characters. Hash is generated out of data specific to user device and browser: userAgent, webdriver, language, colorDepth, deviceMemory, hardwareConcurrency, screenResolution, availableScreenResolution, timezoneOffset, timezone, sessionStorage, localStorage, indexedDb, cpuClass, platform, plugins, canvas, webgl, webglVendorAndRenderer, adBlock, hasLiedLanguages, hasLiedResolution, hasLiedOs, hasLiedBrowser, touchSupport, fonts, audio.
• deviceType: String. Device type can be WEBAPP, IOS or ANDROID.
• longitude: Float. User's geolocation longitude.
• latitude: Float. User's geolocation latitude.
• location: String. User's location at the moment of onboarding process.
• mAdminArea: String, optional. State, eg. CA
• mSubAdminArea: String, optional. County, eg. Santa Clara
• mLocality: String, optional. City.
• mSubLocality: String, optional. Neighborhood, common name, eg. Mission District
• mThoroughfare: String, optional. Street name.
• mSubThoroughfare: String, optional. Number.
• mPostalCode: String, optional. Zip code, eg. 95014
• mCountryCode: String, optional. US
• mCountryName: String, optional. United States

Fetch scores

GET /omni/get/score?id=5e9f3e3e1d0ef70011173fce

Get id validation, liveness and face recognition results for given interviewId.

Request parameters:

• id: String, optional. Id of onboarding for which score is requests. If not present, it will be extracted from token.

Response: Score payload is composed of subsections. Scores are calculated once onboarding is completed.

• idValidation: Id validation of its overall score and two lists of executed tests and checks.

  • photoSecurityAndQuality: List of tests. Each test contains:
    • value: String
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN", "MANUAL"
    • 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"
  • idSpecific: List of tests. Each test contains:
    • value: String
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • 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", "illiteracyCheck", "birthDateCrosscheck", "expirationDateCrosscheck", "sexCrosscheck", "fullNameCrosscheck", "emissionNumberCrosscheck", "documentNumberCrosscheck", "personalNumberCrosscheck", "2DBarcodeContent", "barcode2DDetected", "documentTypeSideCrosscheck", "dD/ReferenceNumberCrosscheck", "underageCheck"
  • customFields: List of custom field validations (only if custom fields are used in the onboarding process). Each validation contains:
    • value: String
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • key: String. Possible keys: "firstNameMatch", "lastNameMatch"
  • appliedRule: Specific rule from rule engine for idValidation:
    • name: String. Name of the rule.
    • expression: String. A logical expression of the rule.
    • ruleType: String. "idValidation"
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
  • overall: see below. Composite result for id validation score.

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

  • overall: see below. Result for antifraud score.

• secondIdValidation: Same as idValidation only applicable if onboarding is configured to capture a second id.

• liveness:

  • livenessScore: Shows confidence that person is real.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • value: String. From 0 to 100
  • photoQuality:
    • value: String.
  • overall: see below. Composite result for liveness score.

• faceRecognition:

  • existingUser: Boolean. Flag indicating if a user is already enrolled.
  • existingInterviewId: String. Session ID, in case the user, is approved in another session.
  • existingExternalId: String. External ID, in case the user, is approved in another session.
  • maskCheck: Shows info if the user was wearing a mask during selfie capture.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • value: String. From 0 to 100.
  • lensesCheck: Shows info if the user was wearing lenses during selfie capture.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
  • faceBrightness: Shows status and level of brightness during selfie capture.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • value: String. Shows the level of brightness during selfie capture.
  • nameMatch: Shows if the name matches the previously used (only in case the user is already approved in another session)
    • status: String. Status can have one of the following values: "OK", "FAIL"
  • appliedRule: Specific rule from rule engine for faceValidation:
    • name: String. Name of the rule.
    • expression: String. A logical expression of the rule.
    • ruleType: String. "faceValidation"
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
  • overall: see below. Shows how much face from ID matches the selfie.

• faceRecognitionSecondId: Same as faceRecognition only applicable if onboarding is configured to capture a second id.

• videoConference:

  • speechTranscript: String. Extracted text from speech, during video recording.
  • speechRecognition: This shows how much the recognized speech matches the expected result.
    • status: String. Status can have one of the following values: "OK", "FAIL"
    • value: String. From 0 to 100.
  • videoSelfieLiveness: Shows liveness confidence that the person is real based on video conference.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • value: String. From 0 to 100.
  • videoSelfieFaceRecognition: Shows how much face from id matches the video conference capture.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"
    • value: String. From 0 to 100.
  • score: Overall video recording score.
    • status: String. Status can have one of the following values: "OK", "FAIL"
    • value: String, optional. Only in case status is "FAIL", value is "0.0".

• governmentValidation:

  • recognitionConfidence: Optional. Only present in case face validation is performed as a part of government check.
    • status: String. Status can have one of the following values: "OK", "WARN", "FAIL"
    • value: String. From 0 to 100
  • validationStatus:
    • status: String. Status can have one of the following values: "OK", "FAIL", "UNKNOWN"
    • value: String. String representation of integer status code. Possible values: -1, 0-14, 99.
    • 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
  • ocrValidation: List of value, status, key objects. Each test contains:
    • value: String. Could be true or false
    • status: String. Status can have one of the following values: "OK", "FAIL", "UNKNOWN"
    • key: String. Not all off the following keys are always present: issueDate firstName, maternalLastName, paternalLastName, ocr, personalId, electorsKey, emissionNumber, registrationDate
  • ocrValidationOverall: Composite result for ocrValidation score.
    • status: String. Status can have one of the following values: "OK", "FAIL"
    • value: String. From 0 to 100
  • overall: Composite result for government validation score.
    • status: String. Status can have one of the following values: "OK", "FAIL", "UNKNOWN"
    • value: String. From 0 to 100

• externalVerification

  • nameAddressCorrelation: Float. Shows the score of correlation between the name and address based on external sources.
  • nameEmailCorrelation: Float. Shows the score of correlation between the name and email based on external sources.
  • namePhoneCorrelation: Float. Shows the score of correlation between the name and phone based on external sources.
  • addressRisk: Float. Shows the risk of address being a fraud based on external sources.
  • emailRisk: Float. Shows the risk of the email is a fraud based on external sources.
  • phoneRisk: Float. Shows the risk of the phone is a fraud based on external sources.

• curpVerification (only for Mex documents, in case curp validation was performed)

  • success: Boolean. Flag indicating if the process finished successfully.
  • curp: String. CURP value.
  • sex: String. Gender
  • nationality: String. Nationality.
  • result: String. Result: success or error message.
  • renapo_valid: Boolean. Flag indicating if the process finished successfully.
  • names: String. Given names.
  • paternal_surname: String. Paternal surname.
  • mothers_maiden_name: String. Mother's maiden name.
  • birthdate: String. Birthdate in format "DD/MM/YYYY",
  • entity_birth: String.
  • probation_document: String.
  • status_curp: String.
  • probation_document_data:
    • foja: String.
    • numEntidadReg: String.
    • libro: String.
    • NumRegExtranjeros: String.
    • cveEntidadNac: String.
    • numActa: String.
    • CRIP: String.
    • tomo: String.
    • cveEntidadEmisora: String.
    • anioReg: String.
    • cveMunicipioReg: String.
    • FolioCarta: String.

• ineScrapingValidation: (only for Mex documents in case INE scraping was performed)

  • scrapingStatus: String. Scraping status. Possible values: IN_PROGRESS, FINISHED, ERROR
  • success: Boolean. Flag indicating if the process finished successfully.
  • result: String. Result: success or error.
  • screenshotUrl: String.
  • cic: String. Cic value.
  • claveElector: String. Clave de elector.
  • numeroEmision: String. Emission number.
  • ocr: String. Ocr number.
  • anioRegistro: String. Registration year.
  • anioEmision: String. Emission year.

• idOcrConfidence: Confidence level for read ocr data from ID.

  • overallConfidence:
    • status: String. Status can have one of the following values: "OK", "FAIL"
    • value: String. From 0 to 100

• idOcrConfidenceSecondId: Same as idOcrConfidence only applicable if onboarding is configured to capture a second id.

• retryInfo: Info about failed onboarding attempts (only if 'Onboarding flow attempts' > 0 in ID Capture module):

  • failedAttemptsCounter: Object with counter of failed attempts per step
  • stepsToRetry: Array of stepts retried. Possible values in array: frontId, backId, selfie, poa, governmentValidation

• appliedRule: Specific rule from rule engine for total:

  • name: String
  • expression: String
  • ruleType: String. "total"
  • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN"

• needsReviewReason: String, optional. In case the overall score status is MANUAL (Needs Review), returns reason. Possible values MANUAL_CAPTURE, RULE_APPLIED, OLD_ID

• incodeWatchlistScore: Incode watchlist score.

  • watchlistScore:
    • value: String. A number that represents a score.
  • dataMatches: Array of fields used as data matching. Possible values: face, birthDate, name, idNumber, phone, email

• overall: Composite result for previous sections.

  • status: String. Status can have one of the following values: "OK", "WARN", "FAIL", "UNKNOWN", "MANUAL"," MANUAL_OK",,"MANUAL_FAIL","MANUAL_PENDING"
  • value: String. From 0 to 100

Fetch images

POST /omni/get/images?id=4390u032r

Returns images for user. Parameter id is optional.

Request parameters:

• id: String, optional. Id of onboarding for which images are requested. If not present, it will be extracted from token.

Request Body:

• images: String array, mandatory. Image types that are requested. It is strongly advised to fetch one image at the time, as response payload can be potentially big. Possible image types: selfie, videoSelfie, croppedFace, croppedIDFace, document, signature, fullFrameFrontID, fullFrameBackID, croppedFrontID, croppedBackID, confSelfie, confFrontID, confBackID, confPoa, addressStatement, medicalDoc, thirdId, contract, signedContract, videoSelfieCompareID, videoSelfieCompareOcr, otherDocument1, otherDocument2

Eg:

{
  "images": [
    "croppedFace",
    "croppedFrontID",
    "signatures"
  ]
}

Response: For each requested image type, response contains line in format:

• {imageType}: String (base64). Base64 representation of image. Additionally, if signature image is requested, response will contain an array of all signatures.

Fetch image links

POST /omni/get/images/v2?id=4390u032r

Returns images temporary links for requested images. Links are valid for one hour. Parameter id is optional.

Request parameters:

• id: String, optional. Id of onboarding for which images are requested. If not present, it will be extracted from token.

Request Body:

• images: String array, mandatory. Image types that are requested.
  Possible image types: selfie, videoSelfie, croppedFace, croppedIDFace, document, signature, fullFrameFrontID, fullFrameBackID, croppedFrontID, croppedBackID, confSelfie, confFrontID, confBackID, confPoa, addressStatement, medicalTest, secondId, thirdId, contract, signedContract

Eg:

{
    "images": ["croppedFace", "croppedFrontID",...]
}

Response: For each requested image type, response contains line in format:

• {imageType}: String (base64). Base64 representation of image. Additionally, if signature image is requested, response will contain an array of all signatures.

Fetch images second id

POST /omni/get/images-second-id?id=4390u032r

Returns images for user. Parameter id is optional.

Request parameters:

• id: String, optional. Id of onboarding for which images are requested. If not present, it will be extracted from token.

Request Body:

• images: String array, mandatory. Image types that are requested. It is strongly advised to fetch one image at the time, as response payload can be potentially big. Possible image types: selfie, videoSelfie, croppedFace, croppedIDFace, document, signature, fullFrameFrontID, fullFrameBackID, croppedFrontID, croppedBackID, confSelfie, confFrontID, confBackID, confPoa, addressStatement, medicalTest, secondId, thirdId, contract, signedContract

Eg:

{
  "images": [
    "croppedFace",
    "croppedFrontID",
    "signatures"
  ]
}

Response: For each requested image type, response contains line in format:

• {imageType}: String (base64). Base64 representation of image. Additionally, if signature image is requested, response will contain an array of all signatures.

Fetch concatenated images

POST /omni/get/concatenated-images?id=4390u032r

Concatenates requested images from user. Resulting image keep the largest width of the requested images and preserves the order. Parameter id is optional.

Request parameters:

• id: String, optional. Id of onboarding for which images are requested. If not present, it will be extracted from token.

Request Body:

• images: String array, mandatory. Image types that are requested. Requested images are limited to crops only, because full frames can potentially lead to big payload in response. Possible image types: selfie, videoSelfie, croppedFace, croppedIDFace, document, signature, croppedFrontID, croppedBackID, confSelfie, confFrontID, confBackID, confPoa, addressStatement, medicalDoc, videoSelfieCompareID, videoSelfieCompareOcr, otherDocument1, otherDocument2

Eg:

{
  "images": [
    "croppedBackID",
    "croppedFrontID"
  ]
}

Response: For each requested image type, response contains line in format:

• {imageType}: String (base64). Base64 representation of image. Additionally, if signature image is requested, response will contain an array of all signatures.

Fetch ocr data

GET /omni/get/ocr-data?id=4390u032r

Returns data about user read from id and address statement.

Request parameters:

• id: String, optional. Id of onboarding for which data are requested. If not present, it will be extracted from token.

Response:

• name: Structure which contains:

  • fullName: String.
  • firstName: String.
  • paternalLastName: String.
  • maternalLastName: String. Optional.
  • givenName: String.
  • middleName: String. Optional.
  • nameSuffix: String. Optional.
  • machineReadableFullName: String. Optional. Full name from Barcode or MRZ.
  • givenNameMrz: String. Optional.
  • lastNameMrz: String. Optional.

• address: String. Optional. Address as read from id. Address can have one, two or three lines. In case of multiple lines, they are separated by \n.

• addressFields: Structure with following fields:

  • street: String. Optional. Street line in the way it is read from address string.
  • colony: String. Optional. Colony line the way it is read from address string. (Not applicable for all countries)
  • postalCode: String. Optional. Postal code in the way it is read from address string.
  • city: String. Optional. City in the way it is read from address string.
  • state: String. Optional. State in the way it is read from address string.

• fullAddress : Boolean. This field is set to true if address from id is full (has three lines) or not.

• invalidAddress : Boolean. Optional. This field cheks for a valid street, numeric postal code with 5 digits, and tha both colony and city have values. (Only checked for Mexican IDs)

• checkedAddress: String. Optional. Address as obtained after processing with geocoder geolocation api.

• checkedAddressBean: Address object obtained after processing with geocoder geolocation api. Optional. Structure with following fields:

  • street: String. Optional. Street line in the way it is read from address string.
  • colony: String. Optional. Colony line the way it is read from address string. (Not applicable for all countries)
  • postalCode: String. Optional. Postal code in the way it is read from address string.
  • city: String. Optional. City in the way it is read from address string.
  • state: String. Optional. State in the way it is read from address string.
  • label: String. Optional. Full address label.

• exteriorNumber: String. Optional. Exterior street number.

• interiorNumber: String. Optional. Interior street number.

• addressFromStatement: String. Optional. Address as read from address statement. Lines are separated by \n.

• addressFieldsFromStatement: Structure with following fields:

  • street: String. Optional. Street line in the way it is read from address string.
  • colony: String. Optional. Colony line the way it is read from address string. (Not applicable for all countries)
  • postalCode: String. Optional. Postal code in the way it is read from address string.
  • city: String. Optional. City in the way it is read from address string.
  • state: String. Optional. State in the way it is read from address string.

• invalidAddressFromStatement : Boolean. This field cheks for a valid street, numeric postal code with 5 digits, and tha both colony and city have values. (Only checked for Mexican POA)

• addressStatementEmissionDate: Long. Optional. Issue date of address statement. The value is presented in UTC milliseconds.

• documentType: String. Optional. Type of address statement document. Possible values:

  • Mexico: liverpool, citibanamex, cfe, telcel, izzi, axtel, telmex, oapas, sacmex, opdm, naturgy, drenaje, totalplay, dhc, att, cea, smapa, megacable, jmas, amicsa, caev
  • Bolivia: cre
  • Uruguay: ute
  • Unknown document: otherPoa

• addressStatementTimestamps: Array. Optional. List of elements:

  • dateType: String. Description of timestamp.
  • addressStatementTimestamp: Long. UTC timestamp.

• poaName: String. Optional. Extracted name from address statement.

• typeOfId: String. Image was classified as one of the following: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard

• documentFrontSubtype: String. Optional. Additional info about ID type (front side)

• documentBackSubtype: String. Optional. Additional info about ID type (back side)

• birthDate: Long. Optional. Date of birth is presented in UTC milliseconds.

• gender: String. Optional. 1 character. Gender values are presented in English. "M" for male and "F" for female.

• claveDeElector: String. Optional. 18 characters. Clave de elector as read from id. For Mexican IDs only.

• curp: String. Optional. 18 characters. Curp as read form id. For Mexican IDs only.

• numeroEmisionCredencial: String. Optional. 2 characters. Numero Emision Credencial as read from id. (For Mexican IDs only).

• cic : String. Optional. 9 characters. Cic as read from id. (This field is read from back side of id; For Mexican IDs only).

• ocr : String. Optional. 13 characters. Ocr as read from id. (This field is read from back side of id; For Mexican IDs only).

• documentNumber: String. Optional. Document number.

• personalNumber: String. Optional. Personal number.

• refNumber : String. Optional. Document Reference Number.

• taxIdNumber : String. Optional. Personal tax identification number.

• nue: String. Optional. NUE number as read from id. (for Resident Cards)

• externalId: String. Optional. External user id.

• issuedAt: String. Optional. Date of issue UTC timestamp.

• expireAt: String. Optional. Expiration date UTC timestamp.

• issueDate: Integer. Optional. Issue year of id.

• expirationDate: Integer. Optional. Expiration year of id.

• registrationDate : Integer. Optional. Registration date read from id.

• issuingCountry: String. Optional. Issuing country of document.

• issuingState: String. Optional. Issuing state of document.

• birthPlace : String. Optional. Birth place as read from id.

• issuingAuthority : String. Optional. Issuing Authority as read from id.

• height : String. Optional. Person's height as read from id.

• weight : String. Optional. Person's weight.

• eyeColor : String. Optional. Person's eye color.

• hairColor : String. Optional. Person's hair color.

• bloodType : String. Optional. Person's blood type.

• maritalStatus : String. Optional. Person's merital status.

• nationality : String. Optional. Person's nationality.

• nationalityMrz : String. Optional. Person's nationality as it appears in MRZ (if present).

• nationalityAlpha3 : String. Optional. Person's nationality Alpha3 code format. Only for Brazilian IDs.

• race : String. Optional. Person's race.

• dlClassDetails: Array. Optional. List of driver's license details elements:

  • dlClass: String. Driver's license class.
  • validFromDate: Long. DL class valid from UTC timestamp.
  • validToDate: Long. DL class valid to UTC timestamp.
  • additionalCodes: String. Additional codes associated with DL class.

• governmentComparisonResults : Government validation data. Optional. Returned only for supported government validation countries. Structure with following fields:

  • paternalLastNameValid : Boolean. Indicates validity of person's paternal last name through government validation apis.
  • maternalLastNameValid : Boolean. Indicates validity of person's maternal last name through government validation apis.
  • firstNameValid : Boolean. Indicates validity of person's first name through government validation apis.
  • curpValid : Boolean. Indicates CURP validity through government validation apis.
  • ocrValid : Boolean. Indicates ocr validity through government validation apis.
  • claveDeElectorValid : Boolean. Indicates clave de elector validity through government validation apis.
  • numeroEmisionCredencialValid : Boolean. Indicates numero emision credencial validity through government validation apis.
  • registrationDateValid : Boolean. Indicates registration date validity through government validation apis.
  • issueDateValid : Boolean. Indicates issue date validity through government validation apis.

• notExtracted : Integer. Number of not extracted OCR fields. Only for Mexican IDs.

• notExtractedDetails : String array. List of ocr field names that were not extracted. Only for Mexican IDs.

• classes : String. Optional. Person's driver licence classes.

• cond : String. Optional. Person's driver licence conditions.

• mentions : String. Optional. Person's driver licence mentions.

• restrictions : String. Optional. Person's driver licence restrictions.

• mrz1 : String. Optional. First MRZ line.

• mrz2 : String. Optional. Second MRZ line.

• mrz3 : String. Optional. Third MRZ line.

• fullNameMrz : String. Optional. Person's full name read from MRZ.

• documentNumberCheckDigit : String. Optional. Document number check digit read from MRZ.

• dateOfBirthCheckDigit : String. Optional. Date of birth check digit read from MRZ.

• expirationDateCheckDigit : String. Optional. Expiration date check digit read from MRZ.

• barcodeRawData : String. Optional. Full unformatted data read from 2D barcode.

• fathersName : String. Optional. Person's father's name. Only for Brazilian and Indian IDs.

• mothersName : String. Optional. Person's mother's name. Only for Brazilian IDs.

• federalRevenueNumber : String. Optional. Federal revenue number. Only for Brazilian IDs.

• originDocumentId : String. Optional. Origin document ID. Only for Brazilian IDs.

• driversLicenseCategory : String. Optional. Driver's licence category. Only for Brazilian IDs.

• controlNumber : String. Optional. Control number. Only for Brazilian IDs.

• renach : String. Renach. Optional. Only for Brazilian IDs.

• ocrDataConfidence : Structure containing ocr reliability confidence for each extracted ocr field. Confidence values are Floats between 0 and 1. All fields are optional.

  • birthDateConfidence : Float. Confidence between 0 and 1.
  • nameConfidence : Float. Confidence between 0 and 1.
  • givenNameConfidence : Float. Confidence between 0 and 1.
  • firstNameConfidence : Float. Confidence between 0 and 1.
  • middleNameConfidence : Float. Confidence between 0 and 1.
  • nameSuffixConfidence : Float. Confidence between 0 and 1.
  • mothersSurnameConfidence : Float. Confidence between 0 and 1.
  • fathersSurnameConfidence : Float. Confidence between 0 and 1.
  • fullNameMrzConfidence : Float. Confidence between 0 and 1.
  • addressConfidence : Float. Confidence between 0 and 1.
  • streetConfidence : Float. Confidence between 0 and 1.
  • colonyConfidence : Float. Confidence between 0 and 1.
  • postalCodeConfidence : Float. Confidence between 0 and 1.
  • cityConfidence : Float. Confidence between 0 and 1.
  • stateConfidence : Float. Confidence between 0 and 1.
  • ...and other described ocr fields, followed by confidence suffix (ocrFieldNameConfidence)

Fetch ocr data v2

GET /omni/get/ocr-data/v2?id=4390u032r

Returns data about user read from id and address statement wrapped in ocrData object.

Request parameters:

• id: String, optional. Id of onboarding for which data are requested. If not present, it will be extracted from token.

Response:

• ocrData: For detailed content of this object check /omni/get/ocr-data

Fetch medical data

GET /omni/get/medical-ocr-data

Returns data about medical card

Response:

• member: String. Member name
• memberId: String.
• provider: String.
• copayEr: String.
• copayOv : String
• rxBin: String
• rxPcn: String

Download events report

POST /omni/get/report

Generates pdf report for all events which have happened for specified user.

Request Body:

• provider: String. Values: incode, nom151. Specifies protocol used for signing each event.

Eg:

{
  "provider": "incode"
}

Response is the pdf report with all events that were connected to user. Response contain header Content-Type:application/pdf

Fetch events

GET /omni/get/events?id=123342

Get events for given id. Parameter id is optional. If it not present, it will be extracted from token. Response contains list of events for given id.

Request Body:

• id: String, optional. If not present it will be extracted from token.
• offset: Integer, optional. Used for pagination. Should be positive integer number. Default value is 0.
• limit: Integer, optional. Used for pagination. Allowed values are between 1 and 100. Default value is 100.

Response:

• events: List.
  • eventName: String
  • eventData: Map
  • singature: String
  • timestamp: Long, UTC timestamp

Fetch events signature

GET /omni/get/events-signature?id=395702947524

Fetch signature of all events that happened for one onboarding session. Id parameter is optional. (If it is not sent, it will be extracted form token)

Response:

• signature: String, mandatory. Signature of all events for one's onboarding session.

Fetch events report

POST /omni/get/events-report

Fetch signature of all events that happened for one onboarding session and the events.

Request Body:

• identityId: String, optional. If not present it will be extracted from token.

• provider:String, optional. Values: incode, nom151 Eg:

  {
    "identityId": "605de63b6ja7haa7aa2b3",
    "provider": "nom151"
  }    

Response:

• events: List.

  • eventName: String
  • eventData: Map
  • singature: String
  • timestamp: Long, UTC timestamp

• signature: String, mandatory. Signature of all events for one's onboarding session.

Generate interview code

GET /omni/code/generate

Generate interview code for this session.

Response:

• interviewCode: String. 6 characters. Newly generated code to be verified before connecting to video conference.

Mark onboarding complete

GET /omni/finish-status

Mark onboarding done

Response:

• redirectionUrl: String. Url to be redirected when onboarding is done
• action: String. Possible values none | approved | manualReview | rejected. Refers to the action performed based on the flow score configurations if applicable.

Verify interview code

POST /omni/code/verify

Verify interview code before connecting to video conference.

Request Body:

• interviewCode: String, mandatory. 6 characters. Interview code to be verified against given session. Eg:

  {
    "interviewCode": "C8Z38D"
  }

Response:

• success: Boolean. Flag indicating interview code verified successfully.

Custom error status:

• 4014: Invalid interview code. For more details about error format see errors section.

Delete PII data for single onboarding session

DELETE /omni/interview?interviewId=id

Delete all PII data for single onboarding session using interviewId. After deletion, we set Deleted in the sessionStatus field for the session and the boolean field deleted=true for the customer.

Note:

• Requires admin login token reference - Admin-Login
• Please, bear in mind that usage of this API endpoint for deletion of Customer Data will mean that Incode will no longer have access to it nor will be able to review or analyze any issue related to deleted Customer Data. After deletion, as Incode will not be able to retrieve the deleted Customer Data, any potential claims related to such data will be waived by Customer. Finally, for clarity purposes, Incode may continue to process information derived from Customer Data that has been deidentified, anonymized, and/or aggregated such that the data is no longer considered Personal Data under applicable Data Protection Laws and in a manner that does not identify individuals or Customer to improve its services and defend its legitimate interests.

Request parameters:

• interviewId: String. Specify which interview.

• keepCustomer: Optional. True or false. Indicates whether to keep idenity of the customer or not. Default is false(which means session and customer identity both will be deleted).

• sendNotification: Optional. True or false. Flag to send a notification about a change interview status. Default is false.

Response:

{
  "success": true
}

Delete PII data for multiple onboarding sessions with multiple options

DELETE omni/interviews

Delete all PII data for onboarding sessions by given array of interview ids. After deletion, we set Deleted in the sessionStatus field for the session and the boolean field deleted=true for the customer.

Note:

• Requires admin login token reference - Admin-Login
• Please, bear in mind that usage of this API endpoint for deletion of Customer Data will mean that Incode will no longer have access to it nor will be able to review or analyze any issue related to deleted Customer Data. After deletion, as Incode will not be able to retrieve the deleted Customer Data, any potential claims related to such data will be waived by Customer. Finally, for clarity purposes, Incode may continue to process information derived from Customer Data that has been deidentified, anonymized, and/or aggregated such that the data is no longer considered Personal Data under applicable Data Protection Laws and in a manner that does not identify individuals or Customer to improve its services and defend its legitimate interests.

Below is the request body with multiple options.

• filter: Mandatory. Filter for cleaning interview. Must contain one of the filter fields

  • ids Array of strings. List of session ids to be cleaned.

  • flowId Strings. List of session ids to be cleaned.

  • externalId String. Specify which external-id.

• config: Delete options, optional.

  • sendNotification: Boolean, optional. Flag indicating to send a notification about a change interview status. Default is false.

  • relatedEntitiesToKeep: Array, optional. List of related entities to be saved. Works only when deletePiiDataOnly=true. Supported entities: identities, faceTemplates, images, stats, chats, deviceFingerPrints

Request Body Eg:

{
    "filter": {
        "ids": [
            "specify interview first id",
            "specify interview second id"
        ]
    },
    "config": {
        "deletePiiDataOnly": true,
        "sendNotification": true,
        "relatedEntitiesToKeep": [
            "faceTemplates",
            "stats"
        ]
    }
}

Response:

{
  "success": true
}

Delete Multiple onboarding sessions with multiple options

Deprecated POST omni/delete/interviews Instead of this endpoint, we recommend using DELETE interviews

Delete all onboarding sessions by given array of interview ids. The endpoint is executed asynchronously.

Note:

• Requires admin login token reference api - Admin-Login
• Please, bear in mind that usage of this API endpoint for deletion of Customer Data will mean that Incode will no longer have access to it nor will be able to review or analyze any issue related to deleted Customer Data. After deletion, as Incode will not be able to retrieve the deleted Customer Data, any potential claims related to such data will be waived by Customer. Finally, for clarity purposes, Incode may continue to process information derived from Customer Data that has been deidentified, anonymized, and/or aggregated such that the data is no longer considered Personal Data under applicable Data Protection Laws and in a manner that does not identify individuals or Customer to improve its services and defend its legitimate interests.

Below is the request body with multiple options.

• interviewIds: Array of strings, mandatory. List of session ids to be deleted.

• cleanerConfiguration: Delete options, optional.

  • piiFieldsToKeep: Array, optional. List of PII fields to preserve when deletePiiFieldsOnly is set to true.

  • keepEnrolledUser: Boolean, optional. Flag indicating if user that was previously enrolled from this session should stay enrolled in the system after this session is deleted. Default is false.

  • keepTemplates: Boolean, optional. Flag indicating if face templates created during onboarding process, should remain in DB. Default is false.

  • keepImages: Boolean, optional. Flag indicating if images captured during onboarding process should remain in the system. Default is false.

  • keepDeviceFingerprints: Boolean, optional. Flag indicating if device fingerprint stored during onboarding process should remain in the system. Default is false.

  • keepEvents: Boolean, optional. Flag indicating if events stored during onboarding process should remain in the system. Default is false.

  • keepValidationTests: Boolean, optional. Flag indicating if validation tests stored during onboarding process should remain in the system. Default is false.

  • keepVideoArchives: Boolean, optional. Flag indicating if video archives stored during onboarding process should remain in the system. Default is false.

  • keepConferenceEvents: Boolean, optional. Flag indicating if events stored during conference video call should remain in the system. Default is false.

  • keepChats: Boolean, optional. Flag indicating if chat stored during conference video call should remain in the system. Default is false.

  • keepStats: Boolean, optional. Flag indicating if statistics stored during onboarding process should remain in the system. Default is false.

Request Body Eg:

{
  "interviewIds" : [
    "specify interview id",
    "specify interview id"
  ],
  "cleanerConfiguration": {
    "keepEnrolledUser": true
  }
}

Response:

{
  "success": true
}

Delete PII data for single onboarding session by external ID

Deprecated DELETE /omni/session/externalId?externalId=id Instead of this endpoint, we recommend using DELETE interviews

Delete single onboarding session using the external ID as identifier.

Note:

• Requires admin login token reference - Admin-Login
• Please, bear in mind that usage of this API endpoint for deletion of Customer Data will mean that Incode will no longer have access to it nor will be able to review or analyze any issue related to deleted Customer Data. After deletion, as Incode will not be able to retrieve the deleted Customer Data, any potential claims related to such data will be waived by Customer. Finally, for clarity purposes, Incode may continue to process information derived from Customer Data that has been deidentified, anonymized, and/or aggregated such that the data is no longer considered Personal Data under applicable Data Protection Laws and in a manner that does not identify individuals or Customer to improve its services and defend its legitimate interests.

Request parameters:

• externalId: Specify which external-id.

• keepCustomer: true or false. Indicates whether to keep idenity of the customer or not. Default is false(which means session and customer identity both will be deleted).

Response:

{
  "success": true
}

Expire onboarding sessions by interviewIds

POST omni/expire/interviews

Expire onboarding sessions given by interviewIds array, and cleanerConfiguration parameter.

Request Body Eg:

{
  "interviewIds": [
    "specify interview id",
    "specify interview id"
  ],
  "cleanerConfiguration": {
    "expirationConditions": [
      "NEEDS_REVIEW"
    ]
  }
}

• interviewIds: Array, mandatory. Array of interview IDs.

• cleanerConfiguration: Structure (mandatory), with following fields: expirationConditions: Array, mandatory. List of one or more conditions. Possible values: INCOMPLETE, NEEDS_REVIEW.

Response:

{
  "success": true
}

Assign interviewId to interview

POST omni/interview/set-interviewer

Assign interviewerId to interview.

In case interview not found returns error status code (status field): 4014

Request Body:

• interviewId String, interviewId (required).
• interviewerId String, interviewerId (required).

Response:

• success boolean

Sign String with NOM 151

POST /omni/sign-string/nom151

Sign any String with NOM 151.

Request Body:

• stringToSign: String, mandatory. String to be signed with NOM151. Eg:

  {
    "stringToSign": "content..."
  }

Response:

• signedString: String. Signed String with NOM151.

Attach signature to pdf document

POST /omni/attach-signature-to-pdf

Attach signature from interview to supplied pdf at (x, y) coordinates with desired height to desired page on pdf. Coordinates are relative to left bottom corner of page.

Request Body:

• body: byte array, mandatory: document to add signature to

Params:

• x: int, mandatory: the x axis where to place the signature image (from the left bottom corner of page)
• y: int, mandatory: the y axis where to place the signature image (from the left bottom corner of page)
• height: int, mandatory: height of the image when placed in the pdf, keeps aspect ratio.
• pageNumber: int, optional: number of page on which to put the signature image (pages numbering start from 1, default value is 1)

Response:

• stream of new pdf document file

Attach signature to multiple pdf documents

POST /omni/attach-signature-to-pdf/v2

Attach signature from interview to previously uploaded PDF contracts at (x, y) coordinates with desired height to desired page on pdf. Coordinates are relative to left bottom corner of page. Every document id can have multiple signature attached to it, hence the array of signature positions for every document.

Request Body:

• signaturePositionsOnContracts: map of arrays of signature positions, mandatory: Keys are IDs of previously added documents (IDs are returned on /add/document?imageType=contract), values are arrays of signature positions.
• includeSignedDocumentInResponse: Boolean, optional: includes the signed document in base64 in response.
• includeNom151SignatureInResponse: Boolean, optional: includes the Nom 151 signature of the signed document in the response.
• includeSignedDocumentWithNom151InResponse: Boolean, optional: includes the signed document with the Nom 151 signature attached in the pdf in the response.
• includeCertificateDetailsInResponse: Boolean, optional: include the certificate details with which the Nom151 signature was created.

Signature position:

• x: int, mandatory: the x axis where to place the signature image (from the left bottom corner of page).

• y: int, mandatory: the y axis where to place the signature image (from the left bottom corner of page).

• height: int, mandatory: height of the image when placed in the pdf, keeps aspect ratio.

• pageNumber: int, mandatory: number of page on which to put the signature image (pages numbering start from 1, default value is 1).

• orientation: enum, optional: counterclockwise rotation of the signature in degrees:

  • ORIENTATION_NORMAL,
  • ORIENTATION_90_DEGREE,
  • ORIENTATION_180_DEGREE,
  • ORIENTATION_270_DEGREE

Eg:

{
  "includeSignedDocumentInResponse": true,
  "includeNom151SignatureInResponse": true,
  "includeSignedDocumentWithNom151InResponse": true,
  "includeCertificateDetailsInResponse": true,
  "signaturePositionsOnContracts": {
    "e81cd044-98fd-47b0-b0c5-937b22b69977#contract1": [
      {
        "x": 10,
        "y": 10,
        "height": 10,
        "pageNumber": 2,
        "orientation": "ORIENTATION_NORMAL"
      },
      {
        "x": 20,
        "y": 30,
        "height": 10,
        "pageNumber": 1,
        "orientation": "ORIENTATION_90_DEGREE"
      }
    ],
    "1ffcd128-153f-40d4-a881-7c3362e58806#contract2": [
      {
        "x": 10,
        "y": 10,
        "height": 20,
        "pageNumber": 2
      },
      {
        "x": 20,
        "y": 30,
        "height": 20,
        "pageNumber": 1
      }
    ],
    "074355ff-81f5-4b9f-a6c6-eb41bdcaf9f1#contract3": [
      {
        "x": 10,
        "y": 10,
        "height": 30,
        "pageNumber": 2
      },
      {
        "x": 20,
        "y": 30,
        "height": 30,
        "pageNumber": 1
      }
    ]
  }
}

Response Body:

{ "success": true, "sessionStatus": "Alive", "additionalInformation": { "signingDetails": { "providedBy": "Advantage Security, S. de R.L. de C.V.", "requestedBy": "Incode Technologies Inc.", "policyValue": "2.16.484.101.10.316.2.1.1.2.", "signingHash": "AHm8P/i2AnvdM8vKfVLWe5xCovA2v/7l3zmWc1+N4HE=", "certificateSerial": "2C", "signingTimestamp": "1651076647389" }, "signedDocumentBase64": "base64 of pdf document", "signedDocumentWithNomSignatureBase64": "base64 of pdf document with nom151" }

Attach signature on annotation

POST /omni/attach-signature-on-annotation

Attach signature from interview to previously uploaded PDF contracts at all places annotated with text from request, with desired height on pdf. Annotations must contain text with either preselected values, or alternative can be supplied. If user wishes to use signature supplied during onboarding, DEFAULT signature type should be used. Preselected values are: DEFAULT, INITIALS, PATIENTS_SIGNATURE, NON_MEDICAL_SIGNATURE_1, NON_MEDICAL_SIGNATURE_2, MEDICAL_SIGNATURE_1, MEDICAL_SIGNATURE_2 Endpoint is intended to be used as fluent api. One call to the api gives in responses id of the signed document which can then be used in the subsequent call to continuously add another signature on a different annotation.

Request Body:

• contractId: String, mandatory: IDs of previously added contract (ID is returned on /add/document?imageType=contract)
• signedContractId: String, optinal: IDs of previously signed contract (ID is returned as response from the previous /attach/signature/on/annotation)
• signatureType: String, optinal: one of the preselected values for annotation text
• alternativeSignatureType: String, optinal: if annotation text is none of the preselected values, pass in here the alternative value (signature must be inserted with the alternative value into database as it's signature type)

Eg:

{
  "contractId": "e81cd044-98fd-47b0-b0c5-937b22b69977#contract1",
  "signatureType": "PATIENTS_SIGNATURE"
}

Response:

{
  "success": true,
  "signedDocumentId": "new signed document ID",
  "signedDocumentURL": "temporary URL to new signed document"
}

Attach stamp on annotation

POST /omni/attach-stamp-on-annotation

Substitute stamps from interview to previously uploaded PDF contracts at all places with pdf text annotations. Annotations must contain text with preselected values. Preselected values are:

• NAME (NAME_STAMP),
• ADDRESS (ADDRESS_STAMP),
• DATE #ZoneId# #Format#,
• AGE,
• SEX,
• DOB #Format#,
• COUNTRY,
• STATE,
• PHONE,
• TIME #ZoneId# #Format#,
• SECOND_NAME *

Replace parameter ZoneId with full size zone using time zones used in Java8 TimeDate API Replace parameter Format with format you wish to display the time and date

Stamps are added in Helvetica, size 13. Endpoint is intended to be used as fluent api. One call to the api gives in responses id of the signed document which can then be used in the subsequent call to continuously add another signature on a different annotation.

Request Body:

• contractId: String, mandatory: IDs of previously added contract (ID is returned on /add/document?imageType=contract)
• customFields: Map<String, String>, optional: Use to add substitute text for stamps with asterisk Eg: { "contractId": "e81cd044-98fd-47b0-b0c5-937b22b69977#contract1", "customFields": { "SECOND_NAME": "Luke Skywalker" } }

Response Body: { "success": true, "additionalInformation": { "signedDocumentId": "new signed document ID", "signedDocumentURL": "temporary URL to new signed document" } }

Calculate contract Nom151 signature

POST /omni/calculate-contract-nom151-signature

This api endpoint calculates the Nom151 signature of an already signed contract and returns the signature.

Request Body:

• signedContractId: String, required: the id of the already signed contract
• includeSignedDocumentInResponse: Boolean, optional: includes the signed document in base64 in response
• includeSignedDocumentWithNom151InResponse: Boolean, optional: includes the signed document with the Nom 151 signature attached in the pdf in the response

Eg:

{
  "signedContractId": "cf74e1be-e1bf-4708-9e0e-3b43a8313f85#contract1",
  "includeSignedDocumentWithNom151InResponse": true,
  "includeSignedDocumentInResponse": true
}

Response Body:

{
  "success": true,
  "sessionStatus": "Alive",
  "additionalInformation": {
    "signedDocumentNom151": "nom151 signature",
    "signedDocumentBase64": "base64 of signed document",
    "signedDocumentWithNomSignatureBase64": "base64 of signed contcat with attached nom151 signature"
  }
}

Get contracts links

GET /omni/get/contracts-links

Fetches temporary link of the contracts uploaded for the current session.

Response:

• Temporary URLs to uploaded documents. URLs valid for 1h (60min)

Eg:

{
  "success": true,
  "sessionStatus": "Alive",
  "additionalInformation": {
    "document ID1": "Temporary URL to uploaded document with ID1",
    "document ID2": "Temporary URL to uploaded document with ID2",
    "document ID3": "Temporary URL to uploaded document with ID3"
  }
}

Get signed contracts links

GET /omni/get/signed-contracts-links

Fetches temporary link of the signed contracts uploaded for the current session.

Response:

• Temporary URLs to signed documents. URLs valid for 1h (60min)

Eg:

{
  "success": true,
  "sessionStatus": "Alive",
  "additionalInformation": {
    "document ID1": "Temporary URL to signed document with ID1",
    "document ID2": "Temporary URL to signed document with ID2",
    "document ID3": "Temporary URL to signed document with ID3"
  }
}

Process batch of images

POST /omni/process/batch

Process batch of images located on S3 Bucket. Image filename can have multiple parts separated by underscore (_), where first part represents external userId. In case file name contains word front it woudl be used as front ID (e.g. 12345_front.jpg). In case file name contains word back it woudl be used as back ID (e.g. 12345_back.jpg). In case file name contains word face it woudl be used as selfie image (e.g. 12345_face.jpg). The external userId identifier could be later used for fetching the ocr data. For each userId, a list of passed operations will be applied.

There is no limit on the amount of images/users to be processed, but bare in mind that on a large set of documents the processing can take even up to a number of days.

Request parameters:

• limit: Integer, optional. Number of users to be processed in batch. In case it is set to -1 all images will be processed. In case omitted, it would be defaulted to 10000.

Request Body:

• onboardingOperations: String array. List of operations that have to be executed for each user. Possible values: ADD_FRONT, ADD_BACK, ADD_FACE, ADD_CURP, EXTRACT_FRONT_ID_OCR, VERIFY_FACE, PROCESS_ID, PROCESS_FACE, PROCESS_GOV_VALIDATION, APPROVE
• flowId: String, optional. Id of the Flow used for processing.

Eg:

{
  "onboardingOperations": [
    "ADD_FRONT",
    "ADD_BACK",
    "ADD_FACE",
    "ADD_CURP",
    "PROCESS_ID",
    "PROCESS_FACE",
    "PROCESS_GOV_VALIDATION"
  ],
  "flowId": "617301aa7471af001546ecd3"
}

Response:

• success: Boolean. Flag indicating that batch was triggered successfully.
• usersBeforeProcessing: Integer. Total number of users left in S3 bucket, before processing.
• batchSize: Integer. Number of users that will be processed in this batch.

Eg:

{
  "success": true,
  "usersBeforeProcessing": 1200000,
  "batchSize": 10000
}

Get batch processing status

GET /omni/get/process-batch-status

Returns the status of the /omni/process/batch progress.

Response:

• Integer: current count of processed documents.

Get ID Summary

GET /omni/get/id-summary?id=619ef4b33aac270013c2df22

Returns success information about addFront and addBack. Also returns onlyFront flag.

Request parameters:

• id: String, optional. Id of onboarding for which data are requested. If not present, it will be extracted from token.

Response:

• IdSummaryResponse : Object containing success info (Booleans) about addFrontResult, addBackResult and onlyFront flag.

Fetch batch of ocr results

POST /omni/fetch/batch/ocr

Fetch batch of ocr results for documents with given ids. Please supply max of 10000 values.

Request:

• body: json string with two params - identifier and a array of values.

Params:

• identifier: String, mandatory: identifier for which to search for the ocr results.
• values: Array of strings, mandatory: values for the given identifier.

Eg:

{
  "identifier": "externalId",
  "values": [
    "123456",
    "654321"
  ]
}

Response:

• ocrDataResponses: Array of ocr responses for asked ids. (for description of each ocr response see Fetch-OCR).

Throws:

• 400 BadRequestException: if more than 10000 values are supplied.

Set session status

POST /omni/session/status/set

Set the status of current session. Possible actions to set the status to are: Alive, Closed or Deleted. Closed status disables all of the "/add/..." calls so they can no longer make any changes to the system. Deleted status deletes the important data stored in the session.

Params:

• action: String: possible values Alive, Closed, Deleted.
• id: String: id of the session, optional, if not sent obtained from token.

Response:

• id: String: Session id.
• createdAt: Timestamp, long: When was the session created.
• updatedAt: Timestamp, long: When was the session last updated.
• closedAt: Timestamp, long: When was the session last closed.
• frontIdAttempts: int: Attempts to save front id.
• backIdAttempts: int: Attempts to save back id.
• selfieAttempts: int: Attempts to save selfie.
• sessionStatus: SessionStatus: Alive, Closed or Deleted.

Get session status

GET /omni/session/status/get

Get the status of current session.

Response:

• id: String: Session id
• createdAt: Timestamp, long: When was the session created
• updatedAt: Timestamp, long: When was the session last updated
• closedAt: Timestamp, long: When was the session last closed
• frontIdAttempts: int: Attempts to save front id
• backIdAttempts: int: Attempts to save back id
• selfieAttempts: int: Attempts to save selfie
• sessionStatus: SessionStatus: Alive, Closed or Deleted

Add user consent

POST /omni/add/user-consent

Add user consent with title, content and status to session.

Request Body:

• title: String: Title of the consent.
• content: String: Text content.
• status: Boolean: Status (true/false).

Eg:

{
  "title": "Title",
  "content": "Content",
  "status": true
}

Response:

• success: Boolean
• sessionStatus: SessionStatus

Get user consent

GET /omni/get/user-consent

Fetches user consent with title, content and status from session.

Request Body:

• id: String - optional: Session id.

Response:

• title: String: Title of the consent.
• content: String: Text content.
• status: Boolean: Status (true/false).

Insert authentications in batch

POST /omni/batch/auth-statst

Inserts face authentications in batch.

Request Body:

• data: Array of authentication stats.
• id: String: identitiy (customer) id.
• photo: String: base64 of photo.
• confidence: Float: match confidence.
• timestamp: Long: timestamp.
• sourceId: String: source identifier of batch of authentications.

Eg:

  {
    "data": 
    [
      {
        "id": "6231ec685a378c0013e72641",
        "photo": "base64 of photo",
        "confidence": 100,
        "timestamp": 1647444546006,
        "sourceId": "identifier"
      },
      {
        "id": "6231ec685a378c0013e72641",
        "photo": "base64 of photo",
        "confidence": 100,
        "timestamp": 1647444546006,
        "sourceId": "identifier"
      }
    ]
  }

Response:

• success: Boolean: operation success.

Generate document upload url

POST /omni/es/generateDocumentUploadUrl

Generates upload URL for document to be signed via Advanced Electronic Signature (AES).

Response:

• preSignedUrl: String: url to be used for uploading the document.
• referenceId: String: reference id for the document.

Get unsigned documents

GET /omni/es/documents/unsigned

Retrieves documents to be signed via AES for a session.

Response:
The response will be a JSON object with the documents key which will contain an array of documents. Each item will have the following schema.

• documentRef: String: reference id of the document.
• documentUrl: String. Pre-signed document url to download the file

Sign document via advanced electronic signature

POST /omni/es/process/sign

Sign document via advanced electronic signature.

Request Body:

• documentRef: String: Reference id of the document to be signed. Reference was received in the /omni/es/generateDocumentUploadUrl response
• userConsented: Boolean: Flag indicating whether user gave consent to sign the document.

Eg:

{
  "documentRef": "7e0299e7-1e0d-4787-b97b-81e69198e5f5",
  "userConsented": true
}

Response:

• success: Boolean

Throws:

• 400 BadRequestException: if userConsented flag is false | if document with documentRef does not exist | session is not approved | Id validation status is not OK | Face recognition status is not OK | Otp verification is enabled and opt phone verification is not done.

Get signed documents

GET /omni/es/documents/signed

Retrieves documents signed via advanced electronic signature.

Response:
The response will be a JSON object with the documents key which will contain an array of documents. Each item will have the following schema.

• documentRef: String: reference id of the signed document.
• documentUrl: String. Pre-signed document url to download the file