Add, List, and Remove Students in Your Academy API

The students endpoints let you manage the people who learn in your academy. You can list all students with pagination, add new students and optionally enroll them in courses at the same time, retrieve a single student’s profile and detailed progress, and remove a student from your academy. All endpoints require your API key in the Authorization header. See Authentication.

List students

Returns a paginated list of active students in your academy.

GET /api/v1/students

Query parameters

number

default:"50"

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

number

default:"0"

Number of students to skip before returning results. Use with limit for pagination.

Response fields

object

required

Hide properties

object[]

required

Array of student objects, ordered by joined_at descending.

Hide student properties

string

required

UUID of the student’s user account.

string

required

Student’s email address.

string

Student’s display name. May be null if not set.

string

URL of the student’s avatar image. May be null.

string

required

ISO 8601 timestamp of when the student joined the academy.

object

required

Summary of what the student holds through your academy’s offers and purchases.

Show access properties

boolean

required

true when the student holds your Academy Pass (access to every course).

number

required

Number of active offers the student currently holds, the Pass included.

boolean

required

true when the student has at least one paid, non-refunded payment in your academy.

number

required

Number of active course enrollments.

object[]

required

Array of active enrollment summaries. An enrollment means the student started the course (it appears in their My Learning); it is not the full picture of what they can open. A student can have access to courses they have not started yet, through free courses, offers they hold, or purchases.

Show enrollment properties

string

required

UUID of the enrollment record.

string

required

UUID of the enrolled course.

string

required

ISO 8601 timestamp of enrollment.

string

ISO 8601 timestamp of completion. null if not yet completed.

object

required

Hide properties

number

required

Total number of students in the academy.

number

required

The limit value used for this request.

number

required

The offset value used for this request.

Example request

curl "https://yourname.fayneos.com/api/v1/students?limit=10&offset=0" \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response

{
  "data": {
    "students": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "email": "alex@example.com",
        "name": "Alex Rivera",
        "avatar_url": "https://cdn.example.com/avatars/alex.jpg",
        "joined_at": "2025-03-15T09:22:00Z",
        "access": {
          "holds_pass": false,
          "offer_count": 1,
          "has_purchase": true
        },
        "courses_enrolled": 2,
        "enrollments": [
          {
            "id": "e1f2a3b4-c5d6-7890-efab-123456789abc",
            "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "enrolled_at": "2025-03-15T09:22:00Z",
            "completed_at": null
          }

        ]
      }
    ],
    "pagination": {
      "total": 42,
      "limit": 10,
      "offset": 0
    }
  }
}

Add a student

Adds a new student to your academy and optionally enrolls them in one or more courses in a single request.

POST /api/v1/students

Body parameters

string

required

Email address of the student. Must be a valid email format.

string

Display name for the student. Maximum 200 characters. Optional.

string[]

Array of course UUIDs to enroll the student in. Maximum 50 course IDs per request. Each course must be published. Optional. Creates a permanent enrollment per course.

string[]

Array of list UUIDs to add the student to. Maximum 50 per request. Each list must exist in this academy, or the request returns 400 invalid_lists. Offer-managed lists return 400 list_managed_by_offer; grant the offer instead. All ids are validated before the student account is created, so a rejected request creates nothing. Use list_ids for cohort or tier access you may want to revoke later, and course_ids for an individual course assignment. Optional.

boolean

default:"true"

Whether to send the magic-link welcome email to the new student. Set to false for silent imports. Optional.

Response fields

Returns the newly created student with a 201 status code. The response contains id, email, name, a membershipStatus field (created or reactivated), and an enrollments array whose items have id, course_id, and course_title. This is a smaller object than the list endpoint’s student: it does not include avatar_url, joined_at, or courses_enrolled. Adding a student who is already an active member of the academy returns 409 already_exists.

Example request

curl -X POST https://yourname.fayneos.com/api/v1/students \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jamie@example.com",
    "name": "Jamie Chen",
    "course_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'

const response = await fetch('https://yourname.fayneos.com/api/v1/students', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'jamie@example.com',
    name: 'Jamie Chen',
    course_ids: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890']
  })
});
const { data } = await response.json();

