Viventii
Search EventsRelease Radar
LoginSign Up
Viventii
Viventii Logo

Discover local events, concerts, workshops and more with Viventii.

Discover

View all cities

Categories

Parties & ClubbingMusic & FestivalsTrade Fairs & MarketsShopping & MarketsBars & RestaurantsFamily & KidsView all categories

Company

Jobs & CareerFAQSupport & ContactPromotions & Deals

Discover nightlife or plan your own private highlights. Whether it's a big concert or a cozy game night with friends – Viventii brings it all together.

ImprintPrivacy PolicyTerms of UseCookie PolicyData sources & licenses

© ... Viventii UG (limited liability). All rights reserved.

DiscoverMapRadarTickets
DiscoverMapRadarTickets

Developer Documentation

Full reference for the Viventii Organizer API.

Download OpenAPI Specification

Viventii API – Complete Documentation (A-Z)

This documentation describes every function, every endpoint, and every integration possibility of the Viventii API – without shortcuts.

Base URL: https://viventii.com/api/v1/organizer

🚀 0. Quickstart: Interactive Code Generator

Use our interactive tool to generate ready-to-use code for your system. Simply enter your API key and a name for your system – our Universal Sync handles the rest automatically.


🔐 1. Authentication & API Keys

What is an API Key?

An API key is a secret key that allows your system to act on behalf of your Viventii account. Format: sk_live_a1b2c3d4e5f6...

How to get an API Key?

  1. Open your Viventii Dashboard
  2. Go to Profile → Developer
  3. Click on "Create API Key"
  4. Choose a Name and Permissions (Scopes)
  5. The key will be shown once – save it securely immediately!

Scopes (Permissions)

ScopeRightsWhen to use?
readRead dataIdeal for widgets, statistics, or backup systems.
writeCreate & change dataRequired for CMS sync (WordPress/Shopify) and entry apps.
adminFull accessOnly use for internal tools or team management systems.

Authentication Flow

  1. Request: Your server sends an HTTP request to Viventii.
  2. Header: You add the header Authorization: Bearer sk_live_....
  3. Validation: Viventii checks the key and your permissions (Scopes).
  4. Identification: Viventii assigns the request to your organization.
  5. Response: You receive the data (200 OK) or an error message (401 Unauthorized).

Security Best Practices

  • Never use in the frontend: An API key belongs in the backend (Node.js, PHP, Python). It must never appear in the JavaScript code of a website (danger of theft!).
  • Two-Key Principle: Use separate keys for different systems (e.g., one key for WordPress, one for the scanner app). If one system is compromised, you only need to revoke one key.
  • Rotation: Renew your keys every 6-12 months.

Alternative: Firebase ID Token

Mobile apps (iOS/Android) can send a Firebase ID Token of the logged-in user instead of an API key. Viventii recognizes the user automatically and grants the appropriate rights.

⚠️ The key is shown only ONCE!


🧪 2. Sandbox Mode (Test vs. Live)

Viventii strictly separates test data from real live data. This prevents test events from accidentally becoming visible to customers.

Comparison: Live vs. Test

FeatureLive Mode (sk_live_...)Test Mode (sk_test_...)
VisibilityPublic on ViventiiOnly for you (Draft/Private)
BrandingNormal titleAutomatically gets [TEST] in title
WebhooksReal webhooksTest webhooks (for development)
ValidityLegally bindingPurely simulated data

Best-Case Workflow for Developers

  1. Test Key: Create a test key (isTest: true) in the Dashboard.
  2. Development: Integrate the API and send test events to Viventii.
  3. Validation: Check in the Dashboard under "Test Events" if all fields arrive correctly.
  4. Going Live: Create a live key as soon as your tests are successful.
  5. Switchover: Change your server's environment variable to the live key.

💡 Live keys cannot read/write test events and vice versa.


📝 3. Events – Create (POST /events)

Scope: write

When do you need this endpoint?

Every time a new event is created in your source system (CMS, website, database). This is the starting point for automatic synchronization.

The Synchronisation Process (Universal Sync)

Viventii uses an "Upsert" principle (Update or Insert). You don't need to store Viventii IDs in your database.

  • Step 1: Your system sends POST /events with a sourceId (e.g., your WordPress post ID).
  • Step 2: Viventii checks: "Do I already know this sourceId from this organizer?"
    • No: A new event is created.
    • Yes: The existing event is updated with the new data.
  • Step 3 (Background):
    • 📍 Geocoding: The address is converted into coordinates for the map.
    • 🌐 AI Translation: Texts are automatically translated into 6 languages.
    • 🔗 SEO: A friendly link (slug) is generated.
    • 🖼️ Asset Flow: Your image is optimized and uploaded to the CDN.
  • Step 4: You receive confirmation (action: "created" or "updated").

Important Fields & Details

