Migrate an existing member base

The canonical import schema, the CSV template shape, a worked example from a realistic foreign roster export, and the partner API sequence for bulk migration. If your data looks like this, you migrate to 4D like this.

User Import is 4D’s self-serve path for bringing an existing member base onto the platform - a tenant admin’s console wizard (template → upload → map columns → dry-run → commit) and a partner backend’s bulk API, both driven by the same import engine and the same guarantees.

The guarantee

Every import, console or API, makes three promises up front:

Never overwrites. Existing values are never replaced. A matched row only fills fields and attributes that are currently empty (“fill-gaps-only”); anything already set on a member stays exactly as it is.
Never emails. Imports are silent. No invitation, welcome, or notification email is triggered as a side effect of any import job - that stays a deliberate, separate step your org owns.
Never deletes. A file only adds and enriches members; it is never treated as the full membership list, and nothing already in 4D is removed because it’s absent from an uploaded file.

Imported members are otherwise ordinary 4D members from the moment they’re created: same identity model, same wallet provisioning, same audit trail as a member created one at a time via the API or the console. They are not visually or functionally distinguishable from anyone else. They don’t receive consent rows at import time - like every member, they hit the consent gate the first time they sign in - and no role beyond the default member role is ever granted by an import.

Canonical row schema

Every row in an import - whichever way it arrives - is one member record. Column names in your source file don’t matter; only the target fields below do, since mapping is what routes your columns onto them.

Field	Type	Required	Example
`email`	string (email)	Yes	`mafalda.rocha@example.com`
`external_id`	string	No	`1042`
`first_name`	string	No	`Mafalda`
`last_name`	string	No	`Rocha`
`display_name`	string	No	`Mafalda R.`
`locale`	string	No	`pt-PT`
`country`	string (ISO 3166-1 alpha-2)	No	`PT`
`dob`	string (ISO 8601 date, `YYYY-MM-DD`)	No	`2005-03-14`
`attributes`	object (attribute key → value)	No	`{"phone": "+351 911 222 333"}`

Field rules, exactly:

email is the only required field, and is the row’s identity key - matching is by email, case-insensitively (trimmed and lowercased on write).
country, if present, must be an officially assigned ISO 3166-1 alpha-2 code. Case doesn’t matter on input (pt and PT both work); it’s stored uppercase. An unassigned two-letter pair (e.g. XX) is rejected.
dob, if present, must be a real ISO calendar date: it has to be an actual day (2024-02-30 doesn’t round-trip and is rejected), strictly in the past, and no earlier than the year 1900.
locale is free-form text - not validated against a fixed locale list.
attributes is a flat object keyed by attribute-registry key (see below). Any column not routed to a core field or an attribute key must be explicitly marked ignored in the mapping - there is no free-form bag left on the member record.

These are exactly the field rules the platform’s shared import schema enforces - reusing the same validators as single-record user creation (Create a user) - so import-time and create-time validation can never drift apart.

Attribute columns (the per-tenant part)

Beyond the fixed core fields above, every org has its own enabled set of Tier-B attributes - the same registry that drives your org’s profile fields. Attribute values are addressed by their key inside the attributes object, typed and validated per that key’s definition:

Type	Meaning	Example values
`text`	free-form string	`"+351 911 222 333"`
`number`	numeric	`12`
`date`	ISO date	`"2026-07-10"`
`boolean`	true/false	`true`
`single_choice`	exactly one of a fixed choice list	`"m"`
`multi_choice`	any subset of a fixed choice list	`["m", "l"]`

A single_choice/multi_choice attribute rejects any value outside its configured choice list - this is not a Zod-level check the wire schema can enforce (values are typed unknown on the wire), so it’s caught during dry-run validation against your org’s live registry, not at upload time. Only attributes your org has enabled (org_attribute_config) are valid mapping targets; an attribute key that’s unknown or disabled for your org fails the same way. The platform ships with a starter catalog you can enable per org - phone, gender, address.line1/address.city/address.postcode, favourite_team, shirt_size, emergency_contact - plus whatever your org has added.

The CSV template

The console wizard’s Import members → Download template button generates a CSV specific to your org: one column per core field, plus one column per attribute your org currently has enabled, a header-description row, and one filled-in example row so the expected shape is self-evident without reading this document. It’s regenerated from your live configuration every time you download it, so it can’t go stale the way a static example file would. The template is the fallback when you don’t want to map columns by hand: fill it in directly and every column already routes to the right field.

