# GEDCOM import and export

Import a GEDCOM file into a workspace, and export a workspace as a GEDCOM file or GEDZIP archive.


GEDCOM is how genealogy programs exchange family trees. Both directions run in the background: you start a job, then poll it. See [Background jobs](/developers/docs/background-jobs) for the polling pattern.

## Import

### 1. Upload the file

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/imports \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -F "file=@family-tree.ged"
```

A `.ged` file can be up to 75 MB, a `.gdz` (GEDZIP) archive up to 300 MB. A GEDZIP archive named `.zip` is accepted too. You get `202` with the job's `id` in status `analyzing`. Nothing is added to the workspace yet.

The upload is not idempotent: a retry uploads the file again. It counts against both your request and upload [rate limits](/developers/docs/rate-limits).

### 2. Check the analysis

Poll `GET .../gedcom/imports/{import_id}` until `status` is `awaiting_confirmation`. Then:

- `analysis` says what the file holds: people, families, sources, events, media, and how many people are already in this workspace from an earlier import (`existing_people`, `changed_people`). Sources are counted but not imported: an import adds people and families.
- `cap_check`, `cap_check_skip` and `cap_check_changed` say whether each import mode fits your plan's person limit (`allowed`).

### 3. Confirm or cancel

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/imports/IMPORT_ID/confirm \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: confirm-import-1" \
  -H "Content-Type: application/json" \
  -d '{"mode": "skip"}'
```

- `all` (the default) imports everyone in the file.
- `skip` leaves out people already in the workspace.
- `changed` is like `skip`, but also imports existing people who changed in the file. It needs the Researcher plan or above.

You get `202`. Poll the job until `status` is `completed`, when `result` says what was added. An import that would pass your plan's person limit is refused with `403 forbidden`.

To cancel instead, send `DELETE .../gedcom/imports/{import_id}`. Nothing is added and the uploaded file is deleted. An import left unconfirmed expires after about an hour, and its file is deleted then.

## Export

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/exports \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: export-1" \
  -H "Content-Type: application/json" \
  -d '{"version": "7.0.18", "format": "ged", "redact_living": true}'
```

All fields are optional:

- `version`: `7.0.18` (default) or `5.5.1`.
- `format`: `ged` (default) for the tree as text, or `gdz` for a GEDZIP archive with the record images.
- `filename`: the base name of the downloaded file. Default `kleiobase-export`.
- `redact_living`: leave out the details of living people. `GET .../gedcom/exports/redaction-preview` lists who that is.

You get `202` with the job's `id`. Poll `GET .../gedcom/exports/{export_id}` until `status` is `ready`, then download the file from `download.url`. The URL works for 5 minutes; poll again for a new one. Finished exports are deleted after 7 days.

- One export at a time per account. Starting another while one is being prepared returns `409 conflict`.
- No email is sent. The app emails a download link; the API does not.
- An archived workspace can still be exported.

Canonical: https://kleiobase.com/developers/docs/gedcom