FieldMeaningPro Tip
sourceIdYOUR IDThe ID from your source system (e.g., wp-123). Crucial for auto-sync!
name_sourceTitleUse the original title from your system.
description_sourceDescriptionbasic HTML allowed (p, br, strong).
externalTicketStatsLive SalesSend current sales figures (Sold/Capacity) directly!
imageDataUriTitle ImageSend the main image as a Base64 string.
galleryImagesImage GalleryAn array of objects (URL or Base64) for additional images.
seriesIdTour/SeriesUse the same ID for all events of a tour.
capacityCapacityImportant for "Fast Sold Out" calculation.

🛠️ Field Mapping & Schema (IMPORTANT)

The Viventii API uses a static target schema. This means: The field names (keys) you send to us (e.g., name_source) must always be named exactly as described in this documentation.

How does mapping work? Your system (e.g., WordPress) has its own field names. You must "translate" these into our names in your code:

Your Field (Example)Viventii Target Field
$post->post_titlename_source
$meta['location']location
$event['start']date / time

Where does the mapping take place? The mapping takes place in your system (e.g., in a cron job, a sync script, or middleware). Before sending the POST request to Viventii, you assign your local variables to the Viventii keys.

🔌 WordPress Special Tip

If you use WordPress, the mapping usually happens in the functions.php of your theme or in a dedicated plugin. A proven pattern is the usage of the save_post hook.

The Bridge Principle (Important for understanding) Many ask: 'How does Viventii know which field in my system means what?'

The answer: Viventii doesn't know. Viventii is a passive recipient (the target). Your system is the active sender (the source).

  1. Your Responsibility: You write a small script (the bridge) that queries data from your database.
  2. The Mapping: You decide in this script which value flows into which Viventii field.
  3. The Push: Your script 'pushes' (POST) the fully translated data to us.
// Example for 'translation' in WordPress functions.php: add_action('save_post', function($post_id) { // Step A: Get your internal data $my_internal_title = get_the_title($post_id); $my_internal_address = get_post_meta($post_id, 'wp_field_address', true); // Step B: Mapping (You assign your value to our key) $payload = [ 'name_source' => $my_internal_title, // Translation: WP-Title -> Viventii-Key 'location' => $my_internal_address, // Translation: WP-Meta -> Viventii-Key 'sourceId' => 'wp-' . $post_id ]; // Step C: Send to Viventii wp_remote_post('https://api.viventii.com/v1/organizer/events', ['body' => json_encode($payload)]); }, 10, 1);

🚀 Outlook: Viventii Connect (No-Code)

We are currently working on Viventii Connect, a specialized WordPress plugin.

  • Upload & Go: No more code editing required.
  • Visual Mapping: You simply select from a list: 'Field X from my theme' -> 'Field Y in Viventii'.
  • Auto-Health: The plugin warns you if a sync fails.

If you would like to test the beta version, please contact our support!


📚 Full Field Reference (60+ Fields)

To leverage the full potential of the Viventii AI, send as many details as possible. The AI uses these facts to automatically write SEO-optimized descriptions in 6 languages.

A. core Metadata (Infrastructure)

FieldTypeRequiredDescription
sourceIdString✅Your ID. Prevents duplicates during auto-sync (e.g., wp-123).
source_systemStringNoName of your system (e.g., "Webshop 1").
name_sourceString✅Original title of your event.
description_sourceString✅Original description (HTML allowed).
dateString✅Date in YYYY-MM-DD format.
timeString✅Start time in HH:MM format.
slugStringNoYour custom permalink (Viventii generates one if empty).
seriesIdStringNoID of an event series or tour.
organizationIdStringNoID of your organizer/venue (for groups).

B. Location & Address

FieldTypeRequiredDescription
locationString✅Name of the venue (e.g., "Olympiastadion").
streetString✅Street and house number.
cityString✅City.
zipStringNoZIP code.
countryStringNoCountry (default: DE).
lat / lngNumberNoManual coordinates (auto-geocoding used if empty).

C. Accessibility

FieldTypeDescription
isWheelchairAccessibleBooleanIs the location wheelchair accessible?
hasAccessibleRestroomsBooleanAre there accessible restrooms?
allowsServiceAnimalsBooleanAre service animals welcome?
hasSignLanguageBooleanIs the event interpreted in sign language?
hasAutomaticDoorsBooleanAre there automatic doors/entrances?
accessibilityNotes_sourceStringTextual details about accessibility (e.g., "Ramp at rear entrance").

D. Gastronomy & Establishments

FieldTypeDescription
venueTypesArrayTypes: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant.
cuisineTypesArrayCuisines: german, italian, french, spanish, greek, turkish, asian, japanese, chinese, thai, indian, mexican, american, mediterranean, middle_eastern, vegetarian_vegan, seafood, steakhouse, pizza, burger, sushi, tapas, fusion, international, other.
dietaryOptionsArrayOptions: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb.
serviceOptionsArrayService: dine_in, takeaway, delivery, reservations, private_events, catering, brunch, happy_hour, outdoor_seating, live_music, sports_tv, air_conditioning, pets_allowed, smoking_area, rooftop, garden, fireplace.
atmosphereTypesArrayAtmosphere: casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business.
paymentMethodsArrayPayment: cash, credit_card, debit_card, mobile_payment, voucher.
reservationUrlURLDirect link to the restaurant's booking system.
priceRangeEnumPrice Range: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€).

