Skip to main content

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.
  • interviewId: String, optional. InterviewId from a previous onboarding, including it helps get a new token for that id.
  • 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",
  "externalId": "client34598",
  "redirectionUrl": "www.google.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.

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.
  • imageUrl: String, mandatory (one of base64Image or imageUrl). Image as image url.

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. If customer with that phone already exists, error will be thrown.

Request Body:

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

Eg:

  {
    "phone": "+1111111"
  }

Response:

  • success: Boolean. Flag indicating request passed successfully.

Custom error status:

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

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.

  • 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

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.

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

Eg:

{
    "manualIdCheckNeeded": true,
    "manualSelfieCheckNeeded": false,
    "name": "John Smith",
    "birthDate": "02/15/1990",
    "address": "221B Baker Street",
    "gender": "Male",
}

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

This endpoint verifies phone, email, address, date of birth and tax numbers, specifically social security number (ssn). When making a request use "kyc" in the plugins array. To have the API return specific risk scores for phone, email, ssn (taxId) and address, see examples below.

Examples​

Check address​


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


Check email​

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

Check phone​

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

Check SSN (taxId)​

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


Full eKYC check​

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

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: ^±!@£$%&*_+¡€#¢§¶•ªº«<>?\/:;|=.
  • email: String
  • street: String
  • postalCode: String
  • countryCode: String ie: us ISO 3166-1 alpha-2 format
  • phone: String, Use E.164 format. Hyphens are optional. ie: +14156067603
  • state: String
  • city: String
  • taxId: Is should be a social security number with no spaces or dashes, ie: 123456789
  • dateOfBirth: String, ie: YYYY-MM-DD

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

Evaluate KYC responses​

KYC response will contain an array of risk objects with key and status properties. The key indicates a type of risk, such as addressRiskLevel. The status value explains the risk level, ie "low", "medium", or "high". When doing a social security number check, the API will return status values of nomatch, fuzzy or exact. Fuzzy means there is plausible match between the name and the social security number, like Dave and David both resolve to the same SSN.

The overallLevel key name is an aggregate risk score for all risk types. It can be used to obtain a single risk score for a whole result set.

Response:

{
    "kyc": [
        {
            "key": "addressRiskLevel",
            "status": "medium"
        },
        {
            "key": "emailDomainLevel",
            "status": "low"
        },
        {
            "key": "emailLevel",
            "status": "low"
        },
        {
            "key": "phoneCarrier",
            "status": "Verizon"
        },
        {
            "key": "phoneLevel",
            "status": "low"
        },
        {
            "key": "phoneLineType",
            "status": "Mobile"
        },
        {
            "key": "taxIdDobMatch",
            "status": "exact"
        },
        {
            "key": "taxIdLevel",
            "status": "low",
        },
        {
            "key": "taxIdMatch",
            "status": "exact"
        },
        {
            "key": "taxIdNameMatch",
            "status": "exact"
        },
        {
            "key": "taxIdStateMatch",
            "status": "exact"
        },
        {
            "key": "manualReview",
            "status": "false"
        },
        {
            "key": "overallLevel",
            "status": "low"
        }
    ]
}

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.
  • addressLine1: String. Address line 1 of the business.
  • addressLine2: String. Address line 2 of the business.
  • city: String. City of the business of the business address.
  • state: String. State of the business of the business address.
  • postalCode: String. 5 letter postal code of the business address.

Request example:

{
   "plugins" : ["ekyb"],
   "businessName" : "Incode Technologies, Inc.",
   "addressLine1" : "575 Market St",
   "addressLine2" : "Fl 4",
   "city" : "San Francisco",
   "state" : "CA",
   "postalCode" : "94105"
}

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.
  • status: String. Whether the test ows passed.
  • sub_label: String. Additional info on the status.
  • message: String. Human readeable description of the status.
{
    "kyb": [
        {
            "key": "name",
            "status": "success",
            "sub_label": "Verified",
            "message": "Match identified to the submitted Business Name"
        },
        {
            "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"
        }
    ]
}

Status codes for business name:

statuslabelsub_label
SuccessMatch identified to the submitted Business NameVerified
WarningSimilar match identified to the submitted Business NameSimilar Match
FailureUnable to identify a match to the submitted Business NameUnverified
FailureWe believe the submitted TIN is associated with “name”Alternate Name

Status codes for address verification:

statuslabelsub_label
SuccessMatch identified to the submitted Business NameVerified
WarningSimilar match identified to the submitted Business NameSimilar Match
FailureUnable to identify a match to the submitted Business NameUnverified
FailureWe believe the submitted TIN is associated with “name”Alternate Name

Status codes for address property type:

statuslabelsub_label
SuccessSubmitted Office Address is a Commercial propertyCommercial
WarningSubmitted Office Address is a Residential propertyResidential

Status codes for address deliverability:

statuslabelsub_label
SuccessThe USPS is able to deliver mail to the submitted Office AddressDeliverable
FailureThe USPS is unable to deliver mail to the submitted Office AddressUndeliverable

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: Float Year of birth, if known

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

  • 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

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

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", "iliterationCheck", "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.

  • 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: Specific rule from rule engine for total:

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

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.
    • givenName: String.
    • middleName: String.
    • nameSuffix: String.
    • machineReadableFullName: String. Full name from Barcode or MRZ.
    • givenNameMrz: String.
    • lastNameMrz: String.

  • address: String. Address as read from id. Address can have two or three lines. Lines 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. 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. Address as obtained after processing with geocoder geolocation api.

  • checkedAddressBean: Address object obtained after processing with geocoder geolocation api. 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. 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. Issue date of address statement. The value is presented in UTC milliseconds.

  • documentType: String. 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. Date of birth is presented in UTC milliseconds.

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

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

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

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

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

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

  • documentNumber: String. Document number.

  • personalNumber: String. Personal number.

  • refNumber : String. Document Reference Number.

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

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

  • externalId: String. External user id.

  • issuedAt: String. Date of issue UTC timestamp.

  • expireAt: String. Expiration date UTC timestamp.

  • issueDate: Integer. Issue year of id.

  • expirationDate: Integer. Expiration year of id.

  • registrationDate : Integer. Registration date read from id.

  • issuingCountry: String. Issuing country of document.

  • issuingState: String. Issuing state of document.

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

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

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

  • weight : String. Person's weight.

  • eyeColor : String. Person's eye color.

  • hairColor : String. Person's hair color.

  • bloodType : String. Person's blood type.

  • maritalStatus : String. Person's merital status.

  • nationality : String. Person's nationality.

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

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

  • race : String. Person's race.

  • additionalTimestamps: Array. Optional. List of elements:

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

  • 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. 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. Person's driver licence classes.

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

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

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

  • mrz1 : String. First MRZ line.

  • mrz2 : String. Second MRZ line.

  • mrz3 : String. Third MRZ line.

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

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

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

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

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

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

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

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

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

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

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

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

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

    • 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 single onboarding session​

DELETE /omni/interview?interviewId=id

Delete single onboarding session using interviewId.

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

Request parameters:

  • interviewId: Specify which interview.

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

Delete Multiple onboarding sessions with multiple options​

POST omni/delete/interviews

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

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

Below is the request body with multiple options.

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

  • cleanerConfiguration: Delete options, optional.

    • deletePiiFieldsOnly: Boolean, optional. Flag indicating if this is partial delete, where only PII fields should be removed. Default is false.

    • 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 single onboarding session with external ID​

DELETE /omni/session/externalId?externalId=id

Delete single onboarding session using the external ID as identifier.

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

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 /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 /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

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