canonical: https://jentic.com/apis/joinways.app/joinways

# Joinways App Joinways Public API

The Joinways Public API reads and updates the sales and operations data of an event venue workspace: inbound leads, events and their pipeline stages, quotes and quote items, companies, contacts, venues, catalog items, and tasks. A lead can be converted into an event, linked to an existing one, or merged into a duplicate, and an event carries its days, space slots, staff, day-of contacts, notes, emails, and banquet event order (BEO), which downloads as a PDF. Venue operations cover availability, opening hours, closures, booking conflicts, and public holiday import, and the analytics endpoints report on inquiries, commercial results, accounting, and responsiveness.

## For AI agents

Work an event venue's sales pipeline in Joinways: triage and convert leads, move events through stages, build and send quotes, check venue availability, and update the BEO. Includes contacts, companies, tasks, analytics, and webhooks.

## Scope

Does not handle ticket sales, payment collection, or guest registration. Use for running an event venue's leads, events, quotes, and venue calendar only.

## Capabilities

- Triage inbound leads by status or source, then convert a lead into an event at a venue, link it to an existing event, or merge it into a duplicate
- Move an event through its pipeline with a status or stage_id change, recording a loss_reason or cancellation_reason when it falls through
- Build a quote for an event, add and reorder quote items, change its status, duplicate it, and download it as a PDF
- Check a venue's availability and booking conflicts for a date range and block dates with a closure
- Fill in an event's banquet event order with setup, catering, and dietary notes and download the BEO as a PDF
- Send an email about an event and list the emails already linked to it
- Subscribe a webhook target_url to event_types so changes in the workspace reach your own system

## Use cases

### Agent Lead Triage and Conversion via Jentic

An AI agent working a venue's inbox lists unread leads, checks the requested dates against venue availability and booking conflicts, and converts the good ones into events with a venue_id, start_date, and end_date. Through Jentic the agent discovers each operation by intent and calls it with the workspace token, so a sales coordinator reviews converted events instead of re-keying inquiries.

Example prompt: List leads with is_read false, check venue availability for each lead's requested date, and convert the first available lead into an event at venue_id with its start_date and end_date

### Quote Building for Event Proposals

Once an event exists, the sales team creates a quote tied to its event_id with a title and currency, adds catalog-based quote items with quantity and unit_price, and reorders them for presentation. The quote moves through statuses, can be duplicated for a variant proposal, and downloads as a PDF in the client's locale.

Example prompt: Create a quote for event_id with title 'Spring offsite proposal' in EUR, add a room hire item and a catering item with quantity and unit_price, then download the quote PDF

### Event Operations and the BEO

Operations staff keep each confirmed event ready for the day: they assign space slots per day, replace the staff and day-of contact lists, add tasks, and fill in the banquet event order with setup_type, catering_notes, and dietary_notes. The BEO then downloads as a PDF for the floor team.

Example prompt: Update the BEO for event id with setup_type, catering_notes, and dietary_notes, create a task 'Confirm AV setup' due the day before, and download the BEO PDF

### Venue Calendar Control

Venue managers set opening hours, block dates for maintenance with a closure that carries startDate, endDate, and a reason, and import public holidays for a country and year. Before confirming a booking, an agent checks the conflicts endpoint for the requested spaces and dates.

