Perfect Venue API and MCP server

• POST

  list_events

  Events and leads with status, dates, guest count, contact and event owner.

  read

  Lists events from your account, including leads. Filter by status (lead, qualified, proposal_sent, confirmed, balance_due, completed or lost), by event date, by venue and by event owner. Each item has the event ID that the other tools take. Lost events are returned only when status is lost, as they are hidden from the home stages in the app.

  POST /api/v1/perfect-venue/list_events

  Input

  Input: list_events

  Parameter	Type	Description
  status	enum	lead, qualified, proposal_sent, confirmed, balance_due, completed or lost. Omit for all except lost.
  from	date	Only events on or after this date.
  to	date	Only events on or before this date.
  venue_id	string	Limit to one venue when you manage several locations.
  owner	string	Event owner, a team member email.
  limit	integer	Events per page.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "events": [
      {
        "event_id": "ev_8812",
        "name": "Smith rehearsal dinner",
        "status": "confirmed",
        "start_date": "2026-11-14",
        "start_time": "18:00",
        "end_time": "22:00",
        "group_size": 40,
        "spaces": [
          "Private Room"
        ],
        "owner": "maria@example.com",
        "contact": {
          "name": "Jane Smith",
          "email": "jane@example.com"
        }
      }
    ],
    "next_cursor": null
  }

• POST

  get_event

  One event with dates, spaces, guests, contact, status, notes, proposal totals and whether the proposal is locked.

  read

  Returns the details of one event: date and time, spaces, group size, event type, owner, contact, status, internal notes and the proposal summary with totals, the deposit and the remaining balance. Use it before update_event or send_proposal. The proposal locks when your proposal locking rule says so (at signing, 2 weeks or 1 week before the event, or never), and the response tells you if it has.

  POST /api/v1/perfect-venue/get_event

  Input

  Input: get_event

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.

  Example response

  {
    "event_id": "ev_8812",
    "name": "Smith rehearsal dinner",
    "status": "confirmed",
    "event_type": "Rehearsal",
    "start_date": "2026-11-14",
    "start_time": "18:00",
    "end_time": "22:00",
    "group_size": 40,
    "spaces": [
      "Private Room"
    ],
    "owner": "maria@example.com",
    "contact": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "555-555-0101"
    },
    "internal_notes": "Vegetarian menu for 6 guests.",
    "proposal": {
      "total": 4800,
      "deposit": 1000,
      "paid": 1800,
      "balance_due": 3000,
      "locked": false
    }
  }

• POST

  list_payments

  Payments of one event: deposits, scheduled payments and offline payments, with amount, method and date.

  read

  Returns the rows of the Payments tab of one event. Each payment says whether it was made online or logged offline, and its status. Offline payments already deduct from the total due on the proposal. Online payments can be refunded with refund_payment; offline payments cannot.

  POST /api/v1/perfect-venue/list_payments

  Input

  Input: list_payments

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.

  Example response

  {
    "event_id": "ev_8812",
    "payments": [
      {
        "payment_id": "pay_3301",
        "type": "online",
        "purpose": "deposit",
        "amount": 1000,
        "method": "card",
        "status": "paid",
        "paid_on": "2026-10-04"
      },
      {
        "payment_id": "pay_3302",
        "type": "offline",
        "purpose": "remaining_balance",
        "amount": 800,
        "method": "check",
        "status": "paid",
        "paid_on": "2026-10-09"
      }
    ],
    "total": 4800,
    "balance_due": 3000
  }

• POST

  list_messages

  The inbox thread of one event: emails to and from the contact with time and text.

  read

  Returns the emails of one event from the Perfect Venue inbox, so your agent sees who wrote last and when before it answers. Each message says whether it came from the guest or from your team.

  POST /api/v1/perfect-venue/list_messages

  Input

  Input: list_messages

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.

  Example response

  {
    "event_id": "ev_8812",
    "messages": [
      {
        "from": "team",
        "sent_at": "2026-10-02T10:15:00Z",
        "subject": "Your event inquiry",
        "body": "Thanks for your inquiry. Here is our proposal."
      },
      {
        "from": "guest",
        "sent_at": "2026-10-03T08:40:00Z",
        "subject": "Re: Your event inquiry",
        "body": "Can we move to 60 guests?"
      }
    ]
  }

