POST
Create conversation from match

Overview

Creates a conversations row for a mutual matches row, or returns the existing one if the handshake has already happened. This is the single entry point into chat — there is no other endpoint that creates a conversation. The flow is:
  1. User A and User B both swipe-yes on each other, producing a Match row with status: "MUTUAL" (see Matching engine).
  2. Either participant POSTs to this endpoint with the matchId.
  3. The server creates one conversations row per match (enforced by a partial-unique index on matchId) with the two participants sorted into a canonical pair.
  4. Any subsequent call by either participant for the same matchId returns the same row — the operation is idempotent, so the client can retry safely on flaky networks.
See Match → Conversation handshake for the full sequence diagram.

Authentication

Bearer <accessToken> required. Additionally gated by requireOnboarded: the caller’s onboardingStatus must be COMPLETE — half-onboarded users cannot open conversations.

Path parameters

Query parameters

None.

Request body

None. The match itself identifies both participants; the server resolves them from the matches row.

Response — 200 OK

Returns the conversation row, freshly created or pre-existing. The response is the same shape in both cases — the client cannot (and shouldn’t) tell whether this call inserted or just read.

Conversation object

peer and property are enrichment fields added by the API for the mobile client. They are NOT stored on the conversations document — they are joined at read time from the users, matches, and currentHomes collections. Which listing is surfaced follows the same rule as the matches feed: it is always the OTHER participant’s listing (if the caller is the match’s userA, the property is listingB, and vice-versa).

Peer object

Property object

LastMessage object

ParticipantState object

Example response

Error responses

Example error — 403 FORBIDDEN

Idempotency & race-safety

The endpoint is idempotent by matchId. Internally:
  • A unique partial index (matchId) on conversations makes a duplicate insert E11000.
  • The service reads-then-creates-then-falls-back-to-read on duplicate-key: if two from-match calls fire simultaneously on the same match, both observers see the same winning row.
  • Re-calling from either participant after the row exists is a single read — no mutation.
You do not need to pass an Idempotency-Key header; the match id IS the idempotency key.

Side effects

  • If the row didn’t exist: one conversations document is inserted with status: "ACTIVE", both participantState entries zeroed.
  • No notifications fire at this point — push fan-out happens on the first message, not on handshake creation (Phase 5).

See also

curl