E. Logistics & Weather

FieldTypeDescription
publicTransportInfo_sourceStringDetails about arrival by bus/train.
parkingInfo_sourceStringWhere to park? (Garage, parking lot, costs).
isWeatherDependentBooleanDoes the event only take place in good weather?
weatherNotes_sourceStringWhat happens if it rains? (Covered, indoor option).

F. Program & Lineup

FieldTypeDescription
lineupArrayList of acts: [{ "name": "Artist A", "role": "Main" }].
scheduleArrayTimetable: [{ "time": "20:00", "title": "Show start" }].
doorsOpenTimeStringDoors open time (format HH:MM).
presaleInfo_sourceStringPresale info (e.g., "Early Bird until May").

G. Marketing & Social Media

FieldTypeDescription
facebookUrlURLLink to Facebook page or event.
instagramUrlURLLink to Instagram profile.
twitterUrlURLLink to Twitter/X profile.
tiktokUrlURLLink to TikTok profile.
youtubeUrlURLLink to a trailer or channel.
linkedinUrlURLLink for business events.
websiteUrlURLOfficial event website.
trackingPixelsObjectIDs: facebook, google, tiktok, linkedin, snapchat.
specialOffers_sourceStringDescription of offers (e.g., "2-for-1 drinks").

H. Tickets & Statistics

FieldTypeDescription
ticketUrlURLLink to ticket shop (appears as button).
externalTicketStatsObjectLIVE synchronization: source, totalSold, totalCapacity.
capacityNumberTotal capacity of the event.
priceNote_sourceStringtextual price info (e.g., "From 15€ for students").

I. Media & Gallery

FieldTypeDescription
imageDataUriDataURIYour main image as Base64 (JPG/PNG).
galleryImagesArrayMore impressions: [{ "url": "...", "caption": "..." }].

📋 4. Events – List (GET /events)

Scope: read — Ideal for syncing your local inventory with Viventii.

Filter Options

ParameterFunction
limitLimits the number of results (Standard: 20)
offsetFor pagination (Page 1, 2, 3...)
organizationIdFilters by a specific organization

📄 5. Get Event (GET /events/:id)

Scope: read — Returns the full record, including all AI-generated translations and coordinates.


✏️ 6. Update Event (PATCH /events/:id)

Scope: write — Only send the fields that have actually changed.


🗑️ 7. Delete Event (DELETE /events/:id)

Scope: write — Deletes the event and all media permanently from the CDN.


🔄 8. Change Event Status (POST /events/:id/status)

Scope: write — Controls visibility and informs customers.

Status Overview

StatusEffect
activePublicly visible, tickets can be sold.
cancelledEvent is marked as "Cancelled". Webhook is triggered.
postponedMarked as "Postponed".
draftVisible only to you. Default for test events.

🎟️ 9. Ticket Sales Stats (POST /events/:id/tickets/stats)

Scope: write — The most important part for the "Live Feeling" on Viventii.


👥 10. Sync Attendee Lists (POST /events/:id/tickets/attendees)

Scope: write — Transfer your buyer data to Viventii for entry.


✅ 11. Check-in / Entry (POST /events/:id/tickets/validate)

Scope: write — If you use custom scanner apps or NFC terminals.


📥 12. Export Guest List (GET /events/:id/tickets/export)

Scope: read — Ideal for offline scanners or reports.


📊 13. Live Entry Statistics (GET /events/:id/stats/entry)

Scope: read — For live dashboards at the venue.


📈 14. Unified Ticket View (GET /events/:id/tickets)

Scope: read — Combines all sales data from different sources.


📦 15. Inventory & Allocations (PATCH /events/:id/inventory)

Scope: write — Manage ticket allocations per channel or category.


🔗 16. Webhooks – Register & Manage

What are Webhooks?

Webhooks are automatic notifications that Viventii sends to your system.

EventWhen is it triggered?
event.createdNew event created
event.updatedEvent data changed
event.status_changedCancellation, postponement, publication
event.ticket_soldTicket sold via Viventii
event.attendee_addedNew participant added

💳 17. Finance – Invoices & Billing

Scope: read — Retrieve all Stripe invoices for your Viventii account.


📣 18. Audience Sync – Marketing Target Groups

Scope: read — Exports email hashes for Custom Audiences (Facebook, Google, etc.).


🛠️ 19. Support & Help

Questions about integration? Our tech team is happy to help.

  • Email: support@viventii.com
  • Web: Support & Contact

Good luck with your integration!