Finance & Payments pack

KYC profiles CSV import API

Import KYC identity profiles from any CSV — legal name, DOB, national ID, risk rating. PII-aware: raw records never leave, only clamped samples.

Try in Workbench Quickstart

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"

→ 7 canonical fields · 2 validated · high risk

Canonical columns

The whole schema, printed as it ships.

Every canonical column, 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. This is the shipped definition, not a summary of it.

kyc_profiles_v1

fields: 7
required: 2
validated: 2
hints: 34

Canonical column	Type	Required	Validators	Header hints the cascade matches
`subject_id`	string	yes	—	subjektsujetsoggettosubjectsujeto
`legal_name`	string	yes	—	namenom légalragione socialelegal namenombre legal
`date_of_birth`	date	—	`date_range`	geburtsdatumdate de naissancedata di nascitadobfecha de nacimiento
`national_id`	string	—	`regex`	ausweisnummernuméro nationalcodice fiscalenational iddni
`country`	string	—	—	landpayspaesepaís
`risk_rating`	enumlowmediumhigh	—	—	risikostufeniveau de risquelivello di rischiorisk ratingnivel de riesgo
`verified_at`	date	—	—	verifiziert amdate de vérificationverificato ilverified atverificado el

Read the same definition as JSON at GET /v1/templates/kyc_profiles_v1. A hint match resolves on layer 2 — no LLM call, no token spend, just the flat per-map fee. Hover a validator id to see what it checks.

7 canonical fields
2 required
2 validated
34 header hints, 5 languages

Why it exists

Written for the file you actually receive.

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 & the foreign headers they ship

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.

The cascade

Six layers, and the cheapest one wins.

Layers run in order and stop the moment a column resolves. That is the single biggest cost lever in the system: a column caught on layer 2 never reaches the metered layer 5.

L1Statisticsno LLM
Auto-accepts a header that past confirmations already resolved the same way, at {minN:100, minRatio:0.95} or {minN:20, minRatio:1.00}.
L2Heuristicno LLM
Normalises accents, punctuation and whitespace, then compares against the column name, the label, and every registered hint (DE / FR / IT / EN / ES).
L3Fuzzyno LLM
Token-set ratio plus Levenshtein over the normalised strings. Auto-accepts at 0.80 — it absorbs typos and reordered words.
L4Semanticcheap, cached
Embedding cosine between the header and the field’s label + hints. Catches the long tail of paraphrases.
L5LLMmetered
Everything still unresolved goes up in ONE batched, collision-aware call, constrained to this template’s column set so it cannot invent a field.

Try it

One template id, two ways in.

REST for your import pipeline, MCP for your editor. Both run the same cascade and both honour the same schema-only clamp.

REST · POST /v1/uploads

Name the template; the cascade picks up the rest. The canonical definition is read-only at GET /v1/templates/kyc_profiles_v1.

bash

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"

→ upload created · mappings ready · confirm before commit

MCP · Cursor / Claude Desktop

Drop AdaptivMapr into your editor and call the same cascade as a tool. Schema-only calls leave only column names and up to three clamped sample rows.

mcp

// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
  template_id: "kyc_profiles_v1",
  headers: ["subject_id", "legal_name", "date_of_birth", "national_id"]
})

schema-only · headers and ≤3 rows, 80 chars each

MCP install instructions

high-risk template

The mappings response comes back flagged. PATCH /uploads/:id/mappings returns requires_hitl: true and hitl_status: "pending_review" so you can hold the commit in your own workflow — the flag is a signal, not a queue we run. Schema-only mode (headers plus at most three sample rows, each clamped to 80 characters) is a data-minimization mode enforced at the HTTP edge. Full-data mode routes the metered layer-5 call to phi-cloud in-region under a BAA, costs 20% more on the whole map charge, and stays locked until the workspace accepts the BAA/NDA in Settings → Security & Data.

How the wallet is charged

Questions

KYC profiles CSV import — FAQ

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.

Map kyc profiles in production — without shipping raw records.

Schema-only mode leaves only headers and a handful of clamped samples. Add full-data when you need row-level AI, routed in-region under a BAA.

Get an API key More Finance & Payments templates →