Perfect Venue API

POST https://cotlet.dev/api/v1/perfect-venue/list_events

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/list_events \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("perfect-venue", "list_events")

const result = await cotlet.call('perfect-venue', 'list_events');

cotlet call perfect-venue list_events

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 https://cotlet.dev/api/v1/perfect-venue/get_event

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/get_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("perfect-venue", "get_event", {"event_id":"event_8c41d2"})

const result = await cotlet.call('perfect-venue', 'get_event', {"event_id":"event_8c41d2"});

cotlet call perfect-venue get_event --data '{"event_id":"event_8c41d2"}'

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 https://cotlet.dev/api/v1/perfect-venue/list_payments

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/list_payments \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"ev_8812"}'

result = client.call("perfect-venue", "list_payments", {"event_id":"ev_8812"})

const result = await cotlet.call('perfect-venue', 'list_payments', {"event_id":"ev_8812"});

cotlet call perfect-venue list_payments --data '{"event_id":"ev_8812"}'

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 https://cotlet.dev/api/v1/perfect-venue/list_messages

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/list_messages \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("perfect-venue", "list_messages", {"event_id":"event_8c41d2"})

const result = await cotlet.call('perfect-venue', 'list_messages', {"event_id":"event_8c41d2"});

cotlet call perfect-venue list_messages --data '{"event_id":"event_8c41d2"}'

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 https://cotlet.dev/api/v1/perfect-venue/list_email_templates

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.

Parameters

No parameters.

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/list_email_templates \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("perfect-venue", "list_email_templates")

const result = await cotlet.call('perfect-venue', 'list_email_templates');

cotlet call perfect-venue list_email_templates

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 https://cotlet.dev/api/v1/perfect-venue/list_spaces

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/list_spaces \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("perfect-venue", "list_spaces")

const result = await cotlet.call('perfect-venue', 'list_spaces');

cotlet call perfect-venue list_spaces

Example response

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

POST https://cotlet.dev/api/v1/perfect-venue/get_events_report

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/get_events_report \
  -H "Authorization: Bearer $COTLET_API_KEY"

result = client.call("perfect-venue", "get_events_report")

const result = await cotlet.call('perfect-venue', 'get_events_report');

cotlet call perfect-venue get_events_report

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 https://cotlet.dev/api/v1/perfect-venue/create_lead

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/create_lead \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Alex","last_name":"Client","email":"client@example.com","start_date":"2026-11-14","start_time":"18:00","end_time":"22:00","group_size":40,"event_type":"Birthday","message":"Birthday dinner, needs a private room."}'

result = client.call("perfect-venue", "create_lead", {"first_name":"Alex","last_name":"Client","email":"client@example.com","start_date":"2026-11-14","start_time":"18:00","end_time":"22:00","group_size":40,"event_type":"Birthday","message":"Birthday dinner, needs a private room."})

const result = await cotlet.call('perfect-venue', 'create_lead', {"first_name":"Alex","last_name":"Client","email":"client@example.com","start_date":"2026-11-14","start_time":"18:00","end_time":"22:00","group_size":40,"event_type":"Birthday","message":"Birthday dinner, needs a private room."});

cotlet call perfect-venue create_lead --data '{"first_name":"Alex","last_name":"Client","email":"client@example.com","start_date":"2026-11-14","start_time":"18:00","end_time":"22:00","group_size":40,"event_type":"Birthday","message":"Birthday dinner, needs a private room."}'

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 https://cotlet.dev/api/v1/perfect-venue/update_event

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/update_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("perfect-venue", "update_event", {"event_id":"event_8c41d2"})

const result = await cotlet.call('perfect-venue', 'update_event', {"event_id":"event_8c41d2"});

cotlet call perfect-venue update_event --data '{"event_id":"event_8c41d2"}'

Example response

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

POST https://cotlet.dev/api/v1/perfect-venue/set_event_status

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/set_event_status \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","status":"lead"}'

result = client.call("perfect-venue", "set_event_status", {"event_id":"event_8c41d2","status":"lead"})

const result = await cotlet.call('perfect-venue', 'set_event_status', {"event_id":"event_8c41d2","status":"lead"});

cotlet call perfect-venue set_event_status --data '{"event_id":"event_8c41d2","status":"lead"}'

Example response

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

POST https://cotlet.dev/api/v1/perfect-venue/send_proposal

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/send_proposal \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'

result = client.call("perfect-venue", "send_proposal", {"event_id":"event_8c41d2"})

const result = await cotlet.call('perfect-venue', 'send_proposal', {"event_id":"event_8c41d2"});

cotlet call perfect-venue send_proposal --data '{"event_id":"event_8c41d2"}'

Example response

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

POST https://cotlet.dev/api/v1/perfect-venue/send_email

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/send_email \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"ev_8830","template_id":"tpl_followup","subject":"Still looking at Saturday 5 Dec?"}'

result = client.call("perfect-venue", "send_email", {"event_id":"ev_8830","template_id":"tpl_followup","subject":"Still looking at Saturday 5 Dec?"})

const result = await cotlet.call('perfect-venue', 'send_email', {"event_id":"ev_8830","template_id":"tpl_followup","subject":"Still looking at Saturday 5 Dec?"});

cotlet call perfect-venue send_email --data '{"event_id":"ev_8830","template_id":"tpl_followup","subject":"Still looking at Saturday 5 Dec?"}'

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 https://cotlet.dev/api/v1/perfect-venue/log_offline_payment

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/log_offline_payment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","amount":1,"method":"method"}'

result = client.call("perfect-venue", "log_offline_payment", {"event_id":"event_8c41d2","amount":1,"method":"method"})

const result = await cotlet.call('perfect-venue', 'log_offline_payment', {"event_id":"event_8c41d2","amount":1,"method":"method"});

cotlet call perfect-venue log_offline_payment --data '{"event_id":"event_8c41d2","amount":1,"method":"method"}'

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 https://cotlet.dev/api/v1/perfect-venue/refund_payment

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.

Parameters

Request

curl -X POST https://cotlet.dev/api/v1/perfect-venue/refund_payment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_id":"payment_8c41d2","reason":"reason"}'

result = client.call("perfect-venue", "refund_payment", {"payment_id":"payment_8c41d2","reason":"reason"})

const result = await cotlet.call('perfect-venue', 'refund_payment', {"payment_id":"payment_8c41d2","reason":"reason"});

cotlet call perfect-venue refund_payment --data '{"payment_id":"payment_8c41d2","reason":"reason"}'

Example response

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