Cohorts

Retorio organizes coaching users in cohorts. Programs are assigned to cohorts, and a user sees everything assigned to the cohorts they are in. The cohort calls manage who is in which cohort: your HR system or LMS invites joiners, removes leavers and reads back the current membership.

Find your cohort

GET /cohorts lists your cohorts with an extId, a name and a type. The extId is the {id} every call below expects, and the value the listings return as cohortExtId. The calls that invite, re-invite or remove work on cohorts of type email and are refused on a token cohort.

Invite users

POST /cohorts/{id}/participants/emails adds users and invites them in one call. A new user receives an invitation email, signs up, and sees every program assigned to the cohort. The language field sets the invitation email’s language and the user’s starting interface language. Users can change it later.

Field	Rules
emails	At least one and up to 200 addresses per call, no duplicates within the call. Batch larger populations across several calls
language	One of en-US, de-DE, fr-FR, es-ES, it-IT, pt-PT, nl-NL, pl-PL, cs-CZ, bg-BG, el-GR, ru-RU, tr-TR, ko-KR

{
  "emails": ["maria.schmidt@customer.example", "j.tan@customer.example"],
  "language": "en-US"
}

Case	What happens
The address is already in this cohort	Refused whatever its state (INVITED, ACTIVATED or DISABLED), and the whole call fails without changing anything. Only a REMOVED membership can be invited again
The address belongs to an admin account, or to another Retorio organization	Refused, and the whole call fails without changing anything
The user exists elsewhere in your organization	Added to this cohort, not duplicated
The user was removed before	Restored with the same account. Their earlier conversations and results do not come back
The user has an account	Added, not emailed
The user has not signed up yet	Emailed again only if their account is active and their last invitation is more than 24 hours old

Reconcile before you send. Re-sending the same list fails on everyone already in the cohort. Read the current membership first and send only the additions.

Invitations last 60 days. A user who has not signed up within 60 days needs a fresh invitation before they can register.

Resend invitations

POST /cohorts/{id}/participants/resendEmails emails users who have not signed up yet. It takes one of two bodies:

Body	Who is emailed	Answer
{ "userExtIds": ["<user-id>"] }	The listed users, up to 200 per call. Each must still be awaiting sign-up, be active, belong to the cohort and have been invited more than 24 hours ago. If one does not qualify, nobody is emailed and the call fails validation	204
{ "select": "next" }	The next batch of users in the cohort who qualify	200 with sent, how many were emailed, and remaining, how many still qualify. Repeat until either reaches zero

Remove users

Both calls take { "userExtIds": [...] }, up to 200 per call, and are all or nothing: if one identifier does not resolve, nothing is removed.

Call	Effect
DELETE /cohorts/participants	Removes the users from your organization, across every cohort. They can no longer sign in, and a pending invitation stops working. Use it for a leaver
DELETE /cohorts/{id}/participants	Takes the users out of one cohort. Their account stays active, with their other cohorts and the programs assigned through them. Use it for a change of team. A user who has not signed up yet and was only in that cohort can no longer sign up

Removing a user from the organization keeps their account in a removed state, which is what lets a later invitation restore it instead of creating a second one. Their conversations and results are removed with them. For a data erasure request under GDPR, contact Retorio.

Read current membership

Call	Returns
GET /cohorts/participants	Every user in at least one email cohort, one entry per cohort membership: a user in three cohorts appears three times. A user who is only in token cohorts is not listed
GET /cohorts/{id}/participants/emailParticipants	One cohort, one entry per user

{
  "userId": "6f1c0a2e_9b41_4d0c_8a7e_2f5b8c1d0e93",
  "email": "maria.schmidt@customer.example",
  "profile": { "firstName": "Maria", "lastName": "Schmidt" },
  "state": "ACTIVATED",
  "cohortExtId": "b2d7e4a1_55c3_4f28_9e10_7a3d6c4b8f02",
  "cohortName": "Sales onboarding 2026",
  "participantId": "e90f3b7c_1a26_44d5_b8c1_0d94e7f25a63",
  "lastInvitedAt": "2026-09-01T08:14:22.000Z",
  "isDisabled": false,
  "createdAt": "2026-09-01T08:14:22.000Z"
}

Field	Meaning
userId	The value to send in userExtIds to the resend and removal calls
state	ACTIVATED once the user signed up, INVITED until then, DISABLED for a suspended account, REMOVED for a past membership
createdAt	When the membership was created, not the account
cohortExtId, cohortName	null when the cohort itself has been deleted

Removed memberships stay in the listings, so filter on state to work out who is currently a member. Neither call is paginated. Match on the email address to map users to records in your own system.

When a call fails

Reconcile before retrying. After a 5xx from the invitation call, some users may already have been created, so sending the same batch again is refused. Read the membership back: invite the users who are missing, and resend to the ones already there who report no invitation, once their 24 hours have passed.