Students

Manage student records, enrollment, photos, and promotions.

All endpoints require Authorization: Bearer <token> and X-SCHOOL-ID headers unless noted otherwise.

---

List Students

GET /students

Returns a paginated list of students for the current school.

Query Parameters

Parameter	Type	Required	Default	Description
pageNumber	integer	Yes	0	Zero-indexed page number
pageSize	integer	Yes	50	Number of results per page
search	string	No	—	Search by student name
admission_number	string	No	—	Filter by admission number
batch_id	uuid	No	—	Filter by cohort batch ID

Example

curl -X GET "https://api.vanillatots.com/students?pageNumber=0&pageSize=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID"

Response 200 OK

{
  "page_number": 0,
  "page_size": 25,
  "total_pages": 6,
  "total": 150,
  "data": [
    {
      "id": "uuid",
      "first_name": "John",
      "last_name": "Doe",
      "other_names": "Middle",
      "admission_number": "STU-001",
      "admission_date": "2024-01-15",
      "date_of_birth": "2012-05-20",
      "gender": "Male",
      "religion": "Christianity",
      "blood_group": "O+",
      "nationality": "Nigerian",
      "state_of_origin": "Benue",
      "lga_of_origin": "Makurdi",
      "health_info": "None",
      "school": "uuid",
      "image_url": "https://...",
      "user": "uuid",
      "username": "john.doe",
      "active": true,
      "deleted_at": null
    }
  ]
}

---

Create Student

POST /students

Register a new student in the current school.

Request Body

Field	Type	Required	Description
first_name	string	Yes	Student's first name
last_name	string	Yes	Student's last name
other_names	string	Yes	Middle or other names
admission_number	string	Yes	Unique admission number
admission_date	date	Yes	Date of admission (YYYY-MM-DD)
date_of_birth	date	Yes	Date of birth (YYYY-MM-DD)
gender	string	Yes	Gender
religion	string	Yes	Religion
blood_group	string	Yes	Blood group
nationality	string	Yes	Nationality
state_of_origin	string	Yes	State of origin
lga_of_origin	string	Yes	LGA of origin
health_info	string	Yes	Health information
batch	uuid	Yes	Cohort batch to enroll into
image_url	string	Yes	Profile image URL
contact	object	Yes	Parent/guardian contact info

The contact object:

Field	Type	Required	Description
owner	uuid	Yes	Contact owner user ID
email_address	email	Yes	Contact email
phone_number	string	Yes	Contact phone number
physical_address	string	Yes	Contact physical address

Example

curl -X POST https://api.vanillatots.com/students \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "other_names": "",
    "admission_number": "STU-042",
    "admission_date": "2024-09-01",
    "date_of_birth": "2013-03-15",
    "gender": "Female",
    "religion": "Islam",
    "blood_group": "A+",
    "nationality": "Nigerian",
    "state_of_origin": "Lagos",
    "lga_of_origin": "Ikeja",
    "health_info": "Asthmatic",
    "batch": "batch-uuid",
    "image_url": "",
    "contact": {
      "owner": "parent-uuid",
      "email_address": "parent@email.com",
      "phone_number": "+2348012345678",
      "physical_address": "123 Main Street, Lagos"
    }
  }'

Response 200 OK — Returns the created StudentResponse.

---

Get Student

GET /students/{id}

Retrieve a single student by their UUID.

Path Parameters

Parameter	Type	Description
id	uuid	Student ID

Example

curl -X GET https://api.vanillatots.com/students/{id} \
  -H "Authorization: Bearer $TOKEN"

Response 200 OK — Returns a StudentResponse object.

---

Move Student

PUT /students/{id}/move

Transfer a student from one cohort batch to another.

Path Parameters

Parameter	Type	Description
id	uuid	Student ID

Request Body

Field	Type	Required	Description
studentId	uuid	Yes	Student ID
oldBatch	uuid	Yes	Current batch ID
newBatch	uuid	Yes	Target batch ID

Example

curl -X PUT https://api.vanillatots.com/students/{id}/move \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "studentId": "student-uuid",
    "oldBatch": "old-batch-uuid",
    "newBatch": "new-batch-uuid"
  }'

Response 200 OK — Returns the updated StudentResponse.

---

Upload Student Photo

PUT /students/{id}/upload-photo

Upload or update a student's profile photo.

Path Parameters

Parameter	Type	Description
id	uuid	Student ID

Query Parameters

Parameter	Type	Required	Description
file	binary	Yes	Image file

Response 200 OK — Returns the updated StudentResponse.

---

Promote Students

PUT /students/promote

Bulk promote students from one cohort batch to another.

Request Body

Field	Type	Required	Description
from_batch	uuid	Yes	Source batch ID
to_batch	uuid	Yes	Destination batch ID
students	uuid[]	Yes	Array of student IDs to promote

Example

curl -X PUT https://api.vanillatots.com/students/promote \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "from_batch": "old-batch-uuid",
      "to_batch": "new-batch-uuid",
      "students": ["student-uuid-1", "student-uuid-2"]
    }
  }'

Response 200 OK — Returns an array of updated StudentResponse objects.

---

Recycle Bin

GET /students/bin

List soft-deleted students.

Example

curl -X GET https://api.vanillatots.com/students/bin \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID"

Response 200 OK — Returns an array of StudentResponse objects.