Event Vesta Partner Integration Guide

This guide outlines the data structure needed to share events and organizations with Event Vesta. All events must be associated with a Company (Organization). For trial imports, you may provide a static file (CSV, JSON, XML) or a feed URL.

Table of Contents

1. Overview
2. Integration Flow
3. Entities Overview
4. Companies (Organizations)
5. Event Listings
6. Boosts (Optional)
7. Delivery Options
8. Reporting and Analytics
9. Paid Trial Setup
10. Conversion Tracking (Strongly Recommended)
11. Partner Pricing and Billing
12. Next Steps

Overview

Vesta makes it easy for our partners to automatically promote events across hundreds of local community calendars, lifestyle sites, and entertainment outlets.

Unlike traditional APIs, Vesta integrations are custom-built for each partner’s workflow. We connect to your event data in one of two flexible ways:

• Feed Pull: Vesta periodically fetches events from a public JSON or CSV feed you host.
• Webhook Push: You send events directly to a unique Vesta webhook URL.

Once we receive event data, Vesta handles everything else. Each event submission automatically creates a Vesta Listing, which is then distributed across our network of applicable event calendars and media partners.

From there, we collect and report on performance data including clicks, impressions, and promotion status.

This process is one-directional. After your system sends us an event, Vesta takes care of the promotion and reporting. No ongoing sync is required unless you choose to submit updates or edits later.

Your System (Feed or Webhook)
           ↓   
Event Vesta Ingestion 
          ↓ 
Automatic Listing Creation
           ↓ 
Distribution to Calendars
           ↓ 
Performance Reporting (if requested)  

Vesta’s goal is to make event promotion effortless for both you and your customers by automating distribution while keeping flexibility in your hands.

Integration Flow

The full process from event submission to reporting is outlined below.

Step 1: Partner Sends Event Data

Partners provide either:

• A hosted feed URL that Vesta polls for new events
• A webhook payload that Vesta receives in near-real time

Step 2: Vesta Creates Listings

Once received, Vesta:

• Validates the data
• Creates a listing record
• Submits the event to relevant calendars and networks (relevancy is determined by the category, geography, and age range for the event)

Step 3: Event Runs Its Course

After submission, no further partner action is needed.

Vesta does not re-poll or sync changes unless specifically requested. See Edits section for more details.

Step 4: Vesta Reports Results

Vesta can send or expose metrics such as:

• Clicks (total)
• Estimated Impressions (from SimilarWeb or similar sources)
• Promotion Status (optional, early-stage)

Entities Overview

Each integration consists of three main data entities.

• Company (Organization) – The organizer or promoter of events.
• Event Listing – An individual event tied to a Company.
• Boosts (Optional) – Extra promotion attached to an Event Listing.

Companies (Organizations)

Required Fields

• organization_name (string) – Name of the organization.

• markets (string) – Default market for the organization. Full list of markets.

  Note: Markets can later be refined based on event locations, but each company must have a default market at creation.

• contact_name (string) – Primary contact person. Listed publicly on some calendars.
• public_contact_email (string) – Email displayed on events for attendee questions. Listed publicly on some calendars.

• vesta_communications_emails (string, one or more emails) – Used for reporting and updates. Private, not listed publicly.

  If white-labeling Vesta, include your own team’s contact email here in addition to the organization’s.

Optional Fields

• organization_description (string) – Short description of the company.
• profile_image_url (string) – Recommended: 300x300px square, max 1200x1200px.
• phone_number (string)
• facebook_link (string)
• team_admins (list of strings) – Additional admin users.

Event Listings

Event Identification and Updates

Each event submitted to Vesta must include a unique external identifier:

This value allows Vesta to recognize when an event has already been received.

• If you submit a new event with a unique event_external_id , a new listing will be created.
• If you resubmit an existing event with the same event_external_id , Vesta will ignore it unless it is marked as an update. Ignored submissions are logged for review but do not overwrite or duplicate existing data.
• Updates that require manual changes to already published listings (for example, new dates, descriptions, or cancellations) should include the field is_edit: true  to flag them for manual review under the Event Edits policy.

Providing consistent and unique IDs ensures smooth updates, accurate reporting, and clean billing records.

Required Fields

• event_name (string)
• event_teaser (string) – Up to ~150 characters.
• event_description (string) – Up to 500 characters.
• event_image_url (string) – Aspect ratio 2:1, .png or .jpeg format. Ideally not ad mat or flyer.
• primary_category (string) – Main event category. Request full list of options from your Vesta contact.
• venue_name (string) – Required if in-person.
• street, city, state, zip (strings) – Required address fields for in-person events.
• start_time (string) – Format: MM/DD/YYYY hh:mm AM/PM  . Multiple occurrences allowed.
• end_time (string) – Format: MM/DD/YYYY hh:mm AM/PM  . Multiple occurrences allowed.
• weekly_reoccurring (boolean) – Yes/No.
  • day_of_week (string) – Only use if weekly_reoccurring is Yes.
    • reoccurring_start_time (string) – hh:mm AM/PM . Only use if weekly_reoccurring is Yes. (one needed for each day_of_week)
    • reoccurring_end_time (string) – hh:mm AM/PM . Only use if weekly_reoccurring is Yes. (one needed for each day_of_week)
• timezone (string)
• ticket_purchase_url (string) – Link to buy tickets or RSVP (or mark as “registration not required”).
• family_friendly (boolean) – Yes/No.

Optional Fields

• additional_categories (list of up to 2 strings)
• age_group (string or list)
• different_parking_address (string) – If different than event venue.
• cheapest_tickets (number) – Lowest ticket price.
• max_attendance (number)
• contact_name, contact_phone, contact_email – Event-specific contact details (overrides company defaults). Listed publicly on some calendars.

