Users CSV import API
users_v1
Import this template via API. Import users from any CSV into a canonical directory schema. Email-validated, role-enumerated, multilingual headers handled.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=users_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Core
- FHIR resource
- —
- Risk level
- low
- Fields
- 7 (2 required, 1 validated)
Why this template?
The Users template is the canonical schema for ingesting a user directory — the kind of file you get the morning of a migration, a SCIM dump, an HRIS export, or a CSV your customer assembled by hand the night before kickoff. It captures the seven attributes you actually want to keep across systems: a stable id, a validated email, given and family names split for personalisation, a role bounded by an enum so downstream RBAC does not break, a created_at timestamp parsed regardless of locale, and a country string for residency routing. The Users template is intentionally narrow — anything richer belongs in a profile table — so the cascade can lock onto it with minimal ambiguity. Teams use it as the first import on day one and the daily delta job from day two onwards.
Two hard guarantees: every row carries a validated email (RFC-style regex, not a vibe), and every role lands in {admin, member, viewer, owner} or surfaces as an error in the dry-run. Hints cover DE / FR / IT / ES / EN naming so a Swiss or Iberian export does not fall through to the LLM. The created_at format is auto-detected (ISO-8601, US, EU, epoch ms).
Migration scenarios & common foreign headers
The most common migration scenarios for the Users template are: importing a fresh SCIM export from Okta or JumpCloud into a new B2B SaaS account, backfilling a year of historical signups from a Postgres dump into a CDP, syncing a daily delta from a legacy LDAP into a modern auth system, and porting a customer base from one identity provider to another at acquisition close. The headers we see most often in the wild are "User ID / Email / E-Mail-Adresse / First Name / Vorname / Prénom / Last Name / Nachname / Nom / Role / Rolle / Created / Erstellt am / Country / Land / País". The cascade catches all of these without an LLM call because the multilingual hint set is exhaustive for the people-data domain.
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 |
|---|---|---|---|---|
| id | string | yes | — | — |
| yes | e-mail · mail · correo · courriel | |||
| first_name | string | — | — | vorname · prenom · prénom · nombre |
| last_name | string | — | — | nachname · nom · apellido · cognome |
| role | enum | — | — | rolle · role · rol · ruolo |
| created_at | date | — | — | — |
| country | string | — | — | land · pays · país · paese |
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=users_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/users_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: "users_v1",
headers: ["id", "email", "first_name", "last_name"]
})MCP install instructions →FAQ — Users CSV import
Does the Users template deduplicate on email?
It does not. Deduplication is a downstream concern; the template guarantees a parseable email per row so your upsert key works. Run AdaptivMapr → land in a staging table → upsert on lower(email).
What if my source has a "username" column but no email?
Map username to id and add an explicit `email` column with a placeholder. The Users template treats email as required because most downstream systems do.
Can the role enum be extended?
Yes — fork the template into your workspace via POST /v1/templates and edit `enum_values`. The forked template gets its own id and lives only in your workspace.
How are localised role names handled?
Add the localised values as `hints` on the role field. The heuristic layer normalises and matches them at zero cost; the LLM never sees the column.