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

# Clients, venues and directories import fields

> Import file fields (version 2.0) for clients, venues, inventory, acts, guests, hotels, vehicles and sponsors, with an example for each.

These are the fields for clients, venues, inventory, acts, guests, hotels, vehicles and sponsors. How to read a row, the fields at the top of the file and the other records are in [Import file fields](https://docs.soundchecklive.io/features/imports/import-format-reference.md). Every field here is Stable for version 2.x.

***

## Clients (`clients[]`)

Clients (customers) that projects and gigs are for. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it, and an `external_id` (its ID in your other system) so importing the file again updates that record instead of adding a copy.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `clients[].ref` | string | | Stable | Name for this client inside the document, used by client\_ref. |
| `clients[].external_id` | string | | Stable | Stable id from your CRM. Strongly recommended — it is what makes a re-import update rather than duplicate. |
| `clients[].name` | string | Yes | Stable | Company or person who books you — also the dedup key within your organization. |
| `clients[].email` | email | | Stable | Client email. |
| `clients[].phone` | phone | | Stable | Client phone. |
| `clients[].website` | string | | Stable | Website. |
| `clients[].status` | string | | Stable | Status. |
| `clients[].notes` | string | | Stable | Notes. |
| `clients[].address` | string | | Stable | Address. |
| `clients[].city` | string | | Stable | City. |
| `clients[].state` | string | | Stable | State / region. |
| `clients[].postal_code` | string | | Stable | Postal code. |
| `clients[].country` | string | | Stable | Country. |
| `clients[].contacts[].name` | string | | Stable | A person at this client. Several rows naming the same client build one customer with several contacts. |
| `clients[].contacts[].email` | email | | Stable | Contact email. |
| `clients[].contacts[].phone` | phone | | Stable | Contact phone. |
| `clients[].contacts[].title` | string | | Stable | Contact title. |
| `clients[].contacts[].is_primary` | boolean | | Stable | Marks this person as the main point of contact for the client. |
| `clients[].contacts[].labels` | list of refs → `labels[].ref` | | Stable | Labels on the contact, by labels\[].ref. Import adds them and never takes a label off. |
| `clients[].provenance` | object | | Stable | Where this client came from. Kept with the document; not written to the client. |

### Example: clients

A client with a ref, an external ID and a primary contact.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PARTNER",
    "name": "acme-booking-feed"
  },
  "clients": [
    {
      "ref": "riverside",
      "external_id": "CRM-1042",
      "name": "Riverside Events Collective",
      "email": "bookings@riverside.example.com",
      "city": "Austin",
      "state": "TX",
      "contacts": [
        {
          "name": "Jordan Lee",
          "email": "jordan@riverside.example.com",
          "is_primary": true
        }
      ]
    }
  ]
}
```

***

## Venues (`venues[]`)

Venues that gigs take place at. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it, and an `external_id` (its ID in your other system) so importing the file again updates that record instead of adding a copy.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `venues[].ref` | string | | Stable | Name for this venue inside the document, used by venue\_ref. |
| `venues[].external_id` | string | | Stable | Stable id from your source system. Strongly recommended — it is what makes a re-import update rather than duplicate. |
| `venues[].name` | string | Yes | Stable | Name of the venue — also the dedup key within your organization. |
| `venues[].address` | string | | Stable | Street address. |
| `venues[].city` | string | | Stable | City. |
| `venues[].state` | string | | Stable | State / region. |
| `venues[].postal_code` | string | | Stable | Postal code. |
| `venues[].country` | string | | Stable | Country. |
| `venues[].phone_number` | phone | | Stable | Phone. |
| `venues[].website` | string | | Stable | Website. |
| `venues[].latitude` | decimal | | Stable | Latitude. |
| `venues[].longitude` | decimal | | Stable | Longitude. |
| `venues[].place_id` | string | | Stable | When present this is the strongest possible match key for a venue. |
| `venues[].photo_url` | string | | Stable | A public http(s) image URL for the venue's baseline photo. Only fills a venue that has no photo yet. |
| `venues[].notes` | string | | Stable | Notes. |
| `venues[].dock` | string | | Stable | Loading dock. |
| `venues[].elevator` | string | | Stable | Elevator. |
| `venues[].parking` | string | | Stable | Parking. |
| `venues[].load_in` | string | | Stable | Load-in. |
| `venues[].load_out` | string | | Stable | Load-out. |
| `venues[].access_code` | string | | Stable | Door/gate code. Stored privately on your organization, never on the shared venue record. |
| `venues[].capacity` | integer ≥ 0 | | Stable | Capacity. |
| `venues[].venue_type` | string | | Stable | Venue type. |
| `venues[].stage_size` | string | | Stable | Stage size. |
| `venues[].wifi` | string | | Stable | WiFi. |
| `venues[].dressing_rooms` | integer ≥ 0 | | Stable | Dressing rooms. |
| `venues[].green_room` | boolean | | Stable | Green room. |
| `venues[].house_tech` | list of strings | | Stable | Comma-separated list — e.g. house PA, lighting desk, monitors. |
| `venues[].restrictions` | list of strings | | Stable | Comma-separated list — curfews, noise limits, rigging limits. |
| `venues[].amenities` | list of strings | | Stable | Comma-separated list. |
| `venues[].contact_name` | string | | Stable | Contact name. |
| `venues[].contact_role` | string | | Stable | Contact role. |
| `venues[].contact_email` | email | | Stable | Contact email. |
| `venues[].stages[].ref` | string | | Stable | Name for this stage inside the document, used by events\[].stages\[].stage\_ref. A workspace export writes the stage's ID here, so importing that export back into the same workspace matches each stage to its own record before it looks at names. |
| `venues[].stages[].name` | string | Yes | Stable | A stage, room or spot in the venue. An active stage's name is unique within its venue, so a stage with no matching ref matches the venue's stage with the same name, ignoring case. A matched stage is not changed. When a venue lists its stages, its own stage\_size and house\_tech are not applied on import, because they describe its first stage. |
| `venues[].stages[].capacity` | integer 0–1000000 | | Stable | Stage capacity. |
| `venues[].stages[].stage_size` | string | | Stable | Stage size. |
| `venues[].stages[].house_tech` | list of strings | | Stable | Stage house tech. |
| `venues[].stages[].notes` | string | | Stable | Stage notes. |
| `venues[].provenance` | object | | Stable | Where this venue came from. Kept with the document; not written to the venue. |

### Example: venues

A venue with its production details.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PARTNER",
    "name": "acme-booking-feed"
  },
  "venues": [
    {
      "ref": "amphitheater",
      "name": "Riverside Amphitheater",
      "address": "100 River Rd",
      "city": "Austin",
      "state": "TX",
      "postal_code": "78701",
      "country": "US",
      "capacity": 2500,
      "dock": "Two dock doors on the north side",
      "green_room": true,
      "house_tech": [
        "Stage manager",
        "Lighting director"
      ],
      "contact_name": "Sam Ortiz",
      "contact_email": "production@amphitheater.example.com",
      "stages": [
        {
          "ref": "main",
          "name": "Main stage",
          "capacity": 2500,
          "stage_size": "60x40"
        },
        {
          "ref": "lawn",
          "name": "Lawn stage",
          "notes": "Acoustic sets only"
        }
      ]
    }
  ]
}
```

