Integrations

Auto-Tagging Setup Guide

This guide explains how to automatically tag borrowers based on their profile data, and how to use those tags to control which loan products they can see and apply for.

What Are Auto-Tags?

Auto-tags are labels automatically assigned to borrowers based on their profile data (employer, phone number, income, loan history, etc.). They are used to:

• Control product visibility — only show a loan product to borrowers who match certain criteria
• Segment borrowers — group borrowers by employer, region, income, risk, etc.
• Automate decisions — route applications based on borrower attributes

There are two types of auto-tags:

1. Built-in tags — computed automatically on every tag sync. No setup needed.
2. Spec-driven tags — you create rules (called "Attribute Specs") that match borrower profile fields against patterns you define.

Part 1: Built-in Auto-Tags (No Setup Required)

These tags are computed automatically by the system on every tag sync. You can use them immediately in product visibility rules.

Employment & Income Tags

Loan History Tags

How to Use Built-in Tags in Product Rules

Go to Admin → Loan Products → [your product] → Tag Rules, and add a visibility rule:

Important: Built-in tag values are uppercase. When writing visibility rules, use uppercase values (e.g., PERMANENT, not Permanent).

Part 2: Spec-Driven Auto-Tags (Custom Rules)

Spec-driven tags let you create custom rules that match borrower profile fields against patterns you define. You create these in Admin → Tags → Auto-Tagging Specs.

How Spec-Driven Tags Work

1. You create an Attribute Spec with:

   • An Attribute Key (the tag category, e.g., STAFF_GROUP)
   • A Source Field (which borrower profile field to check, e.g., employer_name)
   • A Transform Type (how to match: Pattern Match or Passthrough)
   • Patterns (the rules to match against)
   • A Fallback Action (what to do if no pattern matches)

2. During tag sync, the system evaluates each spec against the borrower's profile.

3. The first matching pattern wins, and its tag value is assigned.

4. If no pattern matches, the fallback action determines what happens.

Available Attribute Keys

You can use any of these whitelisted keys for spec-driven tags:

Available Source Fields

You can match patterns against any of these borrower profile fields:

Borrower fields: primary_phone, secondary_phone, primary_email, display_name, borrower_number, kyc_status, borrower_type

Individual fields: national_id_number, national_id_type, first_name, last_name, gender, nationality, date_of_birth, marital_status

Business fields: company_name, business_registration_number, tax_id, company_type, industry_sector, primary_contact_phone, primary_contact_email

Group fields: group_name, group_type, chairperson_phone, secretary_phone, operating_area

Employment fields: employer_name, employment_status, job_title, industry, years_employed, monthly_income

Financial fields: monthly_income, monthly_expenses, other_income

Match Modes

Fallback Actions

Part 3: Step-by-Step Setup Examples

Example 1: Civil Servants (Government Employees)

Goal: Create a salary loan product only for civil servants.

Step 1: Create the Auto-Tag Spec

1. Go to Admin → Tags → Auto-Tagging Specs
2. Click Add Spec
3. Fill in:
   • Attribute Key: STAFF_GROUP
   • Transform Type: Pattern Match
   • Source Field: employer_name
4. Add these patterns (check Ignore Case on each):

1. Fallback Action: skip (non-government employees get no tag)
2. Click Create Spec

Step 2: Run Tag Sync

1. Go to Admin → Tags → Bulk Sync
2. Click Sync All Borrowers
3. Wait for the sync to complete — civil servants will now have STAFF_GROUP = GOVERNMENT

Step 3: Create the Product Visibility Rule

1. Go to Admin → Loan Products → [your Salary Loan] → Tag Rules
2. Add these rules:

1. Save. Now only permanent civil servants in good standing can see this product.

Step 4 (Optional): Include Local Government

If you also want municipal employees to see the product, change the first rule to:

Step 5 (Optional): Sub-Segment by Ministry

If you want separate products for different government departments, use distinct tag values instead of one GOVERNMENT bucket:

Then create separate products with rules like REQUIRE STAFF_GROUP EQ HEALTH for a health-worker-only loan.

Example 2: MNO Staff (Econet / NetOne Employees)

Goal: Tag borrowers who work for mobile network operators based on their phone number.

Step 1: Create the Auto-Tag Spec

1. Go to Admin → Tags → Auto-Tagging Specs → Add Spec
2. Fill in:
   • Attribute Key: MNO_STAFF
   • Transform Type: Pattern Match
   • Source Field: primary_phone

Important: Phone numbers are normalized to international format before matching. Local 0712801234 becomes +263712801234. So your patterns should use the +263 prefix.

1. Add these patterns:

1. Fallback Action: skip
2. Click Create Spec

Step 2: Run Tag Sync and Add Product Rule

After syncing, add this rule to your MNO staff product:

Example 3: Employer-Specific Loan (MOU Partner)

Goal: Create a loan product only for employees of a specific employer with whom you have an MOU.

Step 1: Create the Auto-Tag Spec

1. Go to Admin → Tags → Auto-Tagging Specs → Add Spec
2. Fill in:
   • Attribute Key: MOU
   • Transform Type: Pattern Match
   • Source Field: employer_name
3. Add patterns for each MOU partner:

1. Fallback Action: default:FALSE
2. Click Create Spec

Step 2: Add Product Rule

Now only borrowers whose employer matches one of your MOU patterns can see this product.

Example 4: Region by National ID (Zimbabwe)

Goal: Tag borrowers by region based on their national ID number.

Step 1: Create the Auto-Tag Spec

1. Attribute Key: REGION
2. Transform Type: Pattern Match
3. Source Field: national_id_number
4. Add patterns (Zimbabwean national IDs contain region codes):

1. Fallback Action: default:OTHER_REGION
2. Click Create Spec

Example 5: Borrower Type Passthrough

Goal: Restrict a nano loan product to individual borrowers only.

Step 1: Create the Auto-Tag Spec

1. Attribute Key: SEGMENT
2. Transform Type: Passthrough
3. Source Field: borrower_type
4. Fallback Action: skip
5. Click Create Spec

The borrower's type (INDIVIDUAL, GROUP, COMPANY) is copied directly as the tag value.

Step 2: Add Product Rule

Example 6: Valid National ID Check

Goal: Tag borrowers with valid Zimbabwean national ID format.

1. Attribute Key: ID_PATTERN
2. Transform Type: Pattern Match
3. Source Field: national_id_number
4. Add pattern:

1. Fallback Action: default:INVALID_ID
2. Click **Create Spec`

Then add a product rule: REQUIRE ID_PATTERN EQ VALID_ZW_NATIONAL_ID

Part 4: Editing and Managing Specs

Editing a Spec

1. Go to Admin → Tags → Auto-Tagging Specs
2. Click the pencil icon next to the spec you want to edit
3. Update the fields and click Save Changes

Editing a spec updates it in place — the version number stays the same. Use this for small corrections.

Creating a New Version

If you create a new spec with the same Attribute Key as an existing one, the system:

1. Deactivates the old version (keeps it for audit history)
2. Saves the new version as active
3. Increments the version number

Use this when you want to replace a spec entirely while preserving the old one for audit.

Deleting a Spec

1. Click the trash icon next to the spec
2. Confirm the deletion

This soft-deletes the spec. Existing borrower tags are not affected — they remain until the next tag sync.

Running a Tag Sync

After creating or editing specs, run a sync to apply the new rules to existing borrowers:

• Single borrower: Go to the borrower profile → Sync Tags
• All borrowers: Go to Admin → Tags → Bulk Sync → Sync All

New borrowers are tagged automatically when their profile is created or updated.

Part 5: Common Patterns for Nano and Salary Products

Nano Product — Recommended Tag Rules

Salary Product — Recommended Tag Rules

Combining Built-in and Spec-Driven Tags

You can mix built-in and spec-driven tags in the same product. For example, a salary loan for civil servants might use:

REQUIRE  STAFF_GROUP EQ GOVERNMENT     (spec-driven — you created this)
REQUIRE  EMPLOYMENT  EQ PERMANENT      (built-in — automatic)
REQUIRE  SALARY_BAND IN HIGH,PREMIUM   (built-in — automatic)
EXCLUDE  BLACKLISTED EQ TRUE           (built-in — automatic)

Part 6: Tips and Common Issues

Tip 1: Always Check "Ignore Case" for Text Fields

Borrower profile fields like employer_name are stored as typed (mixed case). Without Ignore Case checked, Ministry of* will not match "ministry of Finance". Always check Ignore Case for text fields unless you need exact case matching.

Tip 2: Use International Phone Format

Phone numbers are normalized to international format before pattern matching. Local 0712801234 becomes +263712801234. Always write phone patterns with the +263 prefix:

• Correct: +26371* matches NetOne numbers
• Incorrect: 071* will not match (the normalized number starts with +263)

Tip 3: Built-in Tag Values Are Uppercase

Built-in tags like EMPLOYER, EMPLOYMENT, SALARY_BAND, INDUSTRY are uppercased automatically. When writing visibility rules for these tags, use uppercase values:

• Correct: REQUIRE EMPLOYMENT EQ PERMANENT
• Incorrect: REQUIRE EMPLOYMENT EQ Permanent

Spec-driven tag values use whatever casing you define in the pattern's Tag Value field.

Tip 4: First Matching Pattern Wins

If a borrower matches multiple patterns in a spec, only the first match is used. Order your patterns from most specific to least specific if there's overlap.

Tip 5: Employer Name Spelling Matters

Spec patterns match against whatever the borrower or loan officer typed in the employer_name field. If someone enters "Ministry Of Finance" vs "Ministry of Finance", Ignore Case handles capitalization, but typos like "Ministry o Finance" will not match. Train loan officers to use consistent employer names, or use broader wildcard patterns like Ministry*.

Tip 6: Test with a Real Borrower

After creating a spec, find a borrower who should match, go to their profile, and run a single-borrower tag sync. Check that the expected tag appears. If it doesn't:

1. Verify the source field has a value for that borrower
2. Verify the pattern matches the actual field value (check casing, spacing, format)
3. Check the sync log for skip reasons

Tip 7: Use Fallback Actions Carefully

• skip — the borrower gets no tag. Use this when the tag is optional (e.g., MNO_STAFF — only MNO staff should be tagged).
• default:VALUE — the borrower gets a default tag value. Use this when every borrower should have a value (e.g., default:OTHER for a REGION spec where non-matching borrowers should be tagged "OTHER").

API Reference (For Advanced Users)

All tag spec operations are available via API:

Example: Create a Civil Servant Spec via API

curl -X POST https://your-instance/api/v1/tag-specs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "attribute_key": "STAFF_GROUP",
    "source_type": "profile",
    "transform_type": "pattern_match",
    "transform_config": {
      "field": "employer_name",
      "patterns": [
        {"pattern": "Ministry of*", "match_mode": "wildcard", "tag_value": "GOVERNMENT", "ignore_case": true},
        {"pattern": "Zimbabwe Republic Police*", "match_mode": "wildcard", "tag_value": "GOVERNMENT", "ignore_case": true},
        {"pattern": "ZESA*", "match_mode": "wildcard", "tag_value": "GOVERNMENT", "ignore_case": true}
      ]
    },
    "fallback_action": "skip"
  }'

Support

For questions or issues:

• Contact the Hiana Loans support team
• Check the LOAN_PRODUCT_SETUP_GUIDE.md for general product configuration
• Check the SALARY_LOAN_PRODUCT_SETUP_GUIDE.md for salary loan workflow setup
• Check the NANO_LOAN_PRODUCT_SETUP_GUIDE.md for nano loan workflow setup
• Check the PRODUCT_TAGS_FEES_GUIDE.md for the full engineering reference of tags, fees, and late fee rules