API reference · v1Implementation-aligned · July 2026

HallHop developer documentation

HAC API,
fully mapped.

A stateless Flask API that turns authorized Home Access Center pages into structured JSON for student tools and HallHop workflows.

https://hacapi-hh.vercel.app

documented routes

100/hr

default IP rate limit

Central

default date timezone

Authentication model

Credentials travel with the request.

The current API does not issue access tokens or maintain server-side login sessions. With the exception of the health and logout routes, every request includes HAC credentials in a JSON body. The server creates a temporary requests session, logs in to HAC, retrieves the requested page, and returns parsed JSON.

Use only from a trusted client and over HTTPS.

Never put real credentials in source control, URLs, analytics, screenshots, or client logs. Production requests are redirected to HTTPS, but consumers still own safe credential handling.

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Quickstart

Make the first request.

Send JSON with a content type header. Check the HTTP status before reading a successful payload; failures consistently use an error field.

JavaScript · progress report

const response = await fetch("https://hacapi-hh.vercel.app/api/getReport", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: process.env.HAC_USERNAME,
    password: process.env.HAC_PASSWORD,
    base_url: "https://accesscenter.roundrockisd.org/"
  })
});

if (!response.ok) {
  const problem = await response.json();
  throw new Error(problem.error ?? "HAC request failed");
}

const report = await response.json();

cURL · day type

curl -X POST "https://hacapi-hh.vercel.app/api/getDayType" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "YOUR_HAC_USERNAME",
    "password": "YOUR_HAC_PASSWORD",
    "target_date": "2026-07-20"
  }'

Endpoint reference

Every route.

Open a route for request fields, responses, and errors.

Service

Check availability and validate credentials without retrieving student records.

GET/Health check

Returns a simple service welcome response. No HAC request is made.

No auth200 OK

Example response

{
  "success": true,
  "message": "Welcome to the HAC API."
}

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/loginValidate HAC credentials

Creates a temporary HAC session, attempts login, and returns success. Limited to 5 requests per minute per client IP.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "success": true
}

Possible errors

400 missing input · 401 invalid credentials · 429 rate limited · 500 upstream failure

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/logoutAcknowledge local logout

Returns a logout acknowledgement. The server stores no persistent HAC session, so clients remain responsible for deleting credentials locally.

No auth200 OK

Example response

{
  "success": true,
  "message": "Logged out locally"
}

Examples use fictional values. Response content depends on the HAC district template and available student records.

Student profile

Read the active student’s identity and registration information.

POST/api/getNameGet active student name

Reads the current student name from HAC Week View.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "name": "Sample Student"
}

Possible errors

400 · 401 · 404 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getInfoGet registration profile

Returns identity and registration fields parsed from the HAC Registration page.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "name": "Sample Student",
  "grade": "11",
  "school": "Example High School",
  "dob": "01/01/2009",
  "counselor": "Counselor Name",
  "language": "English",
  "cohort_year": "2027"
}

Possible errors

400 · 401 · 404 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

Academics & schedule

Retrieve grades, assignments, schedules, transcripts, rank, and A/B day context.

POST/api/getAveragesGet course averages

Returns a course-name-to-average map from the HAC Assignments page.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "AP English Language": "94.20%",
  "Precalculus": "91.80%"
}

Possible errors

400 · 401 · 404 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getAssignmentsGet assignments

Returns assignment and category rows for every course, or courses matching the optional class filter.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

classOptional

string

Optional partial course name or course-code filter.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.
class	string	Optional	Optional partial course name or course-code filter.

Example response

{
  "AP English Language": {
    "code": "ENG301",
    "average": "94.20%",
    "assignments": [["Essay 2", "09/18", "95", "100"]],
    "categories": [["Major", "60%", "94.5%"]]
  }
}

Possible errors

400 · 401 · 404 no matching assignments · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getReportGet progress report

Returns the active student’s interim progress report. If student_id is supplied, the API switches students before parsing the report.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

student_idOptional

string

Optional HAC student ID for multi-student accounts.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.
student_id	string	Optional	Optional HAC student ID for multi-student accounts.

Example response

{
  "headers": ["Class Code", "Class", "Period", "Teacher", "Room", "Average"],
  "data": [["MTH401", "Precalculus", "3", "Teacher Name", "204", "91.80%"]]
}

Possible errors

400 switch failure · 401 · 404 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getIprGet interim progress report

