API Reference
REST API for normalization, entity resolution, and schema management. All endpoints require a Bearer token. Base URL: https://api.hypernormforai.com/v1.
Authentication
Authorization: Bearer hn_live_.../normalize
Normalize one or more source payloads against a canonical schema. Applies field mapping, type coercion, unit conversion, and date format normalization in a single pass.
Request body
{
"config_id": "cfg_a7b2c",
"sources": [
{
"source_key": "vendor_a",
"records": [
{ "company_name": "Acme Corp", "gross_revenue_usd": 142500 }
]
}
]
}Response
{
"run_id": "run_9f3d2",
"record_count": 1,
"records": [
{
"canonical_entity": "Acme Corp",
"revenue_usd": 142500.00,
"_source": "vendor_a",
"_source_id": "vendor_a:0"
}
]
}/resolve
Run entity resolution on a normalized dataset. Applies blocking, fuzzy matching, and returns canonical entity groups with confidence scores. Use after /normalize or pass pre-normalized records directly.
Request body
{
"run_id": "run_9f3d2",
"entity_field": "canonical_entity",
"threshold": 0.88,
"review_below": 0.75
}Response
{
"entities": [
{
"canonical_id": "ent_3a7f",
"canonical_name": "Acme Corporation",
"confidence": 0.97,
"duplicates_merged": 3
}
],
"review_count": 12
}/schemas
List all canonical schemas registered to your account. Returns schema ID, name, version, and field list.
{
"schemas": [
{
"id": "sch_v1",
"name": "canonical_v1",
"version": 1,
"fields": ["canonical_entity", "revenue_usd", "updated_at"]
}
]
}/schemas/infer
Infer a canonical schema from one or more source samples. Useful when starting from scratch or when a vendor has changed their schema format. Returns a suggested canonical schema and field mapping drafts.
{
"samples": [
{
"source_key": "vendor_a",
"records": [
{ "company_name": "Acme", "gross_revenue_usd": 142500 }
]
}
]
}Authentication and rate limits
All API requests must include a Bearer token in the Authorization header. API keys are generated in your account settings under API Keys. Never expose live keys in client-side code.
| Plan | Rate limit | Monthly record budget |
|---|---|---|
| Starter (Free) | 100 req/min | 500,000 records |
| Developer | 1,000 req/min | 10,000,000 records |
| Team | 5,000 req/min | 100,000,000 records |
| Enterprise | Custom | Unlimited |
When you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header. Monthly record overages on Developer and Team are billed per additional million records.