Accounts API — Users and Person Identity Records

The Accounts API is built around a deliberate two-model architecture: User handles authentication credentials, role assignment, and system access, while Person stores every piece of demographic and contact information about the human behind that account. A Person optionally links to a User via a one-to-one relationship — allowing the school to maintain identity records for individuals (such as parents or prospective students) who do not yet have login access. Together these two models form the identity backbone for all other modules in Gobarau Academy.

User vs Person design: User is Django’s authentication record — it stores the login credentials, role, and wing assignment that govern what a principal, teacher, or student can access. Person is the demographic profile — it stores names, dates of birth, contact details, nationality, and any custom metadata. Keeping these concerns separate means you can manage a person’s demographic record independently of their login account, and you can bulk-import identity data before accounts are issued.

Authentication Requirements

All endpoints in the Accounts API require a valid authenticated session or bearer token. The specific permission class varies by resource:

Endpoint	Permission
`/api/accounts/users/`	`IsAuthenticated` + `IsAdminLevel`
`/api/accounts/people/`	`IsAuthenticated` + `IsStaffOrAdmin`

IsAdminLevel restricts access to users whose role is super_admin, principal, or vice_principal.IsStaffOrAdmin extends this to also allow bursar and teacher roles. Any other role (e.g. student, parent) will receive 403 Forbidden.

Users

The Users endpoint manages User records — the authentication and authorisation layer for every person in the system. A user’s role determines their permissions across the entire API, and their wing places them in one of the school’s organisational divisions.

Method	URL
`GET`	`/api/accounts/users/`
`POST`	`/api/accounts/users/`
`GET`	`/api/accounts/users/{id}/`
`PUT`	`/api/accounts/users/{id}/`
`PATCH`	`/api/accounts/users/{id}/`
`DELETE`	`/api/accounts/users/{id}/`

Request Fields

username

string

required

Unique login username. Inherited from Django’s AbstractUser.

string

User’s email address. Inherited from AbstractUser.

first_name

string

First name on the authentication record. Inherited from AbstractUser.

last_name

string

Last name on the authentication record. Inherited from AbstractUser.

password

string

role

string

Role assigned to the user. Controls permission level throughout the API. Must be one of:

Value	Label
`super_admin`	Super Admin
`principal`	Principal
`vice_principal`	Vice Principal
`bursar`	Bursar
`teacher`	Teacher
`student`	Student
`parent`	Parent
`alumni`	Alumni
`nurse`	School Nurse
`counsellor`	Counsellor

Defaults to student.

wing

string

Wing the user belongs to. Must be one of:

Value	Label
`regular`	Regular
`islamiyyah`	Islamiyyah
`tahfeez`	Tahfeez

Defaults to regular.

is_verified

boolean

Indicates whether the user’s identity has been verified by an administrator. Defaults to false.

preferences

object

Free-form JSON object for storing user-specific UI or notification preferences. Defaults to {}.

is_active

boolean

Whether the user account is active. Inherited from AbstractUser. Defaults to true.

Response Fields

integer

Database primary key.

username

string

Unique login username.

string

Email address.

first_name

string

First name.

last_name

string

Last name.

role

string

The user’s assigned role value (e.g. "teacher", "student").

wing

string

Wing assignment value (e.g. "regular", "tahfeez").

is_verified

boolean

Identity verification status.

preferences

object

JSON preferences object.

is_active

boolean

Whether this account is active.

is_staff

boolean

Django admin site access flag. Inherited from AbstractUser.

is_superuser

boolean

Django superuser flag. Inherited from AbstractUser.

date_joined

string (ISO 8601)

Timestamp of account creation. Inherited from AbstractUser.

Timestamp of the most recent login. Inherited from AbstractUser.

groups

array

List of Django permission group IDs. Inherited from AbstractUser.

user_permissions

array

List of explicit Django permission IDs. Inherited from AbstractUser.

Examples

# List all users (admin-level only)
curl -X GET https://api.gobarau.edu.ng/api/accounts/users/ \
  -H "Authorization: Bearer <token>"

