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"}`
`labels`	array of strings	No	`["volunteer", "u18 squad"]`

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).
labels holds up to 20 labels per row. Each label is trimmed, runs of whitespace collapse to one space, and it is lowercased; after that it must be 1 to 64 characters, with no ; and no control characters. An import only ever adds labels: a label a member already has is kept, and none is removed.
Any column not routed to a core field, an attribute key or labels must be explicitly marked ignored in the mapping - there is no free-form bag left on the member record.

An import checks email, country and dob with the same validators as single-record user creation (Create a user), so a value that creation accepts, an import accepts too.

Attribute columns (the per-tenant part)

Beyond the fixed core fields above, every org has its own enabled set of 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 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, job_title, 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" }
  ]
}

A mapping entry has one of four targets:

`target`	Extra field	Routes the column to
`core_field`	`fieldKey`	One of the core fields in the schema table above
`attribute`	`attributeKey`	One attribute key in the row’s `attributes`
`labels`	none	The row’s `labels`. In the console wizard the cell holds labels separated by `;`, for example `volunteer;u18 squad`
`ignored`	none	Nothing; the column is dropped on purpose

A fieldKey outside the core fields, or a target outside these four, is rejected as an invalid mapping, so a typo’d target surfaces immediately instead of silently dropping a column. An attributeKey that is unknown or not enabled for your org fails at the dry-run, as ROW_ATTR_UNKNOWN on each row that carries it. Over the API you send rows already shaped by your mapping, so labels arrives as an array in each row’s payload.

Step 3 - upload and dry-run

The wizard parses the CSV in the browser, applies this mapping, and stages all six rows. Staging does not judge the values: a malformed email, date or country is staged like any other row, and the dry-run marks that row invalid with its own error code (see Row error codes). Nothing has been written to any member yet. Running the dry-run validates each staged row’s email, date and country, checks for duplicate emails and external ids within the file, and checks attributes against the club’s live attribute registry. Two of the six rows already known to have problems (from Step 1) surface here:

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. The report carries the core fields and attributes; it has no labels column. error_code is the stable contract, and every code is listed in Row error codes. 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,Duplicate email or external_id within this import 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). Every import endpoint below is in the API reference, generated from the OpenAPI document the API serves. Use it for the complete request and response shapes.

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 }. Staging checks the shape of each payload, not its values. A field name outside the schema table, a field of the wrong JSON type, a rowNumber that is not a positive integer, or a label that breaks the label rules rejects the whole chunk with 422 VALIDATION_ERROR (field-level details included) before anything is staged. A chunk of more than 5,000 rows, or one that would take the job past 250,000 rows, is 422 IMPORT_ROW_LIMIT. A malformed email, date or country is staged and then fails its own row at validation. The two problems in this example (bad shirt_size choice, duplicate email) are dry-run findings too - 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": "Duplicate email or external_id within this import file", "user_id": null, "...": "..." }
  ],
  "next_cursor": null
}

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

Row error codes

A row error fails that row only, never the job. Rows the dry-run rejects have state: "invalid"; rows that fail while committing have state: "failed". Both appear in the error report.

`error_code`	Set at	Meaning
`ROW_EMAIL_INVALID`	Validate	`email` is not a valid address
`ROW_DOB_INVALID`	Validate	`dob` is not a real `YYYY-MM-DD` date in the past, from 1900 on
`ROW_COUNTRY_INVALID`	Validate	`country` is not an assigned ISO 3166-1 alpha-2 code
`ROW_DUPLICATE_IN_FILE`	Validate	An earlier row in the same job has the same email or `external_id`
`ROW_ATTR_UNKNOWN`	Validate	An attribute key is unknown, retired, or not enabled for your org
`ROW_ATTR_INVALID_VALUE`	Validate	An attribute value does not fit its definition, such as a choice outside the list
`ROW_LABEL_INVALID`	Validate	A label breaks the label rules, or the row has more than 20. Rows staged through the API are refused at staging instead, so this code only appears as a fallback
`ROW_EXTERNAL_ID_CONFLICT`	Commit	The `external_id` already belongs to another member of your org
`ROW_COMMIT_FAILED`	Commit	The create-or-attach write for this row failed for another reason

The dry-run checks a row in this order and records the first problem only: email, date, country, duplicate, attributes, labels. The job-level errors reject the whole request instead: 409 IMPORT_JOB_ACTIVE_EXISTS, 409 IMPORT_JOB_INVALID_STATE and 422 IMPORT_ROW_LIMIT.

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

Content API

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)

Row error codes

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)

​Row error codes

​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)

Row error codes

4. Commit

5. Fetch the error report

Endpoint summary

See also