---
title: "Create a matching session for a cohort (leg A)"
method: POST
path: "/api/cohorts/{cohortId}/matching-sessions"
tags: ["MatchingSessions"]
---

# Create a matching session for a cohort (leg A)

`POST /api/cohorts/{cohortId}/matching-sessions`

## Request

- Base URL: `https://api.production.yourmedley.com`
- URL: `https://api.production.yourmedley.com/api/cohorts/{cohortId}/matching-sessions`
- Auth: HTTP bearer

Always creates a new `matching_sessions` row for the calling admin (1:N model -- spec §14 step 6).
If the cohort has an active matching attempt with another admin, the new row joins it via the
existing `external_session_id` and matching-server is asked to re-mint a navigation token.
Otherwise a fresh session is created on matching-server with the full §9.1 payload.

Per §11.7 SGOS does NOT retry leg (C) automatically. On any failure the row's status
transitions to `failed`; the admin retries by clicking the button again (which creates a
new row).

## Path parameters

- `cohortId` string, uuid, required

## Request body

- object

## Response `200`

Session created (create-mode) or joined an existing attempt (re-mint mode).

- CreateMatchingSessionResponse
  - `session_id` string, uuid, required: SGOS's matching_sessions.id for the new row owned by the calling admin
  - `matching_url` string, uri, required: matching-server URL with a single-use navigation token (leg D entrypoint)

## Other responses

- `400`: Pre-flight validation failure. Codes: - `COHORT_NO_INTAKE_FORM` -- cohort has no `intake_form_id` configured. - `NO_ELIGIBLE_PARTICIPANTS` -- no participant has non-empty `available_time_slots`.
- `401`: Unauthorized -- missing or invalid SGOS admin session.
- `404`: Cohort not found.
- `502`: Outbound matching-server call failed (per spec §13 error matrix). Codes: - `MATCHING_SERVER_AUTH_REJECTED` -- matching-server returned 401 (secret drift; oncall alert emitted). - `MATCHING_SERVER_UNREACHABLE` -- network failure or non-2xx other than 401. - `MATCHING_SERVER_INVALID_RESPONSE` -- response missing required fields.
- `503`: `MATCHING_SERVER_NOT_CONFIGURED` -- matching-server env vars are missing (only possible in non-production deployments).

---

[API](https://skmtc.dev/withmedley/apis/medley-api.md) - [All operations](https://skmtc.dev/withmedley/apis/medley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withmedley/apis/medley-api/revisions/40aaac5ca6bd?raw)