Skip to main content
The Universal Event Format (UEF) is the canonical shape that all operator data is transformed into before it reaches Soundcheck’s normalized tables. The wizard at /imports produces one UEF document per import job; partner integrations (n8n CRM sync, custom feeds) and AI file ingestion emit the same shape, so every path shares writer semantics. If you’re just importing a spreadsheet, you don’t need to touch UEF directly — the mapping UI hides it. This page is for partners building feeds and for engineers extending the importer.
AI file ingestion produces UEF too. When CheckAI extracts a contract or call sheet, it emits the same document with source.type: "INGESTION" — and can additionally propose ledger_items (deposits, balances, expenses) and leads alongside the events, members, and schedule shown below.

​
Top-level shape

  • schema_version — bump only when the shape changes in a way that older mappings would not survive. Current value: 1.0.
  • source.type — "SPREADSHEET" or "PASTE" for the wizard; partners use their own identifier.
  • events[] — the unit the writer iterates over.

​
UEFEvent

The required fields are minimal — anything else is opt-in.

​
UEFVenue

​
UEFCustomer

​
UEFMember

One crew member on the event. To produce an invitation, a member must have either email or phone_number — rows without a contact channel are skipped at write time.

​
UEFScheduleItem

​
Datetime conventions

  • event_date — YYYY-MM-DD (no time component).
  • start_time, end_time, schedule_items[].start_time/end_time — RFC3339 with offset, e.g. 2026-06-15T19:00:00-04:00.
  • source.ingested_at — RFC3339 UTC.

​
Identity & idempotence

External IDs are the heart of safe re-imports. The writer matches in this order:
  1. By external_id (when present).
  2. By natural key — (title, event_date) for events, name (case-insensitive, scoped to the organization) for venues and customers.
When both fields are present, external_id wins. That’s how renaming an event in the source system stays linked instead of becoming a duplicate. Invitations are deduped at the database level by partial unique indexes on (eventId, lower(email)) and (eventId, phoneNumber), with ON CONFLICT DO NOTHING. Re-running the same import is always safe.

​
Field catalog

The wizard mapping UI pulls its dropdown from the same field catalog. You can fetch the live catalog from the API:
This returns one entry per mappable path (e.g. events[].event_date, events[].venue.name, events[].members[].email) with type, required flag, and a short description. The catalog is the source of truth — if it isn’t listed there, the importer can’t write to it.