> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to import and export

> Check and import a Soundcheck import file (UEF), export a workspace, and map a CSV, from the app, the API or an AI agent

These how-tos cover the three ways data moves in and out of Soundcheck with an [import file](https://docs.soundchecklive.io/features/imports/universal-event-format.md) (also called UEF): importing a file, exporting a workspace, and mapping a spreadsheet. Each works from the app or over [MCP](https://docs.soundchecklive.io/integrations/mcp-server.md), so a person and an agent follow the same steps.

| You have | Use |
| - | - |
| An import file from a feed or an agent | [Import a file](#import-a-file) |
| A Soundcheck workspace to copy or restore | [Export and restore a workspace](#export-and-restore-a-workspace) |
| A CSV or spreadsheet from another tool | [Map a CSV](#map-a-csv) |

MCP tool names changed when the catalog was merged. The old names still work: `get_uef_schema` is now `get_import_format`, `validate_uef` is `check_import_file`, and `import_uef` is `import_file`.

***

## Import a file

### 1. Get the format

Call `get_import_format` on the public MCP endpoint (`https://mcp.soundchecklive.io/public/mcp`, no login). It returns the JSON Schema for the served `schema_version`, two example documents and a docs URL. The [field reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md) lists the same fields for people. 

### 2. Check the file

Call `check_import_file` with the file's contents as an object or a JSON string (up to 256 KiB). It runs locally, needs no login and saves nothing. Fix every error it reports before you go on; see [Read the check results](#read-the-check-results).

`check_import_file` can't see your workspace, so a valid result doesn't promise a clean import. The preview in the next step checks the file against your records, positions and permissions.

### 3. Preview against your workspace

On the member MCP endpoint (`https://mcp.soundchecklive.io/mcp`), call `preview_import_file` with the file. Nothing is written. It returns how many records would be new and how many would update existing ones, plus any errors. 

### 4. Import

Call `import_file` with the same file. It writes the records into your workspace and may email organization invitations to team members in `members[]`. It is confirmation-gated, so your agent asks you before it writes, and it only runs on an organization you own or manage. Public MCP doesn't have it.

In the app, the same import is **Settings → Data & knowledge → Import & export → Import a Soundcheck file**. Over the REST API, it is `POST /api/v1/organizations/{orgId}/imports/uef` with the document as the body.

Importing the same file again is safe: records match by `external_id`, then by natural key, so a second run updates instead of duplicating. See [Identity and safe re-imports](https://docs.soundchecklive.io/features/imports/universal-event-format.md#identity-and-safe-re-imports).

***

## Export and restore a workspace

1. Export. Call `export_workspace` on the member MCP endpoint, or click **Download workspace** on **Settings → Data & knowledge → Import & export**. MCP returns one import file, version 2.0 document with `source.type: "EXPORT"`; the app download is a zip with that document in `uef/workspace.json` plus a CSV per catalog.
2. Restore. Pass the file to `preview_import_file` and then `import_file` on the destination organization, or upload the zip on **Settings → Data & knowledge → Import & export**.

An export is only what import can recreate: ledger lines, files, branding and integration secrets stay out, and money fields are withheld from callers who can't view finances. [Export a workspace and restore it](https://docs.soundchecklive.io/features/imports/workspace-export.md) lists exactly what comes back.

***

## Map a CSV

A spreadsheet doesn't need to be turned into an import file first. Its columns are mapped to the same field names, the same paths as in the [field reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md).

In the app, drop the file on **Settings → Data & knowledge → Import & export** and follow [Import your data and start running](https://docs.soundchecklive.io/features/imports/overview.md). Over MCP:

1. `create_import_from_paste` with the CSV or TSV text and a `target_type`: `EVENT`, `LEAD`, `INVENTORY` or `MEMBER`. It creates an import job and parses the rows.
2. `get_import_field_catalog` with the same `target_type` lists the fields a column can map to.
3. `map_import` with the job ID. Leave out `mapping` to let Soundcheck map the columns itself, or pass a `mapping` object whose `columns` list each source `column` header with its `uef_field` path. For gigs, `row_grouping: "group_by_external_id"` inside `mapping` folds several rows with the same external ID into one gig.
4. `preview_import` shows new and updated rows and errors without writing.
5. `commit_import` writes the rows. It is confirmation-gated and can't be undone from MCP.

Coming from another tool? The [migration guides](https://docs.soundchecklive.io/features/imports/coming-from.md) give the export steps and column mappings for Planning Center, Back On Stage, Master Tour, Stagera and LASSO.

***

## Read the check results

`check_import_file` returns:

| Key | Meaning |
| - | - |
| `valid` | `true` when there are no errors and no missing required fields. |
| `errors` | Each problem, with a `path` such as `events[0].days[1].date`, a `message`, and a `severity` of `error` or `warning`. A warning doesn't make the file invalid. |
| `missing_required` | The paths of required fields that are missing, also listed in `errors`. |
| `schema_version` | The version of the format the file was checked against. See [Stability and versioning](https://docs.soundchecklive.io/features/imports/import-format-stability.md#how-the-checker-reports-the-version). |

Match on `path` and `severity`. The wording of `message` can change.

The checks run in two passes. The first checks the shape: the version, known keys, types, required fields and formats. If that fails, it reports those errors and stops, so a second run can show more errors once you fix the first ones.

| Kind of error | Example message | What to do |
| - | - | - |
| Wrong major version | `schema_version must be "2.0" (any later 2.x is accepted)…` | Write the file in the 2.0 shape. |
| Unknown key | `guest_total is not a UEF 2.0 field; import rejects it` | Remove it, or use the field it should be from the [field reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md). |
| Missing required field | `is required` | Add the field. The path is also in `missing_required`. |
| Wrong type or format | `must be string`, `must match pattern …` | Send the type the reference lists. Calendar days are `YYYY-MM-DD`. |
| Number out of range | `must be <= 5` | Use a whole number inside the range in the reference's Type column. |
| Empty file | `The UEF document has no records to import…` | Add at least one record to a collection. |
| Broken ref | `names ballroom, which is not a ref in venues` | Add the record with that `ref`, or fix the pointer. |
| Repeated ref or external ID | `repeats ref …`, `repeats events[0]; one external_id names one record` | Give each record its own `ref` and `external_id`. |
| Value not in an option list | `… is not one of ACTIVE, ARCHIVED, …` | Use one of the listed values. Letter case and padding are forgiven. |
| Bad email, currency, amount or place | `must be an email address`, `must be an ISO 4217 currency code such as USD`, `must be a positive amount under 10,000,000,000 with at most two decimal places`, `must be a latitude between -90 and 90` | Fix the value. |
| Gig dates and times | `is before event_date`, `is outside the gig's dates`, `a multi-day gig carries dates only; give times on its days`, `must be a 24-hour HH:MM time` | See the gig rules in [Universal Event Format](https://docs.soundchecklive.io/features/imports/universal-event-format.md). |
| Venue or client given twice | `use venue_ref or an inline venue, not both` | Keep one form. |
| Paid payable or receivable | `a payable or receivable is marked paid by recording its payment in Soundcheck, not on import` | Import it as `UNPAID` and record the payment in Soundcheck. |
| Member role | A role no role matches is an error; a misspelt one is a warning naming the role it was read as. | Use Member, Admin, Finance or Gig Coordinator. |

For example, this gig has an end date before its start, a venue ref with no venue, and a lowercase currency code:

```jsonc theme={null}
// Not valid: shown with the result check_import_file returns for it.
{
  "schema_version": "2.0",
  "events": [
    {
      "title": "Hillcrest Foundation Gala",
      "event_date": "2026-09-12",
      "end_date": "2026-09-11",
      "venue_ref": "ballroom",
      "currency": "usd"
    }
  ]
}
```

```json theme={null}
{
  "valid": false,
  "errors": [
    {
      "path": "events[0].venue_ref",
      "message": "names ballroom, which is not a ref in venues",
      "severity": "error"
    },
    {
      "path": "events[0].currency",
      "message": "must be an ISO 4217 currency code such as USD",
      "severity": "error"
    },
    {
      "path": "events[0].end_date",
      "message": "is before event_date",
      "severity": "error"
    }
  ],
  "missing_required": [],
  "schema_version": "2.0"
}
```

***

## Related

> **[Field reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md)**
>
> Every field, with an example for each kind of record

> **[Stability and versioning](https://docs.soundchecklive.io/features/imports/import-format-stability.md)**
>
> What stays compatible within 2.x

> **[Connect your AI (MCP)](https://docs.soundchecklive.io/integrations/mcp-server.md)**
>
> Endpoints, sign-in and the full tool catalog

> **[Coming from another system](https://docs.soundchecklive.io/features/imports/coming-from.md)**
>
> CSV migration guides


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.