***

## Inventory (`inventory[]`)

Gear the organization owns.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `inventory[].name` | string | Yes | Stable | Name of the equipment/gear item. Rematch key when external\_id is absent. |
| `inventory[].external_id` | string | | Stable | Stable identity for rematch. Spreadsheet id or Soundcheck record id. |
| `inventory[].category` | string | | Stable | Operator-defined category (Audio, Lighting, Staging, etc.). |
| `inventory[].quantity` | integer ≥ 0 | | Stable | Number of units owned (stock quantity). Defaults to 1. |
| `inventory[].labels` | list of refs → `labels[].ref` | | Stable | Labels on the gear item, by labels\[].ref. Import adds them and never takes a label off. |

### Example: inventory

A piece of gear with its count.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "SPREADSHEET",
    "name": "warehouse.csv"
  },
  "inventory": [
    {
      "name": "Shure SM58",
      "external_id": "INV-0007",
      "category": "Microphones",
      "quantity": 12
    }
  ]
}
```

***

## Acts (`acts[]`)

Performing acts that run-of-show items can name. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it. Acts match by name, ignoring case; `external_id` is kept for reference and does not match a record.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `acts[].ref` | string | | Stable | Name for this act inside the document, used by act\_ref. |
| `acts[].external_id` | string | | Stable | The act's ID in the source system. |
| `acts[].name` | string | Yes | Stable | The act's name. Acts match by name, ignoring case. |
| `acts[].is_external` | boolean | | Stable | True when the act is booked from outside the organization. |
| `acts[].notes` | string | | Stable | Act notes. |

### Example: acts

An outside act that a run-of-show cue can name by ref.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PASTE",
    "name": "festival-lineup"
  },
  "acts": [
    {
      "ref": "headliner",
      "name": "The Velvet Hours",
      "is_external": true
    }
  ]
}
```

