How to import and export

These how-tos cover the three ways data moves in and out of Soundcheck with an import file (also called UEF): importing a file, exporting a workspace, and mapping a spreadsheet. Each works from the app or over MCP, 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
A Soundcheck workspace to copy or restore	Export and restore a workspace
A CSV or spreadsheet from another tool	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 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. 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.

Export and restore a workspace

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.
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 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. In the app, drop the file on Settings → Data & knowledge → Import & export and follow Import your data and start running. Over MCP:

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.
get_import_field_catalog with the same target_type lists the fields a column can map to.
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.
preview_import shows new and updated rows and errors without writing.
commit_import writes the rows. It is confirmation-gated and can’t be undone from MCP.

Coming from another tool? The migration guides 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.

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.
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.
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:

// 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"
    }
  ]
}

{
  "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"
}

Field reference

Every field, with an example for each kind of record

Stability and versioning

What stays compatible within 2.x

Connect your AI (MCP)

Endpoints, sign-in and the full tool catalog

Coming from another system

CSV migration guides

Overview

Account & profile

Home

AI assistant

Gigs

Contracts

Client portal

Setlists

Calendar

Mailbox

Availability

Chat

Mobile app

Everyday tools

Imports

Organization

Teams

CRM

Leads

Offerings

How to import and export

Import a file

1. Get the format

2. Check the file

3. Preview against your workspace

4. Import

Export and restore a workspace

Map a CSV

Read the check results

Field reference

Stability and versioning

Connect your AI (MCP)

Coming from another system

​Import a file

​1. Get the format

​2. Check the file

​3. Preview against your workspace

​4. Import

​Export and restore a workspace

​Map a CSV

​Read the check results

​Related

Field reference

Stability and versioning

Connect your AI (MCP)

Coming from another system

Import a file

1. Get the format

2. Check the file

3. Preview against your workspace

4. Import

Export and restore a workspace

Map a CSV

Read the check results

Related