# Create a new teacher account in the Islamiyyah wing
curl -X POST https://api.gobarau.edu.ng/api/accounts/users/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "malam.ibrahim",
    "email": "[email protected]",
    "first_name": "Ibrahim",
    "last_name": "Abdullahi",
    "password": "SecurePass123!",
    "role": "teacher",
    "wing": "islamiyyah",
    "is_verified": true
  }'

# Promote an existing user to vice_principal
curl -X PATCH https://api.gobarau.edu.ng/api/accounts/users/14/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "vice_principal"}'

Response Example

{
  "id": 14,
  "username": "malam.ibrahim",
  "email": "[email protected]",
  "first_name": "Ibrahim",
  "last_name": "Abdullahi",
  "role": "teacher",
  "wing": "islamiyyah",
  "is_verified": true,
  "preferences": {},
  "is_active": true,
  "is_staff": false,
  "is_superuser": false,
  "date_joined": "2025-08-15T09:00:00Z",
  "last_login": null,
  "groups": [],
  "user_permissions": []
}

People

The People endpoint manages Person records — the full demographic and contact profile for every human in the system. A person may or may not have a linked User account. The full_name field is a read-only computed property assembled from first_name, middle_name, and last_name. Person inherits from both SoftDeleteModel and AuditMixin. Soft-deleted records (where is_archived = true) are excluded from the default queryset but remain in the database. The response also includes created_by and updated_by audit fields.

Method	URL
`GET`	`/api/accounts/people/`
`POST`	`/api/accounts/people/`
`GET`	`/api/accounts/people/{id}/`
`PUT`	`/api/accounts/people/{id}/`
`PATCH`	`/api/accounts/people/{id}/`
`DELETE`	`/api/accounts/people/{id}/`

Results are ordered by last_name, then first_name by default. Use filtering or search on your client side if you need a different ordering.

Request Fields

user

integer | null

Primary key of the linked User account. One-to-one — each user can have at most one Person record. Leave null for individuals who do not yet have a login account.

first_name

string

required

Legal first name (max 100 characters).

last_name

string

required

Legal last name (max 100 characters).

middle_name

string

Middle name (max 100 characters). Defaults to an empty string.

preferred_name

string

Name the person prefers to be called (max 100 characters). Defaults to an empty string.

date_of_birth

string (date)

Date of birth in YYYY-MM-DD format. Nullable.

gender

string

Gender code. Must be one of:

Value	Label
`M`	Male
`F`	Female

Defaults to an empty string (not specified).

state_of_origin

string

Nigerian state of origin. Must be one of the 36 state slugs (e.g. "kano", "lagos", "fct") or left blank. Defaults to an empty string.

lga

string

Local Government Area (max 100 characters). Defaults to an empty string.

religion

string

Religion of the person (max 50 characters). Defaults to an empty string.

nationality

string

Nationality (max 50 characters). Defaults to "Nigerian".

phone_primary

string

Primary contact phone number (max 20 characters). Indexed for fast lookup.

phone_secondary

string

Secondary contact phone number (max 20 characters).

email_personal

string

Personal email address (distinct from the login User.email).

address

string

Residential or contact address.

photo

file

Profile photo. Uploaded to people/photos/.

national_id

string

National Identity Number (NIN) or equivalent (max 50 characters).

external_ref

string

External reference or legacy system ID (max 100 characters).

language

string

Preferred language for communication (max 50 characters). Defaults to "English".

metadata

object

Arbitrary JSON object for additional structured data (e.g. custom intake form answers). Defaults to {}.

Response Fields

integer

Database primary key.

public_id

string (UUID)

Stable public identifier.

user

integer | null

FK to the linked User, or null if no account is linked.

full_name

string

Read-only computed property. Assembled as first_name + middle_name + last_name with blank middle names omitted.

first_name

string

Legal first name.

last_name

string

Legal last name.

middle_name

string

Middle name, or empty string.

preferred_name

string

Preferred name, or empty string.

date_of_birth

string (date) | null

Date of birth.

gender

string

Gender code (M, F, or empty string).

state_of_origin

string

Nigerian state slug, or empty string.

lga

string

Local government area, or empty string.

religion

string

Religion, or empty string.

nationality

string

Nationality.

phone_primary

string

Primary phone number.

