Manage Student Lists and Cohort-Based Course Access

A list is a named group of students in your academy (a “cohort”, “tier”, or “segment”). Lists do two jobs:

Group students so you can manage them in bulk from your own tools.
Drive course access. When an offer in your academy grants its courses to a list, every member of that list can access those courses. Add someone to the list and they get access; remove them and the access is revoked. You configure offers in your dashboard; this API manages the list and its membership. For the start-to-finish recipe (lock courses, create a hidden free offer, grant it to a list, drive membership from here), see Access Workflows.

List access is dynamic and follows membership. This is different from an enrollment, which is a direct per-student course assignment. Use a list for cohort or tier access you may want to revoke later; use an enrollment for an individual assignment.

Some lists are managed by an offer: when a student buys or claims an offer, they join its member list automatically. Those lists are the offer’s source of truth for who holds it, so this API refuses to rename or delete them, or to edit their membership, with a 400 list_managed_by_offer error. Grant or revoke the offer from your dashboard instead. Reads work on every list.

All endpoints require your API key in the Authorization header. See Authentication.

List all lists

Returns every list in your academy, newest first, each with its active member count.

GET /api/v1/lists

Response fields

object

required

Hide properties

object[]

required

Hide list properties

string

required

UUID of the list.

string

required

Display name of the list, unique within the academy.

string

Optional description. May be null.

number

required

Number of active members.

string

required

ISO 8601 creation timestamp.

string

required

ISO 8601 last-updated timestamp.

Example request

curl https://yourname.fayneos.com/api/v1/lists \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response

{
  "data": {
    "lists": [
      {
        "id": "56b4c1c0-27e1-4bf5-ab8a-bca651aef88a",
        "name": "VIP Clients",
        "description": "For our VIPs",
        "member_count": 2,
        "created_at": "2026-05-28T21:19:08Z",
        "updated_at": "2026-05-28T21:19:08Z"
      }
    ]
  }
}

Create a list

POST /api/v1/lists

Body parameters

string

required

Name of the list. 1 to 100 characters. Must be unique within the academy (case-insensitive); a duplicate returns 409 already_exists.

string

Optional description. Maximum 500 characters.

Response

Returns the created list (member_count is 0) with a 201 status code.

Example request

curl -X POST https://yourname.fayneos.com/api/v1/lists \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP Cohort", "description": "Paying members" }'

Example response

{
  "data": {
    "id": "9b34bee2-c132-4374-9c3f-d1e24817a301",
    "name": "VIP Cohort",
    "description": "Paying members",
    "member_count": 0,
    "created_at": "2026-06-19T11:12:52Z",
    "updated_at": "2026-06-19T11:12:52Z"
  }
}

Get a list

GET /api/v1/lists/:listId

Path parameters

string

required

UUID of the list. Returns 404 not_found if it does not exist in this academy.

Returns the same list object shape as the list endpoint.

Update a list

Rename a list or change its description. Provide at least one of name or description.

PATCH /api/v1/lists/:listId

Body parameters

string

New name. 1 to 100 characters. A duplicate name returns 409 already_exists.

string

New description, or null to clear it. Maximum 500 characters.

Returns the updated list object.

Example request

curl -X PATCH https://yourname.fayneos.com/api/v1/lists/9b34bee2-c132-4374-9c3f-d1e24817a301 \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP Cohort 2026" }'

Delete a list

Deletes the list. Members are not removed from the academy, but they lose any course access that this list was granting. Offer-managed lists cannot be deleted through the API (400 list_managed_by_offer).

DELETE /api/v1/lists/:listId

Example response

{ "data": { "deleted": true } }

List members

Returns the active members of a list, newest first.

GET /api/v1/lists/:listId/members

Query parameters

number

default:"50"

Number of members to return. Minimum 1, maximum 100.

number

default:"0"

Number of members to skip. Use with limit for pagination.

Response fields

object

required

Hide properties

object[]

required

Hide member properties

string

required

UUID of the student’s user account.

string

required

Student’s email address.

string

Display name. May be null.

string

Avatar URL. May be null.

string

required

ISO 8601 timestamp of when they joined the list.

object

required

Show properties

number

required

Total active members.

number

required

The limit used.

number

required

The offset used.

Add members

Adds students to a list by email. This endpoint is an upsert: if an email does not yet belong to a student in your academy, the student is created first, then added to the list. Calling it again for someone already on the list is a safe no-op. Offer-managed lists cannot be edited through the API (400 list_managed_by_offer); grant the offer instead.