***

## Guests (`guests[]`)

People on the org's guest list. A gig's guest list names them with guest\_ref. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it. A guest with an email or phone matches an existing guest by it; a guest with neither matches a guest of the same name who has no contact details either. `external_id` is kept for reference and does not match a record.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `guests[].ref` | string | | Stable | Name for this guest inside the document, used by guest\_ref. |
| `guests[].external_id` | string | | Stable | The guest's ID in the source system, kept for reference. Guests match by email, phone or name, not by this ID. |
| `guests[].name` | string | Yes | Stable | The guest's name. A guest with an email or phone matches an existing guest by it; one without matches by name on each gig. |
| `guests[].email` | email | | Stable | Guest email. |
| `guests[].phone` | phone | | Stable | Guest phone. |
| `guests[].dietary` | string | | Stable | Dietary needs. |
| `guests[].tags` | list of strings | | Stable | Labels the org files the guest under, such as VIP. |
| `guests[].notes` | string | | Stable | Guest notes. |

### Example: guests

Guests the org keeps, a gig's guest list that names them by ref, and a guest source listed for reference (import ignores it).

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PASTE",
    "name": "wedding-guest-list"
  },
  "guests": [
    {
      "ref": "jordan",
      "name": "Jordan Lee",
      "email": "jordan@example.com",
      "dietary": "Vegetarian",
      "tags": [
        "VIP"
      ]
    },
    {
      "ref": "sam",
      "name": "Sam Park"
    }
  ],
  "events": [
    {
      "title": "Lee wedding",
      "event_date": "2026-12-12",
      "guest_sources": [
        {
          "provider": "LUMA",
          "label": "Luma RSVPs",
          "external_url": "https://lu.ma/lee-wedding"
        }
      ],
      "guest_list": [
        {
          "guest_ref": "jordan",
          "role": "HONOREE",
          "plus_count": 1,
          "meal_choice": "Fish"
        },
        {
          "guest_ref": "sam",
          "rsvp_status": "MAYBE"
        },
        {
          "name": "Walk-in",
          "pass_type": "COMP"
        }
      ]
    }
  ]
}
```

***

## Hotels (`hotels[]`)

Hotels the org has saved. A gig's hotel stays name them with hotel\_ref. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it. A hotel with a place\_id joins the shared directory record for that place; one without matches a hotel the org has saved with the same name, ignoring case. A matched hotel is not changed. `external_id` is kept for reference and does not match a record.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `hotels[].ref` | string | | Stable | Name for this hotel inside the document, used by hotel\_ref. A workspace export writes the saved hotel's ID here, so importing that export back into the same workspace matches each hotel to its own record before it looks at names. |
| `hotels[].external_id` | string | | Stable | The hotel's ID in the source system, kept for reference. |
| `hotels[].name` | string | Yes | Stable | Hotel name. |
| `hotels[].place_id` | string | | Stable | Google place ID. A hotel with one joins the shared directory record for that place. |
| `hotels[].street` | string | | Stable | Hotel street address. |
| `hotels[].unit` | string | | Stable | Hotel suite or unit. |
| `hotels[].city` | string | | Stable | Hotel city. |
| `hotels[].state` | string | | Stable | Hotel state. |
| `hotels[].postal_code` | string | | Stable | Hotel postal code. |
| `hotels[].country` | string | | Stable | Hotel country. |
| `hotels[].phone` | phone | | Stable | Hotel phone. |
| `hotels[].website` | string | | Stable | Hotel website. |
| `hotels[].brand` | string | | Stable | Hotel brand. |
| `hotels[].check_in_time` | string | | Stable | Hotel check-in time. |
| `hotels[].check_out_time` | string | | Stable | Hotel check-out time. |
| `hotels[].notes` | string | | Stable | The org's own notes on the hotel. |
| `hotels[].room_block_code` | string | | Stable | Room block code. |
| `hotels[].negotiated_rate` | decimal | | Stable | The org's nightly rate. Workspace export includes it only for people with finance access, and import sets it only when the importer may edit travel costs. |
| `hotels[].rate_currency` | string | | Stable | ISO 4217 code. Workspace export includes it only for people with finance access, and import sets it only when the importer may edit travel costs. |
| `hotels[].billing_method` | string | | Stable | Workspace export includes it only for people with finance access, and import sets it only when the importer may edit travel costs. |

### Example: hotels

A saved hotel and a gig's stay there with its guests, named by member email.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PASTE",
    "name": "tour-hotels"
  },
  "hotels": [
    {
      "ref": "figueroa",
      "name": "Hotel Figueroa",
      "street": "939 S Figueroa St",
      "city": "Los Angeles",
      "state": "CA",
      "check_in_time": "15:00",
      "room_block_code": "SOUNDCHECK26"
    }
  ],
  "events": [
    {
      "title": "Downtown LA show",
      "event_date": "2026-12-12",
      "hotel_stays": [
        {
          "hotel_ref": "figueroa",
          "check_in_date": "2026-12-11",
          "check_out_date": "2026-12-13",
          "room_count": 2,
          "guests": [
            {
              "email": "avery@example.com",
              "room_number": "412"
            }
          ]
        }
      ],
      "flights": [
        {
          "airline": "Delta",
          "flight_number": "DL 1234",
          "depart_airport": "JFK",
          "arrive_airport": "LAX",
          "depart_at": "2026-12-11T14:00:00.000Z",
          "arrive_at": "2026-12-11T20:15:00.000Z",
          "passengers": [
            {
              "email": "avery@example.com",
              "seat": "14C"
            }
          ]
        }
      ]
    }
  ]
}
```

