Public API and data sync
Authenticate a school integration, use the read-only endpoints and build a resilient sync.
The integration API is read-only v1 at /api/public/v1. Use the generated API reference and OpenAPI document on the configured API host for exact deployed response schemas. The dashboard API at /api/v1 has a separate purpose and stability boundary.
Create and authenticate a key
An authorized institution user creates a key in Settings → Developers. Save the secret when shown; it cannot be recovered later. Choose only the scopes the integration needs. Send either Authorization: Bearer <key> or X-API-Key: <key>. The key resolves its school; it does not select arbitrary schools by request parameter.
export TAKADAR_API_URL='https://api.takadar.com/api/public/v1'
# Supply TAKADAR_API_KEY through your server's secret configuration.
curl --get "$TAKADAR_API_URL/students" --header "Authorization: Bearer $TAKADAR_API_KEY" --data-urlencode 'page=1' --data-urlencode 'page_size=100' --data-urlencode 'updated_since=2026-10-01T00:00:00Z'
Keep the key on your server, not in a public browser bundle. Revoke and replace it if exposed. No key has wildcard administrator access or permission to issue wider credentials. Optional internal-API access does not turn a key into a person or authorize identity-dependent staff actions.
Resource and scope reference
| GET path | Scope | Useful resource filters |
|---|---|---|
/me | Valid key | Key identity, scopes and configured rate ceiling |
/events | Valid key | Event catalogue and signature guidance |
/students and /students/{id} | enrollment.read | Collection: status, admission_number |
/enrollments | enrollment.read | session_id, class_id, student_id |
/staff | staff.read | is_active |
/academic-sessions | academic.read | Common collection parameters |
/terms | academic.read | session_id |
/classes | academic.read | programme_id |
/sections | academic.read | class_id |
/subjects | academic.read | Common collection parameters |
/invoices | fees.read | student_id, status |
/payments | payments.read | student_id, status |
Collections accept page, page_size (maximum 200) and inclusive updated_since. They return items, total, page, page_size and pages. A subject can be a higher education course; inspect credit_units and the associated structure rather than renaming identifiers in transit.
Sync without losing changes
Record the start time of a sync, fetch every page and upsert by record ID. Advance the saved watermark only after the whole run succeeds. Re-read an overlapping interval to tolerate changes during pagination; deduplicate repeated records. Page-based reads are not a frozen snapshot, and collection ordering varies by resource.
Combine event handling with polling. Bulk student imports do not emit a webhook per row. Deleted rows are excluded from the live collection; do not assume this delta feed provides deletion tombstones. Plan periodic reconciliation if your local copy must reflect removals.
Money, failures and limits
Amounts are integer minor units plus each row’s ISO currency: 10000 NGN minor units means NGN 100. Do not use the school’s current currency to relabel an older record.
An invalid credential is an authentication failure; a missing scope returns 403 with insufficient_scope. A per-key rate ceiling applies and 429 supplies Retry-After. Honor that header and retry transient failures with backoff. Use /me to inspect the key’s actual ceiling rather than hard-coding it.