Docs Quickstart

Quickstart Guide

Estimated time: about 10 minutes.

Connect your first multi-vendor data feed, define a normalization config, and get clean canonical records out the other side.

Prerequisites

  • Python 3.9 or later
  • A HyperNorm account (free tier available at register)
  • At least one CSV file with vendor data, or a supported connector (Snowflake, BigQuery, Postgres, S3)
1

Install the SDK

Install the HyperNorm Python SDK with pip. The SDK supports Python 3.9 and later.

bash 
pip install hypernorm

The SDK bundles the normalization engine client, the CLI, and the connector drivers. If you only need the API client without the connectors, use pip install hypernorm-core.

2

Authenticate

Set your API key as an environment variable. You can find your API key in your HyperNorm account settings under API Keys.

bash 
export HYPERNORM_API_KEY="hn_live_..."

Or set it in Python directly:

python 
import hypernorm

client = hypernorm.Client(api_key="hn_live_...")
3

Define a normalization config

Create a YAML config that maps each vendor's field names to your canonical schema. In this example, two vendors have different field name conventions and one uses EUR amounts.

yaml: hn-config.yml 
version: 1
canonical_schema: canonical_v1.yml

sources:
  vendor_a:
    type: csv
    path: data/vendor_a.csv
    fields:
      company_name -> canonical_entity
      gross_revenue_usd -> revenue_usd
      last_updated -> updated_at  # format: MM/DD/YYYY

  vendor_b:
    type: csv
    path: data/vendor_b.csv
    fields:
      CompanyTitle -> canonical_entity
      TotalRevEUR -> revenue_usd  # currency: EUR -> USD
      UpdatedAt -> updated_at   # format: ISO8601

entity_resolution:
  target_field: canonical_entity
  threshold: 0.88
  review_below: 0.75
4

Run your first pipeline

Pass the config file to the HyperNorm client. The SDK runs normalization, applies entity resolution, and returns a list of canonical records.

python 
import hypernorm

client = hypernorm.Client()

result = client.run(config="hn-config.yml")

print(f"Normalized {result.record_count} records")
print(f"Merged {result.duplicates_merged} duplicate entities")
print(f"Review queue: {result.review_count} low-confidence matches")

# Access the normalized records
for record in result.records[:3]:
    print(record)
output 
Normalized 4281 records
Merged 312 duplicate entities
Review queue: 47 low-confidence matches

{'canonical_entity': 'Acme Corporation', 'revenue_usd': 142500.00, 'updated_at': '2026-03-14'}
{'canonical_entity': 'Tata Consultancy Services', 'revenue_usd': 89200.00, 'updated_at': '2026-03-12'}
{'canonical_entity': 'Infosys Ltd', 'revenue_usd': 76800.00, 'updated_at': '2026-03-11'}

What just happened

The pipeline ran three passes over your data:

  1. Schema inference and field mapping. HyperNorm read each source's schema, applied your field map to rename fields, applied the type coercion rules (string-to-decimal for revenue, date format parsing for dates), and converted currencies where declared.
  2. Blocking and fuzzy matching. For entity resolution, HyperNorm built phonetic and prefix blocking keys over the canonical_entity field, then ran Jaro-Winkler similarity on candidate pairs within each block. This reduced the comparison space from O(n^2) to O(n log n).
  3. Merge and review queue. Pairs above the threshold (0.88) were merged into a single canonical record. Pairs between 0.75 and 0.88 were placed in the review queue. Your 47 review-queue records are available at result.review_records and in the HyperNorm dashboard.

Next steps

API Reference All normalization and resolution endpoints with full request/response shapes. Connectors Connect Snowflake, BigQuery, Redshift, S3, Salesforce, and more. Multi-Vendor Feeds End-to-end walkthrough for three-vendor normalization with currency conversion.