Leads

Convert a lead into an event

Same service as the Inbox conversion: one event per request per venue. When an event already holds this request at this venue it is reused (reused_existing_event: true, matched_via); otherwise an event is created after the venue availability check, with its company and contact, and the lead, its siblings, requested rooms and emails move onto it. Calendars are synchronised and the automatic quote may be drafted. Role permission: leads.manage.

post/leads/{id}/convert

Request

  • Base URL: https://joinways.app/api/v1
  • URL: https://joinways.app/api/v1/leads/{id}/convert
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://joinways.app/oauth/authorize, token URL https://joinways.app/api/oauth/token, scopes: mcp.write)

Headers

Idempotency-Keystring

Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked Idempotency-Replayed: true) instead of executing the operation again. Same key with another body: 422 idempotency_key_reuse; while the first request runs: 409 idempotency_conflict. See the Idempotency section.

Request body

venue_idstring uuid required
titlestring

Defaults to a title built from the request.

start_datestring date-time required
end_datestring date-time required
status'option' | 'confirmed'

Response

The event holding the request.

successboolean
lead_idstring uuid
reused_existing_eventboolean

Only present (true) when an existing event was reused.

matched_viastring

Only with reused_existing_event; how the event was found.

warningsstring[]

Example response

{
  "event": {
    "status": "confirmed",
    "day_hours": [
      {
        "date": "2026-11-12",
        "start": "09:00",
        "end": "18:00"
      },
      {
        "date": "2026-11-13",
        "start": "19:00",
        "end": "02:00"
      }
    ],
    "beo_public_url": "https://joinways.app/beo/8f3c2a1e-…"
  },
  "warnings": [
    "space_ids_not_booked"
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.