Caps and retention

Limit	Value
Max rows per import job	250,000
Max rows per staging chunk (one API call)	5,000
Concurrent import jobs per organization	1 (a second job is rejected until the first finishes or fails)
Uploaded rows and error reports retained	30 days, then purged automatically

The one-active-job limit exists to keep fill-gaps semantics and queue fairness simple - finish or abandon one import before starting the next for the same org. Retention is a fixed PII-minimization default: staged rows, mapping, and generated error reports are deleted 30 days after the job is created, whether or not it completed.

Matching, fill-gaps, and attach semantics

For every row, the import engine runs the same create-or-attach path a single POST /v1/users call uses:

No existing user with that email → a new user and member are created, with every field/attribute in the row written as given.
An existing user with that email, not yet a member of your org → they are attached as a member of your org.
An existing member of your org with that email → the row updates only what’s currently empty on that member - never a value that’s already set. external_id is backfilled only if it was null. Core profile fields (first_name, last_name, country, dob) are backfilled only if currently null/empty. Attribute values are written with an explicit fill_gaps write mode - if a value is already present for that attribute key, the row’s value for it is silently skipped, never overwritten - and stamped with provenance import so every value an import ever wrote is auditable as such.

Re-uploading the same (or a corrected) file is always safe: rows are matched by email every time, so nothing is ever duplicated, and existing data is never clobbered by a stale re-import.

Worked example: Clube Vega’s roster

Clube Vega is a small five-a-side club exporting members from their old spreadsheet system to onboard onto 4D. Their export, as it left that system:

ID Sócio	Nome Próprio	Apelido	Email	Data Nascimento	País	Telemóvel	Tamanho Camisola	Posição
1042	Mafalda	Rocha	mafalda.rocha@example.com	`14/03/2005`	Portugal	+351 911 222 333	M	Ala
1043	Diogo	Fernandes	diogo.fernandes@example.com	`02/11/1998`	Portugal	+351 912 333 444	L	Pivô
…

Portuguese headers, day/month/year dates, and a free-text country name - none of it matches 4D’s field names or formats yet. That’s expected; that’s what the mapping step is for.

Step 1 - fix what mapping can’t compute

Column mapping is a pick-and-rename operation only - it routes a source column to a target field, it doesn’t transform values. So before uploading, Clube Vega’s admin fixes the two things mapping can’t do for them: reformats “Data Nascimento” to ISO (14/03/2005 → 2005-03-14) and replaces “Portugal” with its ISO code (PT) - a spreadsheet find-and-replace on six rows. The ready-to-upload file is available at clube-vega-roster.csv:

ID Sócio,Nome Próprio,Apelido,Email,Data Nascimento,País,Telemóvel,Tamanho Camisola,Posição
1042,Mafalda,Rocha,mafalda.rocha@example.com,2005-03-14,PT,+351 911 222 333,m,Ala
1043,Diogo,Fernandes,diogo.fernandes@example.com,1998-11-02,PT,+351 912 333 444,l,Pivô
1044,Beatriz,Nogueira,beatriz.nogueira@example.com,2001-07-27,PT,+351 913 444 555,s,Guarda-Redes
1045,Rui,Almeida,rui.almeida@example.com,1999-05-30,PT,+351 914 555 666,xg,Ala
1046,Diogo,Fernandes,diogo.fernandes@example.com,1998-11-02,PT,+351 912 333 444,l,Pivô
1047,Sara,Teixeira,sara.teixeira@example.com,2003-09-09,PT,+351 915 666 777,xl,Fixo

(Row 1046 duplicating row 1043’s email, and row 1045’s shirt size xg, are left in deliberately - the export really did contain both mistakes, and the next steps show how 4D handles them.)

Step 2 - declare the mapping

Clube Vega’s admin doesn’t have a shirt_size field to invent; the club already enabled the platform’s starter phone and shirt_size attributes for their org. “Posição” (playing position) isn’t a 4D field at all, so it’s explicitly marked ignored rather than silently dropped:

{
  "columns": [
    { "sourceColumn": "ID Sócio", "target": "core_field", "fieldKey": "external_id" },
    { "sourceColumn": "Nome Próprio", "target": "core_field", "fieldKey": "first_name" },
    { "sourceColumn": "Apelido", "target": "core_field", "fieldKey": "last_name" },
    { "sourceColumn": "Email", "target": "core_field", "fieldKey": "email" },
    { "sourceColumn": "Data Nascimento", "target": "core_field", "fieldKey": "dob" },
    { "sourceColumn": "País", "target": "core_field", "fieldKey": "country" },
    { "sourceColumn": "Telemóvel", "target": "attribute", "attributeKey": "phone" },
    { "sourceColumn": "Tamanho Camisola", "target": "attribute", "attributeKey": "shirt_size" },
    { "sourceColumn": "Posição", "target": "ignored" }
  ]
}

Every core field in the schema table above and every enabled attribute is a legal fieldKey/attributeKey; anything else is rejected as an invalid mapping, so a typo’d target surfaces immediately instead of silently dropping a column.

Step 3 - upload and dry-run

The wizard parses the CSV in the browser, applies this mapping, and stages all six rows. Because every row is already valid against the core-field rules (a genuinely malformed email, date, or country would have been rejected right here, at upload - before anything is staged), staging succeeds outright. Nothing has been written to any member yet. Running the dry-run validates each staged row against the club’s live attribute registry and checks for duplicates within the file. Two of the six rows already known to have problems (from Step 1) surface here - this is exactly the class of error that can’t be caught by field-format rules alone:

Row	Outcome	Detail
1 (Mafalda)	Would create	new member
2 (Diogo, 1043)	Would create	new member
3 (Beatriz)	Would attach	`beatriz.nogueira@example.com` already has a 4D account from a prior self-registration; her existing `country` stays untouched, her (currently empty) `shirt_size` gets filled in
4 (Rui)	Invalid	`shirt_size: "xg"` is not one of the club’s configured choices (`xs`, `s`, `m`, `l`, `xl`, `xxl`)
5 (Diogo, 1046)	Invalid	duplicate email - row 2 already claims `diogo.fernandes@example.com` in this file
6 (Sara)	Would create	new member

Report summary: 6 rows, 4 valid (3 would create, 1 would attach), 2 invalid. Clube Vega’s admin can now either fix rows 4 and 5 in the source file and re-upload, or proceed and handle those two afterward from the error report - nothing forces a perfect file before value starts landing.

Step 4 - commit

Committing processes only the 4 valid rows. The 2 invalid rows are left exactly as flagged - commit never attempts a row the dry-run already rejected. Result: 3 members created, 1 member attached, 0 failed. Mafalda, Diogo, and Sara are new 4D members with their phone/shirt_size attributes set, provenance import. Beatriz’s existing record now additionally has shirt_size filled in - her country and everything else she’d already set is untouched.

Step 5 - the error report

Rows 4 and 5 are downloadable as CSV - original payload columns plus the row number and why it failed - so they can be corrected and re-uploaded as a new job without re-touching the 4 rows that already landed. error_code is the stable, documented contract; the error_message wording below is illustrative of the kind of detail returned and may change:

email,external_id,first_name,last_name,display_name,locale,country,dob,attributes,row_number,error_code,error_message
rui.almeida@example.com,1045,Rui,Almeida,,,PT,1999-05-30,"{""phone"":""+351 914 555 666"",""shirt_size"":""xg""}",4,ROW_ATTR_INVALID_VALUE,shirt_size: must be one of the allowed choices
diogo.fernandes@example.com,1046,Diogo,Fernandes,,,PT,1998-11-02,"{""phone"":""+351 912 333 444"",""shirt_size"":""l""}",5,ROW_DUPLICATE_IN_FILE,email already used by row 2 in this file

Partner API migration guide

Everything above is exactly what a partner backend drives programmatically - same engine, same guarantees, same field rules. This section walks the same Clube Vega example through the REST surface. Auth: every endpoint below takes Authorization: Bearer <api-key>, scoped to your organization; the caller must hold an admin role or an org-scoped service API key (identical to the permission model for single-user creation). Idempotency: POST /v1/imports, /validate, and /commit accept an Idempotency-Key header - replaying the same key with the same body returns the original response; the same key with a different body is rejected with IDEMPOTENCY_CONFLICT (409). The full request/response shapes below are generated from the same schemas the server validates against - see the API reference

so this walkthrough can’t drift from what the API actually accepts.

