Appmiral Timetable v3 & Vendor Importer

Introduction

The Appmiral Timetable Importer v4 allows you to synchronize your timetable data with the Appmiral CMS. Every 15 minutes, the importer will perform a request to both URLs and sync the contents to the Appmiral database as Artists, Stages and Performances.

The importer requires two separate JSON endpoints:

Stages URL — containing all stage/venue information
Artists URL — containing all artist information with nested performances

Translatable Fields

Several fields support multiple languages. There are two ways to implement translatable fields:

Option 1: Single value (sets the default language)

JSON

"name": "Main Stage"

Option 2: Object with language keys

JSON

"name": {
  "en": "Main Stage",
  "nl": "Hoofdpodium",
  "de": "Hauptbühne"
}

Supported languages: English (en), Arabic (ar), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), Galician (gl), German (de), Greenlandic (kl), Hebrew (he), Italian (it), Norwegian (nb), Polish (pl), Romanian (ro), Spanish (es), Swedish (sv), Thai (th)

Stages

The stages endpoint should return a JSON array, optionally wrapped in a "stages" key:

JSON

{
  "stages": [ ... ]
}

Stage Model

Field	Required	Type	Description
id	Yes	string	Must be unique for each stage
name	Yes	string / object	Translatable
priority	No	integer	Determines the position in the list. Default: 100
description	No	string / object	Can contain HTML. Translatable
image	No	string / object	JPG or PNG. Minimum 1500x1500 pixels. Translatable
color	No	string	HEX color code with # (e.g., "#FF0000")
capacity	No	string	Stage capacity (e.g., "5000")
tags	No	array	Array of tag strings or tag objects (see Tags )
customFields	No	object	Key-value pairs matching custom field definitions in the CMS

Stages JSON Example

JSON

{
  "stages": [
    {
      "id": "1",
      "name": "Main Stage",
      "priority": 1,
      "description": "The largest outdoor stage",
      "image": "https://example.com/images/main-stage.jpg",
      "color": "#FF5733"
    },
    {
      "id": "dance_hall",
      "name": {
        "en": "Dance Hall",
        "nl": "Danszaal"
      },
      "priority": 2,
      "image": "https://example.com/images/dance-hall.jpg",
      "tags": [
        "indoor",
        {
          "slug": "vip-area",
          "name": {
            "en": "VIP Area",
            "nl": "VIP Gebied"
          },
          "color": "#FFD700",
          "text_color": "#000000"
        }
      ]
    }
  ]
}

Artists

The artists endpoint should return a JSON array, optionally wrapped in an "artists" key:

JSON

{
  "artists": [ ... ]
}

Artist Model

Field	Required	Type	Description
id	Yes	string	Must be unique and unchangeable. Max 500 characters
name	Yes	string / object	Translatable
performances	No	array	Array of performance objects (see Performances )
priority	No	integer	Determines the position in the list. Default: 100
category	No	string	One of: headliner, featured, regular, supporting
description	No	string / object	Can contain HTML. Translatable
image	No	string / object	JPG or PNG. Minimum 1500x1500 pixels. Translatable
tags	No	array	Array of tag strings or tag objects (see Tags )
related	No	array of strings	Artist IDs to show in the “Related Artists” section
show_in_artists	No	boolean	Show this artist in the artists listing
show_section_titles	No	boolean	Show section titles on the artist detail page
website	No	string / object	Translatable
facebook	No	string	Facebook page URL
twitter	No	string	Twitter/X profile URL
linkedin	No	string	LinkedIn profile URL
instagram	No	string	Instagram profile URL
tiktok	No	string	TikTok profile URL
youtube	No	string	YouTube channel URL
vimeo	No	string	Vimeo profile URL
spotify	No	string	Spotify artist URL or URI
deezer	No	string	Deezer artist URL
applemusic	No	string	Apple Music artist URL
soundcloud	No	string	SoundCloud profile URL
customFields	No	object	Key-value pairs matching custom field definitions in the CMS

Note: If an artist image gets changed, make sure to adjust the URL as well. The importer detects changes by comparing the image URL.

Performances

Performances are nested inside each artist object.

Field	Required	Type	Description
id	Yes	string	Must be unique for each performance
name	No	string / object	Performance name. Optional if same as artist name. Translatable
description	No	string / object	Performance-specific description. Can contain HTML. Translatable
start_time	No	string	Format: YYYY-MM-DD HH:mm:ssZ. Must be ≤ end_time
end_time	No	string	Format: YYYY-MM-DD HH:mm:ssZ. Must be ≥ start_time
stage_id	No	string	Must reference a stage ID from the stages endpoint
priority	No	integer	Default: 100. Inherits from artist if not set
color	No	string	HEX color code with # (e.g., "#FF5733")
hide_times	No	boolean	Hide start and end times from display
show_in_calendar	No	boolean	Show this performance in the calendar view
show_in_schedule	No	boolean	Show this performance in the schedule view
show_in_lineup	No	boolean	Show this performance in the lineup view
tags	No	array	Array of tag strings or tag objects (see Tags )
customFields	No	object	Key-value pairs matching custom field definitions in the CMS

