KYC profiles CSV import API
kyc_profiles_v1
Import this template via API. Import KYC identity profiles from any CSV — legal name, DOB, national ID, risk rating. PII-aware: raw records never leave, only clamped samples.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=kyc_profiles_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Finance & Payments
- FHIR resource
- —
- Risk level
- high
- Fields
- 7 (2 required, 2 validated)
Why it exists
Why this template?
The KYC profiles template is the canonical schema for Know-Your-Customer identity records — the file an onboarding platform, a compliance-tooling export, or a sanctions-screening extract reduces to. Each row carries a subject_id (required), a legal_name (required), a date_of_birth validated against a sane range, an optional national_id, a country, a risk_rating enum (low / medium / high), and a verified_at timestamp. Compliance and onboarding teams reach for it when migrating a customer-due-diligence book between KYC vendors, when backfilling a risk-monitoring warehouse, and when consolidating profiles after an acquisition. It is `high` risk because every row is identifying PII — a legal name tied to a date of birth and a national ID. Schema-only mode is therefore the default ingress: raw KYC records never leave the customer; only headers and a handful of clamped sample cells are processed to decide the mapping.
subject_id and legal_name are required. date_of_birth runs a date_range validator that rejects pre-1900 and future dates — the silent killer of homegrown importers that mis-parse a two-digit year. national_id is checked against a permissive ^[A-Za-z0-9-]{4,20}$ shape so passports, DNIs, and codice fiscale all pass while obvious garbage is caught. risk_rating lands in {low, medium, high} or surfaces as an error. country and verified_at are optional. Hints cover DE / FR / IT / ES / EN so a multilingual compliance export does not escalate to the LLM.
Migration scenarios & common foreign headers
Migration scenarios for the KYC profiles template: porting a customer-due-diligence book between KYC providers (Onfido → Sumsub, Jumio → Veriff) without re-verifying everyone, backfilling a risk-monitoring warehouse with historical profiles for periodic-review scheduling, consolidating identity records after a fintech acquisition, and seeding a sanctions-rescreening pipeline. Foreign headers we routinely see: "Subjekt / Sujet / Soggetto / Sujeto / Name / Nom légal / Ragione sociale / Nombre legal / Geburtsdatum / Date de naissance / Data di nascita / DOB / Fecha de nacimiento / Ausweisnummer / Numéro national / Codice fiscale / National ID / DNI / Land / Pays / Paese / País / Risikostufe / Niveau de risque / Livello di rischio / Nivel de riesgo / Verifiziert am / Date de vérification / Verificato il / Verified at". The cascade resolves every one of these through the registered hints — no LLM call, no PII in the prompt.
Canonical columns
Schema
The canonical column set, with the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against.
| Column | Type | Required | Validators | Hints |
|---|---|---|---|---|
| subject_id | string | yes | — | subjekt · sujet · soggetto · subject · sujeto |
| legal_name | string | yes | — | name · nom légal · ragione sociale · legal name · nombre legal |
| date_of_birth | date | — | date_range (min 1900-01-01, max today) | geburtsdatum · date de naissance · data di nascita · dob · fecha de nacimiento |
| national_id | string | — | regex (^[A-Za-z0-9-]{4,20}$) | ausweisnummer · numéro national · codice fiscale · national id · dni |
| country | string | — | — | land · pays · paese · país |
| risk_rating | enum | — | — | risikostufe · niveau de risque · livello di rischio · risk rating · nivel de riesgo |
| verified_at | date | — | — | verifiziert am · date de vérification · verificato il · verified at · verificado el |
The cascade
How AdaptivMapr maps your headers to this template
Five layers run in order, cheapest first. Layer 1 (Statistics) auto-accepts headers that have been mapped the same way across past uploads. Layer 2 (Heuristic) compares your header to the column name, the optional label, and every registered hint (DE / FR / IT / EN / ES) after a Unicode-and-punctuation-normalising pass. Layer 3 (Fuzzy) catches typos and reordered words. Layer 4 (Semantic) uses cached embeddings to catch the long tail of paraphrases. Layer 5 (LLM) only fires on genuinely ambiguous columns, constrained to the template’s allowed column set so it cannot invent a field. When a layer auto-accepts, the lower-cost layers below it never run — that is the cost lever.
REST · POST /v1/uploads
Pass the template_id; the cascade picks up the rest.
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=kyc_profiles_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/kyc_profiles_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls are free and unlimited.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "kyc_profiles_v1",
headers: ["subject_id", "legal_name", "date_of_birth", "national_id"]
})MCP install instructions →Questions
FAQ — KYC profiles CSV import
Does KYC PII leave our environment during mapping?
No. Schema-only mode is the default: only headers and three clamped sample rows (≤80 chars each) are processed to decide the mapping. Full KYC profiles never touch our infrastructure unless you explicitly opt into full-data mode under an active subscription.
How is national_id validated across countries?
With a permissive shape check (^[A-Za-z0-9-]{4,20}$) so passports, DNIs, national numbers, and codice fiscale all pass while obvious garbage is rejected. For a strict per-country format, fork the template and tighten the regex.
Can I extend the risk_rating enum?
Yes — fork the template and edit enum_values. The canonical set is {low, medium, high} so cross-vendor risk reconciliation works without translation tables; finer-grained internal scales live in the workspace fork.
What does the date_of_birth validator catch?
It rejects dates before 1900-01-01 and any future date, which catches the most common parse failure — a two-digit year that resolves to 2068 instead of 1968. Valid dates round-trip untouched.