Skip to main content
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

​
limit
number
default:"50"
Number of students to return. Minimum 1, maximum 100.
​
offset
number
default:"0"
Number of students to skip before returning results. Use with limit for pagination.

​
Response fields

​
data
object
required

​
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",
        "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

​
email
string
required
Email address of the student. Must be a valid email format.
​
name
string
Display name for the student. Maximum 200 characters. Optional.
​
course_ids
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.
​
list_ids
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. Use list_ids for cohort or tier access you may want to revoke later, and course_ids for a permanent per-course grant. Optional.
​
send_welcome_email
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"]
  }'

​
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

​
studentId
string
required
UUID of the student. Must be a valid UUID or the request returns a 400.

​
Response fields

​
data
object
required

​
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",
    "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

​
studentId
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

​
data
object
required

​
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
  }
}