---
title: "Join a group decision session by join code"
method: POST
path: "/groups/join"
---

# Join a group decision session by join code

`POST /groups/join`

## Request

- Base URL: `https://localselections.com/api/v1`
- URL: `https://localselections.com/api/v1/groups/join`
- Auth: API key in header `X-API-Key`

Requires the `groups_join` scope — no subscription required, same as an anonymous browser join-by-code. A key can be scoped to join without also being able to host (`groups_host` is a separate scope) or vice versa. Costs 1 unit of the key's rate-limit budget per call.

## Request body

- object
  - `joinCode` string, required
  - `displayName` string

## Response `200`

The joined session id and this caller's participant identity.

- object
  - `sessionId` string, required
  - `clientId` string, required
  - `displayName` string, required

## Other responses

- `400`: The request body failed validation.
- `401`: Missing or invalid API key.
- `403`: The API key does not carry the scope this endpoint requires (see the "Requires the ... scope" note on each path, or call GET /introspect to see a key's real granted scopes).
- `404`: No group session exists for that join code.
- `429`: Rate limit exceeded for this API key. The budget is 30 units/60s for keys owned by an unsubscribed account, 120 units/60s for a subscribed account's keys (Stage 60) — shared across every endpoint, but each endpoint spends a different number of units per call rather than always 1 (Stage 104): search/groups_host/groups_join/places/movies cost 1, surprise_me/events cost 2, spin costs 3, bracket costs 4. Call GET /introspect to see a key's real remaining budget before it runs out.

---

[API](https://skmtc.dev/localselections/apis/localselections-public-api.md) · [All operations](https://skmtc.dev/localselections/apis/localselections-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/localselections/apis/localselections-public-api/revisions/a24e9598add4?raw)