Docs · Quickstart
Your first import, in one API call.
POST a file, let the five-layer cascade propose mappings, confirm them, and commit. Schema-only mode (headers + ≤3 sample rows) keeps raw records on your side; full-data mode routes PHI through our BAA-covered infrastructure under a BAA. Every map draws down your prepaid token wallet.
Step 1
Get an API key
Mint a key in the dashboard after you top up a prepaid token wallet ($10 minimum, shared across our suite). Keys are HMAC-signed, self-contained credentials — there is no shared session store, and revocation is enforced by a server-side deny-list checked on every request. Pass it as a bearer token in the Authorization header on every call. A read-only listing call is the quickest way to confirm the key works:
curl https://api.adaptivmapr.com/v1/templates \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY"Twenty-three pre-built templates ship in the catalogue — ten healthcare (FHIR-aware) plus Core, CRM, and E-commerce. Pick the one whose shape matches your data, or browse the catalogue.
Step 2
POST your file
Send the file to POST /v1/uploads as multipart, with the template ID. The parser accepts CSV, TSV, XLSX, JSON, and XML. The response carries an upload_id, the detected columns, the parsed row count, three sample rows, and a 24h expires_at — uploads live in edge storage (Cloudflare KV) with a 24-hour TTL and then expire automatically.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=patient_demographics_v1" \
-F "file=@roster.csv"Prefer not to send a file? Schema-only mode lets you pass just the headers plus ≤3 sample rows (≤80 chars each) — that is all that leaves your environment, the safest way to map.
Step 3
The cascade proposes mappings
Run the match against your upload_id. Five layers fire cheapest-first — statistics → heuristic → fuzzy → semantic → LLM — and the moment a layer auto-accepts a column, the layers below it never run. Keep mode on "schema-only" to keep raw records on your side; switch to "full-data" only when you hold an active PHI subscription (layer 5 then routes to a PHI-eligible provider with X-PHI / X-Region).
POST /v1/uploads/upl_8f3a92c1/match
{ "target_schema": { "schema_id": "sch_patient_demographics_v1" },
"mode": "schema-only", "use_ai": true }The response is one proposal per detected column, each tagged with the source layer (statistics | heuristic | fuzzy | semantic | llm), a confidence, and reasoning — plus an unmapped list and the auto_accept_threshold.
[
{ "source_col": "Vorname",
"target_field": "first_name",
"confidence": 1.0,
"source": "heuristic",
"reasoning": "matched DE hint 'vorname'" }
/* ...plus an "unmapped" list and "auto_accept_threshold" */
]Step 4
Confirm or adjust
PATCH /v1/uploads/:id/mappings takes an array of {source_col, target_field, user_confirmed} overrides. Confirm the proposals you trust and correct the rest; corrections feed the statistics layer so the same header resolves without AI next time.
curl -X PATCH https://api.adaptivmapr.com/v1/uploads/upl_8f3a92c1/mappings \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-H "Content-Type: application/json" \
-d '[{ "source_col": "Geb", "target_field": "date_of_birth", "user_confirmed": true }]'For medium- and high-risk templates (e.g. patient_demographics_v1, lab_results_v1, claims_line_items_v1, drug_formulary_v1) the response sets requires_hitl: true and hitl_status: "pending_review" so you can gate your own commit workflow. The flag is advisory in v1 — it does not block the commit server-side.
{
"upload_id": "upl_8f3a92c1",
"mappings": [ /* ... */ ],
"requires_hitl": true,
"hitl_status": "pending_review"
}Step 5
Commit and use the rows
POST /v1/uploads/:id/commit validates every row against the template’s field validators and returns the mapped, validated rows inline (≤10k rows). Pass skip_invalid_rows to drop failures, or add a webhook object — {url, secret} — to stream rows in batches of 500 with an X-AdaptivMapr-Signature HMAC-SHA256 header (required above 10k rows).
curl -X POST https://api.adaptivmapr.com/v1/uploads/upl_8f3a92c1/commit \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "skip_invalid_rows": true }'Every commit is hashed and written to Chainlog with the mapping fingerprint and accepted/skipped counts, so you can reconstruct exactly which rows landed from which file.
Next
Keep going — put it in production.
Browse the template catalogue, drop AdaptivMapr into Cursor or Claude Desktop via the MCP server, or read the full documentation index. Full-data mode and BAA terms are covered on the pricing page.