🔧 Event Updates and Edits

Event Edits Overview

After an event is created and listings are distributed, any change requested by the partner is considered an Event Edit.

Because edits require manual review and re-submission by Vesta’s team, they are not automated and are billable after the first few free allowances.

Edit Allowances and Pricing

Each edit includes any combination of changes (description, date/time, image, link, etc.) made during a single submission.

How to Flag Edits in Your Feed or Webhook

When you resubmit an event with the same event_external_id , include an explicit boolean field to indicate whether it’s an edit or a full replacement.

Required Field

Example JSON

{  "event_external_id": "EVT12345",  "is_edit": true,  "event_name": "Mystery Night (Rescheduled)",  "event_description": "New date due to weather delay.",  "start_time": "2025-11-08T19:00:00",  "end_time": "2025-11-08T21:30:00" }  

Note: You do not have to let us know specifically what the edit was. We can compare what we have vs. the new submission to determine the edit(s). You can flag what edits you made as a custom field, but it is not necessary.

Example CSV Header

event_external_id,is_edit,event_name,event_description,start_time,end_time  

If is_edit  is not included or is set to false  and the event_external_id already exists in our system, we will ignore it.

Cancellation Workflow

To cancel an event:

• Send the same event_external_id
• Set is_edit: true
• Include a field status: "canceled"  or canceled: true

(canceled: true matches our system but we can handle either because all edits are manually reviewed)

Example:

{  "event_external_id": "EVT12345",  "is_edit": true,  "status": "canceled" }  

This allows Vesta’s team to manually mark listings as cancelled and log it as one edit.

Note: Listings cannot be deleted once created, but can be marked as canceled.

Partner Best Practices

• Only set is_edit  to true  when you want Vesta to manually update live listings.
• Avoid triggering is_edit: true  for internal metadata or link changes that don’t affect public listings.
• If your feed auto-updates, you can include a last_updated  timestamp and only flag is_edit  when a user actively changes event details.

Boosts (Optional)

Boosts represent add-on marketing channels.

• event_id (string) – Must match an existing Event Listing.
• boost_type (string) – Example: “email_blast”, “featured_listing”, “press_release”. Contact for full up-to-date list.
• schedule (string) – Format: MM/DD/YYYY hh:mm AM/PM  to MM/DD/YYYY hh:mm AM/PM . For featured listings.
• quantity (number) –  Number of emails being purchased (2,0005,00010,00020,000)

Delivery Options

• API/Feed URL – Preferred if available.
• Flat File (CSV/JSON/XML) – Acceptable for initial trials.

🧾 Reporting and Analytics

Overview

After an event has been promoted through Vesta, partners can access ongoing performance data through the reporting feed or email reports.

• Reporting remains available after the event ends, so partners can continue to reference historical performance data.
• However, click counts stop updating after the event end date.
• Metrics are retained for at least 90 days post-event unless otherwise arranged.

Metrics Provided

Reporting Delivery

• Email: Sent to the vesta_communications_emails  address weekly or at the end of each month.
• Webhook (optional): Partners may request a JSON payload with current stats.
• Manual export: Vesta can share CSV reports upon request for trials or audits.

🧪 Paid Trial Setup

Flexible Trial Options

Vesta supports paid trial periods so partners can see real-world performance before a full integration.

Partners may provide:

• A CSV or JSON feed of sample events
• A public URL or spreadsheet listing test events
• Even a simple email containing links to organizer pages and specifications about which events to pull in.

We’ll handle the import manually or through a temporary connector to get campaigns live quickly.

Typical Trial Scope

• 20–100 events across multiple markets
• Events at least 30 days from end date
• Events across multiple categories for best sample size
• Includes click and impression reporting for each event (and conversion tracking if setup)
• Paid trials are invoiced before the initial campaign based on the number of events to be promoted.

Next Steps for Trials

1. Send trial event info (CSV, feed, or email) to your Vesta contact.

2. We’ll confirm formatting and estimated start dates.

   Once approved, you’ll receive:

   • Confirmation of events imported
   • Reporting access for trial events
   • Post-trial summary and ROI data

🎯 Conversion Tracking (Strongly Recommended)

To measure ROI and show your customers results directly in your platform, append a unique tracking link or code to all URLs submitted to Vesta.

We highly recommend:

• UTM parameters (?utm_source=calendars )
• or a partner-specific Affiliate Tracking Link
• or a Promo URL created within your own system

Why This Matters

• Clicks from Vesta listings convert at a high rate (20–30%)

• Partners can surface this data in their own dashboards to demonstrate value

  If white-labeling, you can name the source whatever fits your brand — for example:

  • utm_source=calendars
  • utm_source=localpromotions

Partner Pricing and Billing

Vesta’s billing model is designed to be simple and predictable for both you and your customers.

Each event listing you send to Vesta represents one promotional campaign across our distribution network.

Standard Event Pricing

• Each unique event listing counts as one billable event per calendar month, regardless of how many dates or occurrences fall within that month.
• Pricing is determined by your partner agreement and billed monthly via an itemized invoice.

Recurring and Multi-Date Events

This structure ensures fair pricing for ongoing or recurring events while maintaining accurate tracking month to month.

Boosts and Add-Ons

Optional promotional add-ons (Boosts) such as Email Blasts, Featured Listings, or Press Releases are billed separately from the base event price.

Boosts can be included at the time of submission or added later by sending a corresponding boost  object referencing the same event_external_id .

Next Steps

1. Provide a sample feed of at least one Company and a few Events.
2. Vesta will validate and manually import for the trial.
3. Upon successful partnership, we’ll build a tailored connector for automated sync.