Returns the same parsed Interim Progress report structure used by getReport for the active student.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "headers": ["Class Code", "Class", "Period", "Teacher", "Room", "Average"],
  "data": [["SCI301", "Physics", "2", "Teacher Name", "118", "93.00%"]]
}

Possible errors

400 · 401 · 404 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getTranscriptGet transcript

Returns semester groupings, course rows, credits, cumulative GPA fields, and rank parsed from HAC Transcript.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "2025 - Semester 1": {
    "year": "2025",
    "semester": "1",
    "grade": "10",
    "school": "Example High School",
    "data": [["ENG201", "English II", "A", "1.0"]],
    "credits": "4.0"
  },
  "Rank": "42 / 815"
}

Possible errors

400 · 401 · 404 transcript unavailable · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getRankGet class rank

Returns the rank field parsed from the HAC Transcript page.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "rank": "42 / 815"
}

Possible errors

400 · 401 · 404 rank unavailable · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/api/getDayTypeGet A/B day type

Parses HAC Week View for the target week and resolves the requested date in America/Chicago time.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

target_dateOptional

string · date

Optional. YYYY-MM-DD or MM/DD/YYYY; defaults to today in Central Time.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.
target_date	string · date	Optional	Optional. YYYY-MM-DD or MM/DD/YYYY; defaults to today in Central Time.

Example response

{
  "target_date": "2026-07-20",
  "week_start": "2026-07-20",
  "day_type": "A",
  "is_weekend": false,
  "found": true,
  "week": [
    { "weekday": "Monday", "date": "2026-07-20", "mmdd": "07/20", "day_type": "A" }
  ]
}

Possible errors

400 invalid date · 401 · 404 Week View parse failure · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

Multi-student accounts

List students attached to a HAC account, inspect the active student, and switch context.

POST/lookup/studentsList students

Returns student IDs and names from the HAC Student Picker.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "students": [
    { "id": "100001", "name": "Sample Student" },
    { "id": "100002", "name": "Second Student" }
  ]
}

Possible errors

400 · 401 · 404 no students · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/lookup/currentGet active student

Reads the currently selected student from the HAC home-page banner.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.

Example response

{
  "success": true,
  "active_student": { "name": "Sample Student" }
}

Possible errors

400 · 401 · 404 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/lookup/switchSwitch active student

Submits the HAC Student Picker form with the requested student ID for the temporary session created by this request.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

student_idRequired

string

Student ID returned by /lookup/students.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.
student_id	string	Required	Student ID returned by /lookup/students.

Example response

{
  "success": true,
  "message": "Switched to student 100002"
}

Possible errors

400 missing/invalid student · 401 · 429 · 500

Examples use fictional values. Response content depends on the HAC district template and available student records.

Hall pass logs

Create and close checkout records in the configured Supabase checkouts table.

POST/logs/checkoutCreate checkout

Validates HAC credentials, then inserts an open checkout record through the Supabase service role.

HAC credentials201 Created

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

student_idRequired

string

HAC student identifier.

student_nameRequired

string

Student display name.

class_nameRequired

string

Current class.

periodRequired

integer · 1–8

Current period.

roomRequired

string

Origin room.

teacherRequired

string

Origin teacher.

checkout_timeRequired

ISO 8601 timestamp

Checkout time with timezone.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.
student_id	string	Required	HAC student identifier.
student_name	string	Required	Student display name.
class_name	string	Required	Current class.
period	integer · 1–8	Required	Current period.
room	string	Required	Origin room.
teacher	string	Required	Origin teacher.
checkout_time	ISO 8601 timestamp	Required	Checkout time with timezone.

Example response

{
  "id": "5b8c2f52-1a2b-4d5e-9f10-123456789abc",
  "student_id": "100001",
  "class_name": "Precalculus",
  "period": 3,
  "room": "204",
  "checkout_time": "2026-07-20T10:18:00-05:00",
  "checkin_time": null,
  "duration_sec": null
}

Possible errors

400 missing fields · 401 · 429 · 500 · 503 Supabase unavailable

Examples use fictional values. Response content depends on the HAC district template and available student records.

POST/logs/checkinClose checkout

Validates HAC credentials, then updates a checkout by UUID with its return time and computed duration.

HAC credentials200 OK

JSON request body

usernameRequired

string

Home Access Center username.

passwordRequired

string

Home Access Center password.

base_urlOptional

string · URL

