Universal Event Format (UEF)

Universal Event Format (UEF) is the JSON shape every import path lands in before normalized tables are written. The wizard on Settings → Organization → Imports (/settings/organization/imports) builds one UEF document per 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, start with Import your data and start running. You don’t need to touch UEF directly. This page is for partners building feeds and for engineers extending the importer.

AI file ingestion, a CheckAI Private Preview feature for existing beta testers only, produces UEF too. When CheckAI extracts a contract or call sheet, it emits the same document with source.type: "INGESTION", and can also propose ledger_items (deposits, balances, expenses) and leads alongside the events, members, and schedule shown below.

Top-level shape

{
  "schema_version": "1.0",
  "source": {
    "type": "SPREADSHEET",
    "name": "spring-2026-bookings.xlsx",
    "ingested_at": "2026-05-11T15:00:00Z",
    "import_job_id": "imp_..."
  },
  "events": [
    { /* UEFEvent */ },
    ...
  ]
}

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; "INGESTION" for AI file ingestion; "EXPORT" for a workspace export. Partners use their own identifier.
events[]: the unit the writer iterates over.

UEFEvent

Required fields are minimal. Everything else is opt-in.

Field	Type	Required	Notes
`title`	string	yes	Name of the gig, e.g. “Acme Corp Holiday Party”.
`event_date`	string (`YYYY-MM-DD`)	yes	The calendar date the event takes place.
`external_id`	string	no	Stable identifier from the source system. Strongly recommended: drives upsert vs. insert on re-import. Defaults to `{import_job_id}:{row_index}` when omitted.
`event_type`	string	no	Operator-defined category (Wedding, Corporate, Concert, Festival, …).
`start_time`	string (RFC3339)	no	e.g. `2026-06-15T19:00:00-04:00`.
`end_time`	string (RFC3339)	no	Same format as `start_time`.
`status`	string	no	`ACTIVE` (default), `DRAFT`, `TEMPLATE`, `ARCHIVED`.
`currency`	string (ISO 4217)	no	Defaults to `USD`.
`default_performance_fee`	decimal	no	Numeric, e.g. `500.00`.
`payment_terms`	string	no	Free-text, e.g. “Net 30”, “On the day”.
`notes`	string	no	Public notes visible to crew and clients.
`admin_notes`	string	no	Internal-only notes.
`location` / `location_name`	string	no	Use these when there’s no separate venue column.
`latitude` / `longitude`	decimal	no	Optional event-level coordinates.
`place_id`	string	no	Google Places ID, when known.
`venue`	object	no	See UEFVenue below.
`customer`	object	no	See UEFCustomer below.
`members[]`	array	no	See UEFMember below.
`schedule_items[]`	array	no	Timeline rows (load-in, sound check, …).
`metadata`	object	no	Arbitrary source-system fields preserved for audit.

UEFVenue

Field	Type	Notes
`name`	string	Required when `venue` is present.
`external_id`	string	Improves dedup; use the source system’s venue ID when available.
`address`, `city`, `state`, `postal_code`, `country`	string
`phone_number`, `website`	string
`latitude`, `longitude`, `place_id`	various
`notes`, `metadata`	string / object

UEFCustomer

Field	Type	Notes
`name`	string	Required when `customer` is present.
`external_id`	string	Source-system customer ID.
`email`, `phone`, `website`	string
`contacts[]`	array	Optional list of contacts on the customer record (name, email, phone, title, `is_primary`).
`notes`, `metadata`	string / object

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.

Field	Type	Notes
`first_name`, `last_name`	string
`email`	string	One of `email` or `phone_number` is required for invitation.
`phone_number`	string	Same as above.
`position`	string	Human-readable; resolved against the organization’s positions.
`performance_fee`	decimal	Per-performer override; otherwise the event default applies.
`fee_notes`	string
`call_order`	integer	`0` = primary, `1+` = backup.
`external_id`	string	Improves dedup across re-imports.

UEFScheduleItem

Field	Type	Notes
`name`	string	Required.
`start_time`	string (RFC3339)	Required.
`end_time`	string (RFC3339)	Optional.
`order`	integer	Defaults to natural order.
`notes`	string	Optional.

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 and idempotence

External IDs keep re-imports safe. The writer matches in this order:

By external_id (when present).
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. 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. Spreadsheet Crew import still requires email on each roster row. That is separate from UEF member invitation identity (email or phone).

Field catalog

The wizard mapping UI pulls its dropdown from the same field catalog. Fetch the live catalog from the API:

GET /v1/organizations/{orgId}/imports/catalog

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.

Overview

Account & profile

Home

AI assistant

Gigs

Contracts

Client portal

Setlists

Calendar

Mailbox

Availability

Chat

Mobile app

Everyday tools

Imports

Organization

Teams

CRM

Leads

Universal Event Format (UEF)

Top-level shape

UEFEvent

UEFVenue

UEFCustomer

UEFMember

UEFScheduleItem

Datetime conventions

Identity and idempotence

Field catalog

​Top-level shape

​UEFEvent

​UEFVenue

​UEFCustomer

​UEFMember

​UEFScheduleItem

​Datetime conventions

​Identity and idempotence

​Field catalog

Top-level shape

UEFEvent

UEFVenue

UEFCustomer

UEFMember

UEFScheduleItem

Datetime conventions

Identity and idempotence

Field catalog