Tip: If the day of a performance is already known but the exact time is still unknown, use the same start_time and end_time on the day of the performance.

Artists JSON Example

JSON

{
  "artists": [
    {
      "id": "rihanna",
      "name": "Rihanna",
      "description": "<p>Barbadian singer, actress and businesswoman.</p>",
      "image": "https://example.com/images/rihanna.jpg",
      "category": "headliner",
      "priority": 1,
      "website": "https://www.rihanna.com",
      "facebook": "https://www.facebook.com/rihanna",
      "instagram": "https://www.instagram.com/badgalriri",
      "spotify": "https://open.spotify.com/artist/5pKCCKE2ajJHZ9KAiaK11H",
      "related": ["taylor-swift"],
      "tags": [
        "pop",
        {
          "slug": "headliner-friday",
          "name": {
            "en": "Headliner Friday",
            "nl": "Headliner Vrijdag"
          },
          "color": "#FF0000",
          "text_color": "#FFFFFF"
        }
      ],
      "performances": [
        {
          "id": "rihanna-friday",
          "stage_id": "1",
          "start_time": "2025-07-18 22:00:00Z",
          "end_time": "2025-07-19 00:00:00Z",
          "color": "#FF0000",
          "show_in_schedule": true,
          "show_in_lineup": true,
          "show_in_calendar": true
        }
      ]
    },
    {
      "id": "taylor-swift",
      "name": {
        "en": "Taylor Swift",
        "nl": "Taylor Swift"
      },
      "description": {
        "en": "<p>American singer-songwriter known for narrative songs.</p>",
        "nl": "<p>Amerikaanse singer-songwriter bekend om haar verhalende liedjes.</p>"
      },
      "image": {
        "en": "https://example.com/images/taylor-en.jpg",
        "nl": "https://example.com/images/taylor-nl.jpg"
      },
      "category": "headliner",
      "priority": 2,
      "website": {
        "en": "https://www.taylorswift.com",
        "nl": "https://www.taylorswift.com/nl"
      },
      "instagram": "https://www.instagram.com/taylorswift",
      "spotify": "https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02",
      "related": ["rihanna"],
      "tags": ["pop", "country"],
      "performances": [
        {
          "id": "taylor-saturday",
          "stage_id": "1",
          "start_time": "2025-07-19 21:00:00Z",
          "end_time": "2025-07-19 23:30:00Z"
        },
        {
          "id": "taylor-acoustic",
          "name": {
            "en": "Taylor Swift - Acoustic Session",
            "nl": "Taylor Swift - Akoestische Sessie"
          },
          "description": "Intimate acoustic set",
          "stage_id": "dance_hall",
          "start_time": "2025-07-20 15:00:00Z",
          "end_time": "2025-07-20 16:00:00Z",
          "hide_times": true
        }
      ]
    }
  ]
}

Field	Required	Type	Description
slug	Yes	string	Tag identifier. Lowercase, a-z, 0-9, hyphens only
name	Yes	string / object	Display name. Translatable
color	No	string	Background color (HEX with #)
text_color	No	string	Text color (HEX with #)

Custom Fields

Custom fields allow you to store additional data on stages, artists, and performances. The keys must match custom field definitions configured in the CMS for the edition.

JSON

"customFields": {
  "ticket_price": "45.00",
  "age_restriction": "18+",
  "is_seated": "true"
}

Values are mapped based on the custom field type defined in the CMS (string, text, HTML, integer, boolean, or date).

Notes

All times must be in UTC (format: YYYY-MM-DD HH:mm:ssZ)
The importer uses change detection — unchanged data is not re-imported
Duplicate IDs within the same import are skipped (first occurrence wins)
Artist descriptions support HTML content
Empty strings for URLs are treated as null
If an image URL changes, the image will be re-downloaded automatically

Should you need assistance setting up your data importers, do not hesitate to contact your Customer Success Manager at Appmiral.

Appmiral Timetable v3 & Vendor Importer

Introduction

Translatable Fields

Stages

Stage Model

Stages JSON Example

Artists

Artist Model

Performances

Artists JSON Example

Tags

Simple format (string)

Full format (object)3

Custom Fields

Notes