HAC origin. Defaults to Round Rock ISD Access Center.

checkout_idRequired

string · UUID

ID returned by /logs/checkout.

checkin_timeRequired

ISO 8601 timestamp

Return time with timezone.

duration_secRequired

integer · ≥0

Elapsed time in seconds.

Field	Type	Requirement	Description
username	string	Required	Home Access Center username.
password	string	Required	Home Access Center password.
base_url	string · URL	Optional	HAC origin. Defaults to Round Rock ISD Access Center.
checkout_id	string · UUID	Required	ID returned by /logs/checkout.
checkin_time	ISO 8601 timestamp	Required	Return time with timezone.
duration_sec	integer · ≥0	Required	Elapsed time in seconds.

Example response

[
  {
    "id": "5b8c2f52-1a2b-4d5e-9f10-123456789abc",
    "checkin_time": "2026-07-20T10:24:30-05:00",
    "duration_sec": 390
  }
]

Possible errors

400 missing fields · 401 · 404 checkout not found · 429 · 500 · 503 Supabase unavailable

Examples use fictional values. Response content depends on the HAC district template and available student records.

Error contract

Failures stay readable.

{
  "error": "Invalid credentials or HAC login failed"
}

400	Missing fields, invalid dates, invalid base URL, or student-switch failure
401	HAC rejected the supplied credentials
404	Requested HAC data or checkout record was not found
429	The client IP exceeded a configured rate limit
500	Unexpected upstream, parser, or server failure
503	Supabase is not configured or could not initialize

Limits & transport

Know the guardrails.

100 / hour

Default Flask-Limiter rule applied per remote IP.

5 / minute

Stricter rule on POST /api/login per remote IP.

10 seconds

Timeout used for HAC GET and POST requests; retry logic covers 429 and common 5xx responses.

CORS currently allows every origin, common HTTP methods, and requested headers. Browser credentials are disabled. Treat this as a public network surface and do not rely on CORS as authentication.

Security notes

Read before integrating.

No API token layer

Authorization is currently possession of valid HAC credentials. Add an application-level identity and authorization layer before broader third-party use.

Stateless HAC sessions

Each protected call logs in again. The code does not persist a server-side HAC session, and /api/logout only acknowledges local cleanup.

Open CORS policy

Any web origin can call the service. Restrict allowed origins for controlled production clients.

Service-role database access

Checkout logging uses SUPABASE_SERVICE_ROLE_KEY. Keep it server-only and review table policy; the included schema disables row-level security.

Upstream HTML dependency

Responses depend on HAC page markup. A district HAC update can change or break parsing without changing this API contract.

Sensitive response data

Registration, grades, assignments, transcripts, schedules, and movement logs are student records. Minimize collection, logging, retention, and display.

This section describes the current repository implementation. It is not a security certification or a substitute for district privacy, legal, infrastructure, and vendor review.

Local development

Run the service.

Terminal

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export FLASK_ENV=development
python app.py

.env · only required for /logs routes

SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_SERVICE_ROLE_KEY=YOUR_SERVER_ONLY_SERVICE_ROLE_KEY

Local URL

http://localhost:5000

Setting FLASK_ENV=development prevents the HTTPS redirect during local work.

Production adapters

The repository includes a Vercel Python build configuration and a Gunicorn Procfile for process-based hosting.

Need an integration review?

Bring the workflow, district HAC origin, and data boundary. We’ll help identify the smallest useful integration.

Contact sales

HAC API,fully mapped.

Credentials travel with the request.

Use only from a trusted client and over HTTPS.

Make the first request.

Every route.

Service

JSON request body

Possible errors

Student profile

JSON request body

Possible errors

JSON request body

Possible errors

Academics & schedule

JSON request body

Possible errors

JSON request body

Possible errors

JSON request body

Possible errors

JSON request body

Possible errors

JSON request body

Possible errors

JSON request body

Possible errors

JSON request body

Possible errors

Multi-student accounts

JSON request body

Possible errors

JSON request body

Possible errors

JSON request body

Possible errors

Hall pass logs

JSON request body

Possible errors

JSON request body

Possible errors

Failures stay readable.

Know the guardrails.

Read before integrating.

No API token layer

Stateless HAC sessions

Open CORS policy

Service-role database access

Upstream HTML dependency

Sensitive response data

Run the service.

Local URL

Production adapters

Need an integration review?

HAC API,
fully mapped.