• POST

  list_email_templates

  Your template emails from Settings, Email, with name, subject and text.

  read

  Returns the template emails you set up in Settings, Email. Use a template_id from this list in send_email. Templates carry the Personalize fields, which Perfect Venue fills in with the details of each event.

  POST /api/v1/perfect-venue/list_email_templates

  Input

  No parameters.

  Example response

  {
    "templates": [
      {
        "template_id": "tpl_followup",
        "name": "Follow-up",
        "subject": "Still looking at your date?",
        "body": "Hi, just checking in on your event."
      },
      {
        "template_id": "tpl_balance",
        "name": "Balance reminder",
        "subject": "Your remaining balance",
        "body": "Your remaining balance is due before your event."
      }
    ]
  }

• POST

  list_spaces

  The spaces of your venue with their IDs.

  read

  Returns the spaces you set up in Settings, Spaces, with the ID that update_event and create_lead take. Use it to name the room a guest asked for.

  POST /api/v1/perfect-venue/list_spaces

  Input

  Input: list_spaces

  Parameter	Type	Description
  venue_id	string	Limit to one venue when you manage several locations.

  Example response

  {
    "spaces": [
      {
        "space_id": "sp_01",
        "name": "Private Room"
      },
      {
        "space_id": "sp_02",
        "name": "Patio"
      }
    ]
  }

• POST

  get_events_report

  One line per event, like Reports, Events: status, owner, dates and the sales breakdown.

  read

  Returns the rows of the Events report, with the filters of a custom view: event status, venue, event owner, event date and created date. Use created dates to count new leads in a week and the status filter to count confirmed events. Lost events come back only when status is lost, with the lost reason.

  POST /api/v1/perfect-venue/get_events_report

  Input

  Input: get_events_report

  Parameter	Type	Description
  status	enum	lead, qualified, proposal_sent, confirmed, balance_due, completed or lost.
  venue_id	string	Limit to one venue.
  owner	string	Event owner, a team member email.
  event_from	date	Event date on or after this date.
  event_to	date	Event date on or before this date.
  created_from	date	Created on or after this date.
  created_to	date	Created on or before this date.
  cursor	string	Next page cursor from the previous call.

  Example response

  {
    "rows": [
      {
        "event_id": "ev_8812",
        "name": "Smith rehearsal dinner",
        "status": "confirmed",
        "created_at": "2026-10-02",
        "start_date": "2026-11-14",
        "owner": "maria@example.com",
        "total": 4800
      },
      {
        "event_id": "ev_8830",
        "name": "Lee birthday",
        "status": "lead",
        "created_at": "2026-10-08",
        "start_date": "2026-12-05",
        "owner": "maria@example.com",
        "total": 0
      }
    ],
    "count": 2,
    "next_cursor": null
  }

• POST

  create_lead

  New inquiry in the Lead status with its contact. Nothing is sent to the guest.

  write

  Adds an event in the Lead status, the status every contact-form inquiry starts in, with the contact, date, time, guest count and spaces you give. It sends nothing to the guest and is undone with set_event_status lost, so it runs without asking first. Perfect Venue may still run your automated emails for the Lead stage.

  POST /api/v1/perfect-venue/create_lead

  Input

  Input: create_lead

  Parameter	Type	Description
  first_name required	string	Contact first name.
  last_name	string	Contact last name.
  email required	string	Contact email.
  phone	string	Contact phone.
  start_date	date	Requested date.
  start_time	string	Start time, HH:MM.
  end_time	string	End time, HH:MM.
  group_size	integer	Expected number of guests.
  event_type	string	Event type as named in your account.
  spaces	array	Space IDs from list_spaces.
  message	string	Anything else from the inquiry.

  Example response

  {
    "event_id": "ev_8841",
    "status": "lead",
    "start_date": "2026-11-14",
    "group_size": 40,
    "contact": {
      "name": "Alex Client",
      "email": "client@example.com"
    }
  }

