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
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.
An API key is a secret key that allows your system to act on behalf of your Viventii account. Format: sk_live_a1b2c3d4e5f6...
| Scope | Rights | When to use? |
|---|---|---|
read | Read data | Ideal for widgets, statistics, or backup systems. |
write | Create & change data | Required for CMS sync (WordPress/Shopify) and entry apps. |
admin | Full access | Only use for internal tools or team management systems. |
Authorization: Bearer sk_live_....200 OK) or an error message (401 Unauthorized).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!
Viventii strictly separates test data from real live data. This prevents test events from accidentally becoming visible to customers.
| Feature | Live Mode (sk_live_...) | Test Mode (sk_test_...) |
|---|---|---|
| Visibility | Public on Viventii | Only for you (Draft/Private) |
| Branding | Normal title | Automatically gets [TEST] in title |
| Webhooks | Real webhooks | Test webhooks (for development) |
| Validity | Legally binding | Purely simulated data |
isTest: true) in the Dashboard.💡 Live keys cannot read/write test events and vice versa.
Scope: write
Every time a new event is created in your source system (CMS, website, database). This is the starting point for automatic synchronization.
Viventii uses an "Upsert" principle (Update or Insert). You don't need to store Viventii IDs in your database.
POST /events with a sourceId (e.g., your WordPress post ID).sourceId from this organizer?"
action: "created" or "updated").| Field | Meaning | Pro Tip |
|---|---|---|
sourceId | YOUR ID | The ID from your source system (e.g., wp-123). Crucial for auto-sync! |
name_source | Title | Use the original title from your system. |
description_source | Description | basic HTML allowed (p, br, strong). |
externalTicketStats | Live Sales | Send current sales figures (Sold/Capacity) directly! |
imageDataUri | Title Image | Send the main image as a Base64 string. |
galleryImages | Image Gallery | An array of objects (URL or Base64) for additional images. |
seriesId | Tour/Series | Use the same ID for all events of a tour. |
capacity | Capacity | Important for "Fast Sold Out" calculation. |
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_title | name_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.
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).
// 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);
We are currently working on Viventii Connect, a specialized WordPress plugin.
If you would like to test the beta version, please contact our support!
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.
| Field | Type | Required | Description |
|---|---|---|---|
sourceId | String | ✅ | Your ID. Prevents duplicates during auto-sync (e.g., wp-123). |
source_system | String | No | Name of your system (e.g., "Webshop 1"). |
name_source | String | ✅ | Original title of your event. |
description_source | String | ✅ | Original description (HTML allowed). |
date | String | ✅ | Date in YYYY-MM-DD format. |
time | String | ✅ | Start time in HH:MM format. |
slug | String | No | Your custom permalink (Viventii generates one if empty). |
seriesId | String | No | ID of an event series or tour. |
organizationId | String | No | ID of your organizer/venue (for groups). |
| Field | Type | Required | Description |
|---|---|---|---|
location | String | ✅ | Name of the venue (e.g., "Olympiastadion"). |
street | String | ✅ | Street and house number. |
city | String | ✅ | City. |
zip | String | No | ZIP code. |
country | String | No | Country (default: DE). |
lat / lng | Number | No | Manual coordinates (auto-geocoding used if empty). |
| Field | Type | Description |
|---|---|---|
isWheelchairAccessible | Boolean | Is the location wheelchair accessible? |
hasAccessibleRestrooms | Boolean | Are there accessible restrooms? |
allowsServiceAnimals | Boolean | Are service animals welcome? |
hasSignLanguage | Boolean | Is the event interpreted in sign language? |
hasAutomaticDoors | Boolean | Are there automatic doors/entrances? |
accessibilityNotes_source | String | Textual details about accessibility (e.g., "Ramp at rear entrance"). |
| Field | Type | Description |
|---|---|---|
venueTypes | Array | Types: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant. |
cuisineTypes | Array | Cuisines: 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. |
dietaryOptions | Array | Options: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb. |
serviceOptions | Array | Service: 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. |
atmosphereTypes | Array | Atmosphere: casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business. |
paymentMethods | Array | Payment: cash, credit_card, debit_card, mobile_payment, voucher. |
reservationUrl | URL | Direct link to the restaurant's booking system. |
priceRange | Enum | Price Range: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€). |
| Field | Type | Description |
|---|---|---|
publicTransportInfo_source | String | Details about arrival by bus/train. |
parkingInfo_source | String | Where to park? (Garage, parking lot, costs). |
isWeatherDependent | Boolean | Does the event only take place in good weather? |
weatherNotes_source | String | What happens if it rains? (Covered, indoor option). |
| Field | Type | Description |
|---|---|---|
lineup | Array | List of acts: [{ "name": "Artist A", "role": "Main" }]. |
schedule | Array | Timetable: [{ "time": "20:00", "title": "Show start" }]. |
doorsOpenTime | String | Doors open time (format HH:MM). |
presaleInfo_source | String | Presale info (e.g., "Early Bird until May"). |
| Field | Type | Description |
|---|---|---|
facebookUrl | URL | Link to Facebook page or event. |
instagramUrl | URL | Link to Instagram profile. |
twitterUrl | URL | Link to Twitter/X profile. |
tiktokUrl | URL | Link to TikTok profile. |
youtubeUrl | URL | Link to a trailer or channel. |
linkedinUrl | URL | Link for business events. |
websiteUrl | URL | Official event website. |
trackingPixels | Object | IDs: facebook, google, tiktok, linkedin, snapchat. |
specialOffers_source | String | Description of offers (e.g., "2-for-1 drinks"). |
| Field | Type | Description |
|---|---|---|
ticketUrl | URL | Link to ticket shop (appears as button). |
externalTicketStats | Object | LIVE synchronization: source, totalSold, totalCapacity. |
capacity | Number | Total capacity of the event. |
priceNote_source | String | textual price info (e.g., "From 15€ for students"). |
| Field | Type | Description |
|---|---|---|
imageDataUri | DataURI | Your main image as Base64 (JPG/PNG). |
galleryImages | Array | More impressions: [{ "url": "...", "caption": "..." }]. |
Scope: read — Ideal for syncing your local inventory with Viventii.
| Parameter | Function |
|---|---|
limit | Limits the number of results (Standard: 20) |
offset | For pagination (Page 1, 2, 3...) |
organizationId | Filters by a specific organization |
Scope: read — Returns the full record, including all AI-generated translations and coordinates.
Scope: write — Only send the fields that have actually changed.
Scope: write — Deletes the event and all media permanently from the CDN.
Scope: write — Controls visibility and informs customers.
| Status | Effect |
|---|---|
active | Publicly visible, tickets can be sold. |
cancelled | Event is marked as "Cancelled". Webhook is triggered. |
postponed | Marked as "Postponed". |
draft | Visible only to you. Default for test events. |
Scope: write — The most important part for the "Live Feeling" on Viventii.
Scope: write — Transfer your buyer data to Viventii for entry.
Scope: write — If you use custom scanner apps or NFC terminals.
Scope: read — Ideal for offline scanners or reports.
Scope: read — For live dashboards at the venue.
Scope: read — Combines all sales data from different sources.
Scope: write — Manage ticket allocations per channel or category.
Webhooks are automatic notifications that Viventii sends to your system.
| Event | When is it triggered? |
|---|---|
event.created | New event created |
event.updated | Event data changed |
event.status_changed | Cancellation, postponement, publication |
event.ticket_sold | Ticket sold via Viventii |
event.attendee_added | New participant added |
Scope: read — Retrieve all Stripe invoices for your Viventii account.
Scope: read — Exports email hashes for Custom Audiences (Facebook, Google, etc.).
Questions about integration? Our tech team is happy to help.
Good luck with your integration!