POST /api/v1/lists/:listId/members

Body parameters

string

A single student email. Provide either email or emails.

string[]

A batch of student emails. Maximum 100 per request. Provide either email or emails.

boolean

default:"true"

Whether to send the magic-link welcome email to students who are newly created by this call. Set to false for silent bulk syncs. Has no effect on people who are already members.

Response fields

Returns 200 with a per-email result array, so a single failure (such as a plan-limit hit) does not fail the whole batch.

object

required

Hide properties

object[]

required

Hide result properties

string

required

The email from the request.

string

required

One of: created (a new student was provisioned and added), added (an existing student was added to the list), already_member (already on the list, no change), or error.

string

UUID of the student. Present unless status is error.

string

Error code (for example limit_exceeded). Present only when status is error.

string

Human-readable error detail. Present only when status is error.

Example request

curl -X POST https://yourname.fayneos.com/api/v1/lists/9b34bee2-c132-4374-9c3f-d1e24817a301/members \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["jamie@example.com", "alex@example.com"], "send_welcome_email": false }'

Example response

{
  "data": {
    "results": [
      { "email": "jamie@example.com", "status": "created", "student_id": "6bf451b8-765c-412c-a707-e4d0c6b4de2f" },
      { "email": "alex@example.com", "status": "already_member", "student_id": "c0b9a270-b89a-425a-80e0-869dfdc3d6d5" }
    ]
  }
}

Remove a member

Removes a student from a list. They remain in your academy, but they lose any course access this list was granting. The student’s enrollments and progress are untouched. Offer-managed lists cannot be edited through the API (400 list_managed_by_offer); revoke the offer instead.

DELETE /api/v1/lists/:listId/members/:userId

Path parameters

string

required

UUID of the student to remove (the id from the members list). Returns 404 not_found if they are not an active member of the list.

Example response

{ "data": { "removed": true } }

Courses a list grants

Returns the courses this list grants access to, derived from your academy’s active offers. A list grants a course in one of two ways: an offer is free for the list’s members (the offer grants to the list), or the list is the offer’s member list (the people who bought or claimed it). This is read-only; create or edit offers in your dashboard.

GET /api/v1/lists/:listId/courses

Response fields

object

required

Hide properties

object[]

required

Hide course properties

string

required

UUID of the course.

string

required

Course title.

string

required

URL-safe course slug.

object[]

required

The offers through which this list grants the course.

Show granted_via properties

string

required

UUID of the offer.

string

required

Display name of the offer.

string

required

How the list is attached: grants_to (the offer is free for this list’s members) or member (the list is the offer’s member list).

Example response

{
  "data": {
    "courses": [
      {
        "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Cold Outreach Mastery",
        "slug": "cold-outreach-mastery",
        "granted_via": [
          {
            "offer_id": "d4e5f6a7-b8c9-0123-def0-456789abcdef",
            "offer_name": "VIP Bundle",
            "role": "grants_to"
          }
        ]
      }
    ]
  }
}

Authentication

Endpoints

Guides

Manage Student Lists and Cohort-Based Course Access

List all lists

Response fields

Example request

Example response

Create a list

Body parameters

Response

Example request

Example response

Get a list

Path parameters

Update a list

Body parameters

Example request

Delete a list

Example response

List members

Query parameters

Response fields

Add members

Body parameters

Response fields

Example request

Example response

Remove a member

Path parameters

Example response

Courses a list grants

Response fields

Example response

​List all lists

​Response fields

​Example request

​Example response

​Create a list

​Body parameters

​Response

​Example request

​Example response

​Get a list

​Path parameters

​Update a list

​Body parameters

​Example request

​Delete a list

​Example response

​List members

​Query parameters

​Response fields

​Add members

​Body parameters

​Response fields

​Example request

​Example response

​Remove a member

​Path parameters

​Example response

​Courses a list grants

​Response fields

​Example response

List all lists

Response fields

Example request

Example response

Create a list

Body parameters

Response

Example request

Example response

Get a list

Path parameters

Update a list

Body parameters

Example request

Delete a list

Example response

List members

Query parameters

Response fields

Add members

Body parameters

Response fields

Example request

Example response

Remove a member

Path parameters

Example response

Courses a list grants

Response fields

Example response