***

## Vehicles (`vehicles[]`)

The org's own and rented vehicles. A gig's rides name them with vehicle\_ref. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it. A vehicle matches a vehicle of the same name, ignoring case. A matched vehicle is not changed. `external_id` is kept for reference and does not match a record.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `vehicles[].ref` | string | | Stable | Name for this vehicle inside the document, used by vehicle\_ref. A workspace export writes the saved vehicle's ID here, so importing that export back into the same workspace matches each vehicle to its own record before it looks at names. |
| `vehicles[].external_id` | string | | Stable | The vehicle's ID in the source system, kept for reference. |
| `vehicles[].name` | string | Yes | Stable | Vehicle name. |
| `vehicles[].ownership` | string | Yes | Stable | One of \{options}. One of `OWNED`, `RENTED`. |
| `vehicles[].make` | string | | Stable | Make. |
| `vehicles[].model` | string | | Stable | Model. |
| `vehicles[].year` | integer 1900–2100 | | Stable | Year. |
| `vehicles[].color` | string | | Stable | Color. |
| `vehicles[].license_plate` | string | | Stable | License plate. |
| `vehicles[].seats` | integer 1–100 | | Stable | Seats. |
| `vehicles[].rental_company` | string | | Stable | Rented vehicles only. |
| `vehicles[].rental_confirmation` | string | | Stable | Rented vehicles only. |
| `vehicles[].rental_start_date` | `YYYY-MM-DD` | | Stable | Rented vehicles only. |
| `vehicles[].rental_end_date` | `YYYY-MM-DD` | | Stable | Rented vehicles only. |
| `vehicles[].cost` | decimal | | Stable | Workspace export includes it only for people with finance access, and import sets it only when the importer may edit travel costs. |
| `vehicles[].cost_currency` | string | | Stable | ISO 4217 code. Workspace export includes it only for people with finance access, and import sets it only when the importer may edit travel costs. |
| `vehicles[].notes` | string | | Stable | Vehicle notes. |