Example prompt: Add a closure for venueId from 2026-12-24 to 2026-12-26 with reason 'Holiday closure', then list conflicts for those dates to see which events need moving

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/leads` | List leads |
| POST | `/leads/{id}/convert` | Convert a lead into an event |
| POST | `/events` | Create an event |
| POST | `/events/{id}/status` | Change an event status |
| POST | `/quotes` | Create a quote |
| GET | `/venues/{venueId}/availability` | Get venue availability |
| PUT | `/events/{id}/beo` | Update event BEO fields |
| POST | `/webhooks` | Create a webhook subscription |

## Key resources

- **Leads** — Inbound requests that can be converted, linked, or merged into events.
- **Events** — Bookings with pipeline status and stage, days, slots, staff, contacts, notes, emails, and BEO.
- **Quotes** — Priced proposals for an event with items, statuses, and PDF output.
- **Venues** — Venues and spaces with availability, opening hours, closures, and conflicts.
- **Companies and contacts** — Client organisations and people linked to events.
- **Webhooks** — Subscriptions that push workspace changes to your own endpoint.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 61 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 86 / 100
  - Security: 75 / 100
  - AI Discoverability: 84 / 100
- **View full report:** https://jentic.com/apis/joinways.app/joinways/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Joinways by hand means choosing between a workspace API key and an OAuth 2.1 PKCE flow with a resource parameter, rotating refresh tokens, and handling its stacked per-IP and per-workspace rate limits. Through Jentic you install once, import Joinways from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Joinways puts the record id in the URL path (`/events/{id}`, `/quotes/{id}`, `/venues/{venueId}`), so a rule can pin your agent to one event, quote, or venue and the operations you pick. You choose the operations it may call, so destructive ones like deleting an event or a contact are not included unless you add them.
- **Credential handling:** Your Joinways token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert a lead into an event' or 'check venue availability', and Jentic returns the matching Joinways operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cvent** — Cvent covers large-scale event and venue sourcing; Joinways is a sales and operations CRM for the venue itself.
- **Pipedrive API** — Pipedrive is a general sales pipeline CRM; Joinways adds venue availability, quotes, and BEOs built for events.
- **Eventbrite** — Eventbrite sells tickets for public events; Joinways manages private event bookings and their operations.
- **Stripe** — Stripe collects deposits and payments; Joinways produces the quote those payments settle.

## FAQ

### What authentication does the Joinways Public API use?

The Joinways Public API declares two schemes in its OpenAPI spec: an HTTP bearer token, which can be a workspace API key prefixed jw_ created under Settings, Developers, API keys, and OAuth 2.1 authorization code with PKCE, whose access tokens are prefixed jw_oat_ and carry the mcp.read and mcp.write scopes. Either goes in the Authorization: Bearer header and is bound to a single workspace. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time.

### Is there a Joinways MCP server?

Yes - Joinways offers an official MCP server at mcp.joinways.app. You can also connect the Joinways Public API directly through Jentic: your agent gets the full 93-endpoint surface from the spec without loading another server's tool definitions into its context, your credential is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### Can I limit what my agent is allowed to do with the Joinways Public API?

Yes. For example, write a rule that allows only the lead list, lead read, venue availability read, and lead convert operations, so an intake agent can triage inquiries and turn them into events but cannot delete events, contacts, or quotes. Because the event id sits in the path, you can also hold an operations agent to `/events/{id}` for one event, and every call it makes is logged.

### Can I check venue availability before booking with the Joinways Public API?

Yes. GET `/venues/{venueId}/availability` takes from, to, and optional space_ids, and GET `/venues/{venueId}/conflicts` lists booking conflicts for a start_date and end_date. Closures added through the closures endpoint block dates on the venue calendar.

### What are the rate limits for the Joinways Public API?

Per the Joinways OpenAPI spec, limits stack: 300 requests per minute per IP before authentication, 600 requests per minute and 100,000 per day per workspace on the Pro plan, 200 per minute and 5,000 per day on the free trial, and 20 per minute per workspace for sending event emails. Responses carry X-RateLimit headers, and a 429 tells you to wait for Retry-After seconds.

### How do I convert a lead into an event with the Joinways Public API through Jentic?

Search Jentic for an intent like 'convert a venue inquiry into an event', import Joinways from the API Directory, and store your workspace token once. Your agent then calls POST `/leads/{id}/convert` with the venue_id, start_date, and end_date, and reads the new event back with GET `/events/{id}.` To run it on your own infrastructure, install Jentic One from its GitHub repo.