phone_secondary

string

Secondary phone number.

email_personal

string

Personal email address.

address

string

Residential address.

photo

string | null

Relative URL of the uploaded profile photo, or null.

national_id

string

National Identity Number, or empty string.

external_ref

string

External reference ID, or empty string.

language

string

Preferred language.

metadata

object

Custom JSON metadata.

is_archived

boolean

Whether this record has been soft-deleted.

archived_at

string (ISO 8601) | null

Timestamp of archival, or null if not archived.

archived_by

integer | null

User PK who archived this record, or null.

created_at

string (ISO 8601)

Timestamp of record creation.

updated_at

string (ISO 8601)

Timestamp of last update.

created_by

integer | null

User PK of the creator.

updated_by

integer | null

User PK of the last editor.

Examples

# List all person records (staff and admin roles)
curl -X GET https://api.gobarau.edu.ng/api/accounts/people/ \
  -H "Authorization: Bearer <token>"

# Create a person record linked to user ID 14
curl -X POST https://api.gobarau.edu.ng/api/accounts/people/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": 14,
    "first_name": "Ibrahim",
    "last_name": "Abdullahi",
    "middle_name": "Yusuf",
    "date_of_birth": "1990-03-15",
    "gender": "M",
    "state_of_origin": "kano",
    "lga": "Nassarawa",
    "religion": "Islam",
    "nationality": "Nigerian",
    "phone_primary": "+2348031234567",
    "email_personal": "[email protected]",
    "language": "Hausa"
  }'

# Create a person record with no linked account (e.g. a parent contact)
curl -X POST https://api.gobarau.edu.ng/api/accounts/people/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": null,
    "first_name": "Fatima",
    "last_name": "Musa",
    "phone_primary": "+2348059876543",
    "nationality": "Nigerian",
    "metadata": {"intake_year": 2025, "source": "parent_form"}
  }'

Response Example

{
  "id": 28,
  "public_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "user": 14,
  "full_name": "Ibrahim Yusuf Abdullahi",
  "first_name": "Ibrahim",
  "last_name": "Abdullahi",
  "middle_name": "Yusuf",
  "preferred_name": "",
  "date_of_birth": "1990-03-15",
  "gender": "M",
  "state_of_origin": "kano",
  "lga": "Nassarawa",
  "religion": "Islam",
  "nationality": "Nigerian",
  "phone_primary": "+2348031234567",
  "phone_secondary": "",
  "email_personal": "[email protected]",
  "address": "",
  "photo": null,
  "national_id": "",
  "external_ref": "",
  "language": "Hausa",
  "metadata": {},
  "is_archived": false,
  "archived_at": null,
  "archived_by": null,
  "created_at": "2025-08-15T09:15:00Z",
  "updated_at": "2025-08-15T09:15:00Z",
  "created_by": 1,
  "updated_by": null
}

Endpoint Summary

Resource	Base URL	Permission	Inherits
Users	`/api/accounts/users/`	`IsAdminLevel`	Django `AbstractUser`
People	`/api/accounts/people/`	`IsStaffOrAdmin`	`SoftDeleteModel` + `AuditMixin`

When creating a new staff or student record, the recommended workflow is: (1) POST /api/accounts/users/ to create the login account, then (2) POST /api/accounts/people/ with the returned user ID to attach the demographic profile. This keeps authentication and identity concerns cleanly separated.

Administration

People & Admissions

Academics

Finance & Services

Communication & Content

Accounts API — Users and Person Identity Records

Authentication Requirements

Users

Request Fields

Response Fields

Examples

Response Example

People

Request Fields

Response Fields

Examples

Response Example

Endpoint Summary

Build docs developers (and LLMs) love

Administration

People & Admissions

Academics

Finance & Services

Communication & Content

Documentation Index

​Authentication Requirements

​Users

​Request Fields

​Response Fields

​Examples

​Response Example

​People

​Request Fields

​Response Fields

​Examples

​Response Example

​Endpoint Summary

Build docs developers (and LLMs) love

Authentication Requirements

Users

Request Fields

Response Fields

Examples

Response Example

People

Request Fields

Response Fields

Examples

Response Example

Endpoint Summary