### Example: vehicles

An org van and a gig's ride in it, with its riders named by member email.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PASTE",
    "name": "tour-ground"
  },
  "vehicles": [
    {
      "ref": "van",
      "name": "Sprinter 1",
      "ownership": "OWNED",
      "seats": 12
    }
  ],
  "events": [
    {
      "title": "Downtown LA show",
      "event_date": "2026-12-12",
      "transports": [
        {
          "kind": "VAN",
          "vehicle_ref": "van",
          "pickup_location": "LAX Terminal 2",
          "pickup_at": "2026-12-11T20:45:00.000Z",
          "dropoff_location": "Hotel Figueroa",
          "riders": [
            {
              "email": "avery@example.com"
            }
          ]
        }
      ]
    }
  ]
}
```

***

## Sponsors (`sponsors[]`)

The org's sponsors. A gig's sponsor deals name them with sponsor\_ref. Give a record a `ref` (any short name, such as `main-stage`) so other records in the same file can point at it. A sponsor matches the org's sponsor with the same name, ignoring case, when their emails agree or either has none. A matched sponsor is not changed. `external_id` is kept for reference and does not match a record.

| Field | Type | Required | Status | Notes |
| - | - | - | - | - |
| `sponsors[].ref` | string | | Stable | Name for this sponsor inside the document, used by events\[].sponsor\_commitments\[].sponsor\_ref. A workspace export writes the record's ID here, so importing that export back into the same workspace matches each sponsor to its own record before it looks at names. |
| `sponsors[].external_id` | string | | Stable | The sponsor's ID in the source system, kept for reference. |
| `sponsors[].name` | string | Yes | Stable | Sponsor name. |
| `sponsors[].email` | email | | Stable | Sponsor email. |
| `sponsors[].phone` | phone | | Stable | Sponsor phone. |
| `sponsors[].website` | string | | Stable | Sponsor website. |
| `sponsors[].status` | string | | Stable | Sponsor status. |
| `sponsors[].tier` | string | | Stable | Sponsor tier. |
| `sponsors[].notes` | string | | Stable | Sponsor notes. |
| `sponsors[].commitments[].ref` | string | | Stable | A workspace export writes the deal's ID here, so importing it back into the same workspace finds the deal before it compares titles. Deals tied to a gig travel under that gig in events\[].sponsor\_commitments. |
| `sponsors[].commitments[].title` | string | Yes | Stable | Sponsor deal. |
| `sponsors[].commitments[].amount` | decimal | | Stable | A new deal needs it and posts it to the ledger as a receivable. Workspace export includes it only for people with finance access, and import sets it only when the importer may edit finances. |
| `sponsors[].commitments[].currency` | string | | Stable | ISO 4217 code. Defaults to USD. |
| `sponsors[].commitments[].status` | string | | Stable | Sponsor deal status. |
| `sponsors[].commitments[].due_date` | `YYYY-MM-DD` | | Stable | Sponsor deal due. |
| `sponsors[].commitments[].paid_at` | date-time | | Stable | Sponsor deal paid. |
| `sponsors[].commitments[].notes` | string | | Stable | Sponsor deal notes. |

### Example: sponsors

A sponsor with a standing deal, and a deal tied to one gig.

```json theme={null}
{
  "schema_version": "2.0",
  "source": {
    "type": "PASTE",
    "name": "sponsors"
  },
  "sponsors": [
    {
      "ref": "harbor",
      "name": "Harbor Brewing",
      "email": "events@harbor.example.com",
      "tier": "Gold",
      "commitments": [
        {
          "title": "Season bar sponsorship",
          "amount": 5000,
          "due_date": "2026-06-01"
        }
      ]
    }
  ],
  "events": [
    {
      "title": "Summer kickoff",
      "event_date": "2026-06-20",
      "sponsor_commitments": [
        {
          "sponsor_ref": "harbor",
          "title": "Stage banner",
          "amount": 750,
          "status": "committed"
        }
      ]
    }
  ]
}
```


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