• POST

  update_event

  Change date, time, guests, spaces, event type, owner or internal notes of an event.

  write

  Changes the fields you pass and leaves the rest. It does not change the proposal items, prices or the status; use set_event_status for the status. It reaches no guest and is undone by calling it again with the old values, so it runs without asking first.

  POST /api/v1/perfect-venue/update_event

  Input

  Input: update_event

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.
  name	string	Event name.
  start_date	date	New date.
  start_time	string	Start time, HH:MM.
  end_time	string	End time, HH:MM.
  group_size	integer	Number of guests.
  spaces	array	Space IDs from list_spaces.
  event_type	string	Event type as named in your account.
  owner	string	Event owner, a team member email.
  internal_notes	string	Internal notes of the event.

  Example response

  {
    "event_id": "ev_8812",
    "status": "confirmed",
    "group_size": 60,
    "updated": [
      "group_size"
    ]
  }

• POST

  set_event_status

  Move an event to another status, with a lost reason when it is lost.

  asks first write

  Sets the status of one event: lead, qualified, proposal_sent, confirmed, balance_due, completed or lost. Perfect Venue asks for a canceled reason when an event is moved to lost, so reason is required then. Statuses can trigger your automated emails, which are set by event stage, so a change can reach the guest. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/perfect-venue/set_event_status

  Input

  Input: set_event_status

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.
  status required	enum	lead, qualified, proposal_sent, confirmed, balance_due, completed or lost.
  reason	string	Canceled reason. Required when status is lost.

  Example response

  {
    "event_id": "ev_8830",
    "status": "qualified",
    "previous_status": "lead"
  }

• POST

  send_proposal

  Send the event proposal to the guest, where they review it, sign and pay the deposit.

  asks first write

  Sends the current proposal of one event to its contact. Perfect Venue then moves the event to Proposal Sent by itself. The guest can change their menu choices only until the proposal locks. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/perfect-venue/send_proposal

  Input

  Input: send_proposal

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.
  message	string	Short note to the guest with the proposal.

  Example response

  {
    "event_id": "ev_8812",
    "status": "proposal_sent",
    "sent_to": "jane@example.com",
    "sent_at": "2026-10-11T09:30:00+02:00"
  }

• POST

  send_email

  Email the event contact from the Perfect Venue inbox, from your text or a template.

  asks first write

  Sends one email to the contact of an event from the inbox, so the reply lands in the same thread. With template_id, Perfect Venue fills in the event details of the Personalize fields. Give body or template_id. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/perfect-venue/send_email

  Input

  Input: send_email

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.
  template_id	string	Template from list_email_templates.
  subject	string	Subject line.
  body	string	Email text. Required without template_id.

  Example response

  {
    "event_id": "ev_8830",
    "status": "sent",
    "to": "lee@example.com",
    "subject": "Still looking at Saturday 5 Dec?",
    "sent_at": "2026-10-11T09:32:00+02:00"
  }

• POST

  log_offline_payment

  Record a cash, check or in-house card payment on an event.

  asks first write

  Logs a payment made outside Perfect Venue on one event, with amount, method, status and date, as Add payment, Offline payment does in the app. It charges no one, but the amount deducts from the total due on the proposal and shows in your payment reports. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/perfect-venue/log_offline_payment

  Input

  Input: log_offline_payment

  Parameter	Type	Description
  event_id required	string	Event ID from list_events.
  amount required	number	Amount paid.
  method required	string	How it was paid, for example cash or check.
  status	string	Payment status as named in your account.
  paid_on	date	Date it was paid.

  Example response

  {
    "payment_id": "pay_3302",
    "event_id": "ev_8812",
    "type": "offline",
    "amount": 800,
    "method": "check",
    "paid_on": "2026-10-09",
    "balance_due": 3000
  }

• POST

  refund_payment

  Refund an online payment in full or in part, with a reason.

  asks first write

  Refunds a payment that was made online, in full or in part, with a reason. Offline payments cannot be refunded here; they go back by the original payment method. Perfect Venue notes that a refund can take 5 to 7 business days to reach the guest, and takes the money from your connected payment account or bank account. By default you confirm each call; you can switch that off for this tool.

  POST /api/v1/perfect-venue/refund_payment

  Input

  Input: refund_payment

  Parameter	Type	Description
  payment_id required	string	Online payment ID from list_payments.
  amount	number	Amount to refund. Omit for a full refund.
  reason required	string	Reason for the refund.

  Example response

  {
    "payment_id": "pay_3301",
    "event_id": "ev_8812",
    "refunded": 1000,
    "refund_type": "full",
    "status": "refunded"
  }

Each successful call uses credits for the work it takes; failed calls and timeouts cost nothing. A hard spend cap is on by default. Authenticate with the Authorization: Bearer header.