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 a course grants access to a list, every member of that list can access the course. Add someone to the list and they get access; remove them and the access is revoked. You configure which courses a list grants from your dashboard; this API manages the list and its membership.

List access is dynamic and follows membership. This is different from an enrollment, which is a permanent per-course grant. Use a list for cohort or tier access you may want to revoke later; use an enrollment for a one-off grant that should persist.

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

data

object

required

Hide properties

lists

object[]

required

Hide list properties

string

required

UUID of the list.

name

string

required

Display name of the list, unique within the academy.

description

string

Optional description. May be null.

member_count

number

required

Number of active members.

created_at

string

required

ISO 8601 creation timestamp.

updated_at

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

name

string

required

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

description

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": "Premium Cohort", "description": "Paying members" }'

Example response

{
  "data": {
    "id": "9b34bee2-c132-4374-9c3f-d1e24817a301",
    "name": "Premium 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

listId

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

name

string

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

description

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": "Premium Cohort 2026" }'

Delete a list

Deletes the list and removes the course-access grants that target it. Members are not removed from the academy, but they lose any course access that this list was granting.

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

limit

number

default:"50"

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

offset

number

default:"0"

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

Response fields

data

object

required

Hide properties

members

object[]

required

Hide member properties

string

required

UUID of the student’s user account.

string

required

Student’s email address.

name

string

Display name. May be null.

avatar_url

string

Avatar URL. May be null.

joined_at

string

required

ISO 8601 timestamp of when they joined the list.

pagination

object

required

Show properties

total

number

required

Total active members.

limit

number

required

The limit used.

offset

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.

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

Body parameters

string

A single student email. Provide either email or emails.

emails

string[]

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

send_welcome_email

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.

data

object

required

Hide properties

results

object[]

required

Hide result properties

string

required

The email from the request.

status

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.

student_id

string

UUID of the student. Present unless status is error.

code

string

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

message

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.

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

Path parameters

userId

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 the course-access rules that target it. This is read-only; attach or detach courses from a list in your dashboard.

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

Response fields

data

object

required

Hide properties

courses

object[]

required

Hide course properties

course_id

string

required

UUID of the course.

title

string

required

Course title.

slug

string

required

URL-safe course slug.

term

string

required

How the list grants the course: free, one_time, or included.

price_cents

number

One-time price in cents when term is one_time; otherwise null.

Example response

{
  "data": {
    "courses": [
      {
        "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Cold Outreach Mastery",
        "slug": "cold-outreach-mastery",
        "term": "free",
        "price_cents": null
      }
    ]
  }
}

​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