ID OCR Verification

The ID OCR Node extracts data from identity documents using Optical Character Recognition (OCR) technology. This node processes front and back images of identity documents and extracts structured data that can be used throughout your conversational flow.

Overview

The ID OCR Node is designed to extract information from identity documents (such as national IDs, driver's licenses, or passports) by processing document images. It supports multiple countries and OCR providers, allowing you to configure the appropriate service for your region and requirements.

This node is essential for onboarding flows where you need to collect and verify identity information from users. It can extract data like names, identification numbers, dates of birth, addresses, and other document-specific fields.

Configuration

Configuration Options

Configuration Interface

The node configuration is done through a visual dialog with two tabs:

Configuration Tab

1. OCR Verification Required - A highlighted section explaining that this node extracts data from identity documents using OCR technology.

2. Provider Configuration:

   • Select Country - A dropdown to choose the country for which the identity document is issued (e.g., Ecuador)
   • Provider - A dropdown to select the OCR provider service (e.g., Nubarium)

3. Front Image Variable - A variable selector to choose the variable containing the URL of the front image of the document. The variable type should be attachment (e.g., cedula_front).

4. Back Image Variable - A variable selector to choose the variable containing the URL of the back image of the document. The variable type should be attachment (e.g., cedula_back).

5. Store Response in Variable - A toggle switch to enable saving the OCR response data in a flow variable. When enabled, you can select the variable name (e.g., ocr_response of type object).

6. Store in Package - A toggle switch to enable saving the OCR response as a package for later access.

Advanced Tab

1. Save Images to Identity - A toggle switch to attach the document images to an identity for storage.

2. Maximum Retries - A number input field to set the number of retry attempts if the OCR provider fails. Range: 1-5, Default: 3.

Input

The node requires two image inputs:

Front Image Variable

The variable containing the URL of the front image of the identity document. This should be an attachment variable that references the document's front side image.

Variable Type: attachment

Example:

cedula_front

Back Image Variable

The variable containing the URL of the back image of the identity document. This should be an attachment variable that references the document's back side image.

Variable Type: attachment

Example:

cedula_back

Output

The node produces structured data extracted from the identity document. The output format depends on the country and document type, but typically includes:

• Personal information (name, identification number, date of birth)
• Address information
• Document metadata (issue date, expiration date, document number)
• Additional fields specific to the document type

Output Format

When "Store Response in Variable" is enabled, the response is stored in the specified variable as an object containing:

• extractedData - An object with the extracted information:
  • Personal information (name, identification number, date of birth)
  • Address information (street, city, country)
  • Other document-specific fields
• documentType - The type of document processed (e.g., "national_id", "cedula")
• confidence - A confidence score (0-1) indicating the accuracy of the extraction
• processedAt - Timestamp of when the processing occurred

Behavior

OCR Processing

1. The node receives front and back image URLs from the specified variables
2. It sends the images to the configured OCR provider for the selected country
3. The provider processes the images and extracts structured data
4. The extracted data is returned and optionally stored in a variable and/or package

Retry Logic

If the OCR provider fails, the node will retry the request up to the specified maximumRetries number (default: 3, range: 1-5). This helps handle temporary network issues or provider unavailability.

Package Storage

When storeInPackage is enabled, the OCR response is saved as a package in the system. This allows the data to be accessed later in the flow or in other workflows, and provides a historical record of the extracted information.

Identity Storage

When saveImagesToIdentity is enabled, the document images are attached to an identity record for permanent storage. This is useful for compliance and audit purposes.

Usage Examples

Example 1: Basic OCR Extraction

Configure the node to extract data and store the response in a variable:

1. Select the country (e.g., Ecuador) and provider (e.g., Nubarium)
2. Select the front image variable (e.g., cedula_front)
3. Select the back image variable (e.g., cedula_back)
4. Enable "Store Response in Variable" toggle
5. Select the response variable (e.g., ocr_response)

Example 2: Full Configuration with Package Storage

Configure the node with all storage options enabled:

1. Select country and provider
2. Select front and back image variables
3. Enable "Store Response in Variable" and select the variable
4. Enable "Store in Package" toggle
5. Switch to the "Advanced" tab
6. Enable "Save Images to Identity" toggle
7. Set "Maximum Retries" to 5

Example 3: Minimal Configuration

Configure the node for basic extraction without storing results:

1. Select country and provider
2. Select front and back image variables
3. Leave all storage toggles disabled
4. Optionally adjust "Maximum Retries" in the Advanced tab if needed

Flow Integration

Typical Flow Pattern

1. Before ID OCR Node:

   • User uploads document images (via file upload node or message attachment)
   • Images are stored in flow variables (e.g., cedula_front, cedula_back)

2. ID OCR Node:

   • Processes the images and extracts data
   • Stores results in specified variables/packages

3. After ID OCR Node:

   • Data validation node (to verify extracted information)
   • Identity creation/update node (to store identity information)
   • Conditional logic nodes (to route based on extracted data)
   • Data enrichment nodes (to cross-reference with other sources)

Connecting Nodes

The ID OCR Node typically connects to:

• Input: File upload nodes, message attachment handlers, or image collection nodes
• Output: Data validation nodes, identity management nodes, conditional routing nodes, or data enrichment nodes

Response Samples

The structure of the OCR response varies by country and provider. Below are sample responses for different country and provider combinations.

Ecuador - Nubarium

When processing Ecuadorian identity documents (cédula) with Nubarium, the response includes personal information, document details, and metadata. The response structure varies depending on the document version.

{
  "status": "OK",
  "validationCode": "eci1730483568.839952560564",
  "messageCode": 0,
  "documentIdentifier": "ECU_IdCard_2009",
  "className": "IdCard",
  "subclassName": "2009",
  "documentType": "ID_CARD",
  "country": "ECU",
  "data": {
    "dateBirth": "30 11 1980",
    "nationality": "COLOMBIANA",
    "gender": "MUJER",
    "maritalStatus": "CASADO",
    "identificationNumber": "1723196426",
    "lastName": "ORTIZ LOPEZ",
    "firstName": "JANETH",
    "placeBirth": "Colombia Ipiales",
    "partnerName": "EDUARDO DUARTE MORA",
    "barcode": "1723196426",
    "fingerprintId": "E2333V3222",
    "educationLevel": "SUPERIOR",
    "occupation": "EMPLEADO PRIVADO",
    "fatherName": "ORTIZ ORTIZ ALVARO",
    "motherName": "BUSTOS MYRIAM",
    "expiryDate": "21 05 2028",
    "issuePlace": "QUITO",
    "issueDate": "21 05 2018"
  }
}

Response Fields

Common Fields (both versions):

• status - Processing status (e.g., "OK")
• validationCode - Unique validation code for this processing
• messageCode - Message code indicating the result
• documentIdentifier - Identifier for the document type and version (e.g., "ECU_IdCard_2009" or "ECU_IdCard_2021")
• className - Document class (e.g., "IdCard")
• subclassName - Document subclass/version (e.g., "2009" or "2021")
• documentType - Type of document (e.g., "ID_CARD")
• country - Country code (e.g., "ECU")

Data Fields - 2009 Version:

• Personal Information: firstName, lastName, identificationNumber, dateBirth, placeBirth, nationality, gender, maritalStatus
• Family Information: fatherName, motherName, partnerName
• Additional Details: educationLevel, occupation, fingerprintId, barcode
• Document Details: issueDate, issuePlace, expiryDate

Data Fields - 2021 Version:

• Personal Information: firstName, lastName, identificationNumber, dateBirth, placeBirth, nationality, gender, maritalStatus, citizenshipStatus
• Family Information: fatherName, motherName, partnerName
• Additional Details: documentNumber, state, barcode, fingerprintId, bloodType, organDonor
• Document Details: issueDate, issuePlace, expiryDate
• MRZ Data: mrz (Machine Readable Zone), mrzValidation (validation results for MRZ fields)

Error Response Fields:

• status - Error status (e.g., "ERROR")
• validationCode - Unique validation code for this processing attempt
• messageCode - Error code indicating the type of error:
  • "1" - Document not identified
  • "2" - Missing input (e.g., "Document <front> not found" or "Document <back> not found")
• message - Descriptive error message indicating the specific error

Best Practices

• Image Quality: Ensure users upload clear, well-lit images of their documents. Provide guidance on image requirements in your flow.
• Variable Naming: Use descriptive variable names (e.g., cedula_front instead of img1) to make your flows more maintainable.
• Package Storage: Enable storeInPackage if you need to access the OCR data later or for audit purposes.
• Retry Configuration: Set maximumRetries to 3-5 for production environments to handle temporary provider issues.
• Identity Storage: Enable saveImagesToIdentity for compliance requirements or when you need to maintain a permanent record of submitted documents.
• Data Validation: Validate extracted data before using it in subsequent nodes to ensure data quality.