Leads

Create a lead

Creates a request (e.g. from a form or Zapier). With platform_link, the request gets the identity every Joinways ingestion path writes: when a lead already carries the same request (same link, a known alias of it, or the same inquiry at the same venue), that lead is returned with existing: true and 200 instead of a duplicate. The same inquiry at another venue is a sibling request: it is created (201). source defaults to platform when given, else api. Role permission: leads.manage.

post/leads

Request

  • Base URL: https://joinways.app/api/v1
  • URL: https://joinways.app/api/v1/leads
  • 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

client_namestring required
client_emailstring email
client_phonestring
companystring
event_typestring
date_eventstring date
date_event_endstring date
participants_fixedinteger
budget_estimatednumber
location_idstring uuid

A venue of the workspace.

requested_space_idsstring[]

Spaces of location_id the request asks for.

sourcestring

Origin label (e.g. zapier, typeform). Defaults to platform when given, else api.

notesstring
platform_linkstring uri

Link of the request on the booking platform; identifies the request (no duplicate).

platformstring

Booking platform of the request (e.g. kactus); builds the inquiry key and marks the lead as a platform request.

Response

The request was already in Joinways; the existing lead is returned.

idstring uuid
status'pending' | 'validated' | 'rejected' | 'needs_info'

pending = to process, validated = accepted (it has an event), rejected = declined, needs_info = waiting for information from the client.

client_namestring nullable
client_emailstring nullable
client_phonestring nullable
companystring nullable
event_typestring nullable
venue_namestring nullable

Venue named in the request.

venue_citystring nullable
location_idstring uuid nullable

The workspace venue the request is for.

date_eventstring date nullable
date_event_endstring date nullable
start_timestring nullable
end_timestring nullable
participants_mininteger nullable
participants_maxinteger nullable
participants_fixedinteger nullable
budget_estimatednumber nullable
budget_flexibleboolean nullable
sourcestring nullable

Origin label (a platform name, api, zapier…).

source_type'email' | 'instagram' | 'whatsapp' | 'form' | 'linkedin' | 'facebook' | 'website' | 'referral' | 'manual' | 'aircall'
platform_linkstring nullable

Link of the request on the booking platform.

inquiry_keystring nullable

Identity of the request (<platform>:<inquiry id> or <platform>:link:<canonical link>). Same key = same request (siblings across venues).

ai_scorenumber nullable
is_readboolean
is_platformboolean
is_lockedboolean

Locked by the Free plan monthly allowance (content sealed).

archived_atstring date-time nullable

Deleted (soft) or merged into another lead.

event_idstring uuid nullable

Event the request is on (converted or linked).

requested_space_idsstring[]

Spaces (rooms) of location_id the request asks for.

created_atstring date-time nullable
updated_atstring date-time nullable
validated_atstring date-time nullable
rejected_atstring date-time nullable
rejection_reason'date_unavailable' | 'capacity' | 'budget' | 'not_a_fit' | 'other'

Why the venue declined the request (optional). Only set on a rejected lead; cleared as soon as the status changes.

info_requested_atstring date-time nullable
client_replied_atstring date-time nullable
existingboolean required

true = no lead created; this is the lead already carrying the request.

matched_via'identity' | 'alias' | 'sibling' | 'source_reference'

Only when existing; how the request was recognised.

Example response

{
  "status": "pending",
  "client_name": "Jane Doe",
  "company": "Acme",
  "event_type": "seminar",
  "start_time": "19:00",
  "inquiry_key": "kactus:184522",
  "rejection_reason": "date_unavailable"
}

Changes

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