Get a student

Returns the full profile and enrollment detail for a single student, including per-course progress.

GET /api/v1/students/:studentId

Path parameters

string

required

UUID of the student. Must be a valid UUID or the request returns a 400.

Response fields

object

required

Hide properties

string

required

UUID of the student’s user account.

string

required

Student’s email address.

string

Student’s display name. May be null.

string

URL of the student’s avatar image. May be null.

string

required

ISO 8601 timestamp of when the student joined the academy.

object

required

What the student holds through offers, purchases, and course assignments.

Hide access properties

boolean

required

true when the student holds your Academy Pass (access to every course).

number

required

Number of active offers the student currently holds, the Pass included.

boolean

required

true when the student has at least one paid, non-refunded payment in your academy.

object[]

required

The student’s live course assignments (given through this API or the dashboard). A grant can exist before the student has opened the course, so it may not have a matching enrollment yet.

Show grant properties

string

required

UUID of the assigned course.

string

required

ISO 8601 timestamp of when the course was assigned.

object[]

required

Array of active enrollments with full progress detail, ordered by enrolled_at descending. An enrollment means the student started the course; access itself can also come from free courses, offers, or purchases that have no enrollment yet.

Hide enrollment properties

string

required

UUID of the enrollment record.

string

required

UUID of the enrolled course.

string

required

Display title of the course.

string

required

URL-safe slug of the course.

string

required

ISO 8601 timestamp of enrollment.

string

ISO 8601 timestamp of course completion. null if not yet completed.

number

required

Total number of published lessons in the course.

number

required

Number of lessons the student has completed.

number

required

Completion percentage from 0 to 100, rounded to the nearest integer.

Example request

curl https://yourname.fayneos.com/api/v1/students/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "email": "alex@example.com",
    "name": "Alex Rivera",
    "avatar_url": "https://cdn.example.com/avatars/alex.jpg",
    "joined_at": "2025-03-15T09:22:00Z",
    "access": {
      "holds_pass": false,
      "offer_count": 1,
      "has_purchase": true,
      "grants": [
        {
          "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "granted_at": "2025-03-15T09:22:00Z"
        }
      ]
    },
    "enrollments": [
      {
        "id": "e1f2a3b4-c5d6-7890-efab-123456789abc",
        "course_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "course_title": "Cold Outreach Mastery",
        "course_slug": "cold-outreach-mastery",
        "enrolled_at": "2025-03-15T09:22:00Z",
        "completed_at": null,
        "total_lessons": 12,
        "completed_lessons": 5,
        "progress": 42
      }
    ]
  }
}

Remove a student

Removes a student from your academy. This revokes all of their course enrollments and deletes all of their lesson progress, and cannot be undone. The student’s Fayne account itself is not deleted; they are only removed from this academy.

DELETE /api/v1/students/:studentId

Path parameters

string

required

UUID of the student to remove.

Removing a student deletes all of their progress data in this academy and revokes access to every course. This cannot be reversed. Their Fayne account is not deleted.

Response fields

object

required

Hide properties

boolean

required

Always true when the operation succeeds.

Example request

curl -X DELETE \
  https://yourname.fayneos.com/api/v1/students/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response

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

Authentication

Endpoints

Guides

Add, List, and Remove Students in Your Academy API

List students

Query parameters

Response fields

Example request

Example response

Add a student

Body parameters

Response fields

Example request

Get a student

Path parameters

Response fields

Example request

Example response

Remove a student

Path parameters

Response fields

Example request

Example response

​List students

​Query parameters

​Response fields

​Example request

​Example response

​Add a student

​Body parameters

​Response fields

​Example request

​Get a student

​Path parameters

​Response fields

​Example request

​Example response

​Remove a student

​Path parameters

​Response fields

​Example request

​Example response

List students

Query parameters

Response fields

Example request

Example response

Add a student

Body parameters

Response fields

Example request

Get a student

Path parameters

Response fields

Example request

Example response

Remove a student

Path parameters

Response fields

Example request

Example response