1. Create the job

curl -X POST "$API_BASE_URL/v1/imports" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clube-vega-2026-07-10-01" \
  -d '{
    "file_name": "clube-vega-roster.csv",
    "declared_total": 6,
    "mapping": { "columns": [ /* the 9 entries from Step 2 above */ ] }
  }'

201 Created:

{
  "id": "0198f2b1-2a00-7c31-9c47-df6a2ee9a001",
  "organization_id": "<your org id>",
  "created_by_id": null,
  "source": "api",
  "state": "staging",
  "mapping": { "columns": [ "..." ] },
  "file_name": "clube-vega-roster.csv",
  "declared_total": 6,
  "staged_rows": 0,
  "processed_rows": 0,
  "valid_rows": 0,
  "invalid_rows": 0,
  "created_count": 0,
  "attached_count": 0,
  "failed_count": 0,
  "expires_at": "2026-08-09T00:00:00.000Z",
  "created_at": "2026-07-10T00:00:00.000Z",
  "updated_at": "2026-07-10T00:00:00.000Z"
}

A 409 IMPORT_JOB_ACTIVE_EXISTS means your org already has a job in progress

finish or let it finish first.

2. Stage rows

Up to 5,000 rows per call, rowNumber 1-based and stable across chunks (it’s what keys the per-row idempotency and the error report). All 6 fit in one call here:

curl -X POST "$API_BASE_URL/v1/imports/0198f2b1-2a00-7c31-9c47-df6a2ee9a001/rows" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "rowNumber": 1, "payload": { "email": "mafalda.rocha@example.com", "external_id": "1042", "first_name": "Mafalda", "last_name": "Rocha", "country": "PT", "dob": "2005-03-14", "attributes": { "phone": "+351 911 222 333", "shirt_size": "m" } } },
      { "rowNumber": 2, "payload": { "email": "diogo.fernandes@example.com", "external_id": "1043", "first_name": "Diogo", "last_name": "Fernandes", "country": "PT", "dob": "1998-11-02", "attributes": { "phone": "+351 912 333 444", "shirt_size": "l" } } },
      { "rowNumber": 3, "payload": { "email": "beatriz.nogueira@example.com", "external_id": "1044", "first_name": "Beatriz", "last_name": "Nogueira", "country": "PT", "dob": "2001-07-27", "attributes": { "phone": "+351 913 444 555", "shirt_size": "s" } } },
      { "rowNumber": 4, "payload": { "email": "rui.almeida@example.com", "external_id": "1045", "first_name": "Rui", "last_name": "Almeida", "country": "PT", "dob": "1999-05-30", "attributes": { "phone": "+351 914 555 666", "shirt_size": "xg" } } },
      { "rowNumber": 5, "payload": { "email": "diogo.fernandes@example.com", "external_id": "1046", "first_name": "Diogo", "last_name": "Fernandes", "country": "PT", "dob": "1998-11-02", "attributes": { "phone": "+351 912 333 444", "shirt_size": "l" } } },
      { "rowNumber": 6, "payload": { "email": "sara.teixeira@example.com", "external_id": "1047", "first_name": "Sara", "last_name": "Teixeira", "country": "PT", "dob": "2003-09-09", "attributes": { "phone": "+351 915 666 777", "shirt_size": "xl" } } }
    ]
  }'

200 OK: { "staged": 6 }. Every payload here must already satisfy the field rules in the schema table

a malformed email, date, or country rejects the whole chunk with 422 VALIDATION_ERROR (field-level details included) before anything is staged. The two problems in this example (bad shirt_size choice, duplicate email) are the kind that can only be caught once your org’s live attribute registry and the rest of the file are known - that’s what the next step is for.

3. Validate (dry-run)

curl -X POST "$API_BASE_URL/v1/imports/0198f2b1-2a00-7c31-9c47-df6a2ee9a001/validate" \
  -H "Authorization: Bearer $API_KEY"

202 Accepted - the job moves to validating and runs asynchronously; poll GET /v1/imports/{id} until state is validated:

{ "state": "validated", "staged_rows": 6, "processed_rows": 6, "valid_rows": 4, "invalid_rows": 2, "...": "..." }

Fetch the two problem rows directly:

curl "$API_BASE_URL/v1/imports/0198f2b1-2a00-7c31-9c47-df6a2ee9a001/rows?state=invalid" \
  -H "Authorization: Bearer $API_KEY"

{
  "rows": [
    { "id": "...", "job_id": "...", "row_number": 4, "state": "invalid", "error_code": "ROW_ATTR_INVALID_VALUE", "error_message": "shirt_size: must be one of the allowed choices", "user_id": null, "...": "..." },
    { "id": "...", "job_id": "...", "row_number": 5, "state": "invalid", "error_code": "ROW_DUPLICATE_IN_FILE", "error_message": "email already used by row 2 in this file", "user_id": null, "...": "..." }
  ],
  "next_cursor": null
}

error_code is the stable, documented contract here too - the error_message wording (like the CSV example in Step 5 above) is illustrative and may change.

4. Commit

curl -X POST "$API_BASE_URL/v1/imports/0198f2b1-2a00-7c31-9c47-df6a2ee9a001/commit" \
  -H "Authorization: Bearer $API_KEY"

202 Accepted - moves to committing, then asynchronously to completed. Poll GET /v1/imports/{id} again:

{ "state": "completed", "valid_rows": 4, "created_count": 3, "attached_count": 1, "failed_count": 0, "...": "..." }

409 IMPORT_JOB_INVALID_STATE means the job isn’t validated yet - commit only ever runs against a completed dry-run, so an unvalidated row is never written. If you’d rather skip the explicit /validate call, POST /commit with { "dry_run": false } on a still-staging job triggers the same validate-then-commit sequence as one round trip; it still runs both phases internally and still requires a follow-up call (or poll) once validation finishes before the actual commit happens.

5. Fetch the error report

curl "$API_BASE_URL/v1/imports/0198f2b1-2a00-7c31-9c47-df6a2ee9a001/error-report" \
  -H "Authorization: Bearer $API_KEY"

200 OK, Content-Type: text/csv - the same file shown in Step 5 above. This is also the console’s download link (cookie-authenticated instead of an API key; same permission gate).

Endpoint summary

Method	Path	Purpose	Success
`POST`	`/v1/imports`	Create a job (starts `staging`)	`201`
`POST`	`/v1/imports/{id}/rows`	Stage a chunk (≤5,000 rows)	`200`
`POST`	`/v1/imports/{id}/validate`	Seal + start async dry-run	`202`
`POST`	`/v1/imports/{id}/commit`	Commit a validated job	`202`
`GET`	`/v1/imports/{id}`	Status + counts	`200`
`GET`	`/v1/imports/{id}/rows`	Per-row outcomes, paged, `?state=` filter	`200`
`GET`	`/v1/imports/{id}/error-report`	Invalid + failed rows as CSV	`200`

Get started

Concepts

Walkthroughs

SDK

The guarantee

Canonical row schema

Attribute columns (the per-tenant part)

The CSV template

Caps and retention

Matching, fill-gaps, and attach semantics

Worked example: Clube Vega’s roster

Step 1 - fix what mapping can’t compute

Step 2 - declare the mapping

Step 3 - upload and dry-run

Step 4 - commit

Step 5 - the error report

Partner API migration guide

1. Create the job

2. Stage rows

3. Validate (dry-run)

4. Commit

5. Fetch the error report

Endpoint summary

See also

​The guarantee

​Canonical row schema

​Attribute columns (the per-tenant part)

​The CSV template

​Caps and retention

​Matching, fill-gaps, and attach semantics

​Worked example: Clube Vega’s roster

​Step 1 - fix what mapping can’t compute

​Step 2 - declare the mapping

​Step 3 - upload and dry-run

​Step 4 - commit

​Step 5 - the error report

​Partner API migration guide

​1. Create the job

​2. Stage rows

​3. Validate (dry-run)

​4. Commit

​5. Fetch the error report

​Endpoint summary

​See also

The guarantee

Canonical row schema

Attribute columns (the per-tenant part)

The CSV template

Caps and retention

Matching, fill-gaps, and attach semantics

Worked example: Clube Vega’s roster

Step 1 - fix what mapping can’t compute

Step 2 - declare the mapping

Step 3 - upload and dry-run

Step 4 - commit

Step 5 - the error report

Partner API migration guide

1. Create the job

2. Stage rows

3. Validate (dry-run)

4. Commit

5. Fetch the error report

Endpoint summary

See also