Scoliom Scolarité API — v1

Read-only REST API · JSON · one key per connected software · updated 28 October 2026

In short. The API lets another software of a school (accounting, reporting, a dashboard…) read its students, classes, levels, instalments, payments and absences. It cannot change anything. It is closed by default: it only opens when the school's management creates a key, and the management can revoke that key at any time.
Plain-language overview for school management: the API on scoliom.com.

1. Getting a key

The school's management (director or administrator account) opens Settings › API in Scoliom Scolarité, names the key after the software it will connect (for example “Accounting”) and clicks Create a key.

The key looks like sco_ followed by 40 characters. It is shown only once: Scoliom keeps only a fingerprint of it and cannot display it again. If it is lost, revoke it and create a new one.
A key only ever sees its own school.
A school can have up to 5 active keys: one per connected software, so that each one can be revoked on its own.
The same screen shows the API address of the school, the date each key was last used and its number of calls.

2. Calling the API

Address (schools hosted on app.scoliom.com — the exact address is shown in Settings › API):

https://app.scoliom.com/api/v1.php?resource=<resource>

Send the key in the Authorization header:

curl -H "Authorization: Bearer sco_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     "https://app.scoliom.com/api/v1.php?resource=students&status=inscrit&per_page=100"

If a proxy strips Authorization, send X-Api-Key: sco_… instead.
Never put the key in the URL: the request is refused (400 key_in_url), because URLs end up in server logs.
HTTPS only. GET (and HEAD) only: any other method gets 405.
The resource can also be given as a path: /api/v1.php/students.
The API is meant to be called from a server. It sends no CORS headers: do not put a key in a web page.

3. Conventions

Lists and pagination

{
  "data": [ { … }, { … } ],
  "meta": { "page": 1, "per_page": 100, "total": 412, "pages": 5 }
}

page (from 1) and per_page (1 to 200, default 100). Items are sorted by id, so a page does not shift when new records are added at the end.

Formats

Dates: YYYY-MM-DD. Date-times: ISO 8601 with offset (2026-10-28T12:00:00+01:00).
Amounts: numbers with two decimals, in the school's currency (MAD for Moroccan schools).
Status values are stable codes (in French, as in the product); their meaning is given below.
Unknown or empty values are null.

Rate limit

60 requests per minute per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Beyond the limit: 429 rate_limited with Retry-After: 60. Repeated invalid keys from the same address (20 in 10 minutes) are refused for 10 minutes (429 too_many_failures).

Errors

{ "error": { "code": "invalid_parameter", "message": "Parameter 'per_page' must be between 1 and 200." } }

HTTP	code	Meaning
400	`invalid_parameter`, `missing_resource`, `key_in_url`	The request is malformed.
401	`missing_key`, `invalid_key`	No key, or a key that is unknown or revoked.
403	`https_required`	The request did not use HTTPS.
404	`unknown_resource`, `not_found`	Unknown resource, or a school year of another school.
405	`method_not_allowed`	The API is read-only.
429	`rate_limited`, `too_many_failures`	Slow down (see above).
500	`server_error`	Retry later.

4. Resources

`school` — the school of the key

Fields: id, name, name_ar, city, country, language, current_school_year (id, label, start_date, end_date). A single object, no pagination. Handy to check a key.

`levels` — levels (grades)

Fields: id, cycle, label, label_ar, order, next_level_id (the level a student moves up to), active.

`classes` — classes of a school year

Parameters: school_year_id (default: the current year), level_id.
Fields: id, school_year_id, level_id, label, label_ar, code, capacity, students_count (enrolled students), active.

`students` — students

Parameters: class_id, level_id, status, updated_since (date or ISO 8601 date-time: for incremental synchronisation).
Fields: id, number (the school's student number), national_student_number (Massar code in Morocco), last_name, first_name, last_name_ar, first_name_ar, sex (M/F), birth_date, status, level_id, class_id, family_id (siblings share it), entry_date, exit_date, updated_at.
status: en_attente (application pending), inscrit (enrolled), reinscrit (re-enrolled), sorti (left the school).

`installments` — instalments (amounts due)

Parameters: school_year_id (default: the current year), student_id, status, due_from, due_to.
Fields: id, student_id, school_year_id, fee_id, label, amount, amount_paid, balance, due_date, status.
status: a_payer (unpaid), partielle (partly paid), payee (paid), annulee (cancelled).

`payments` — payments received

Parameters: student_id, date_from, date_to, include_cancelled (true/false, default false).
Fields: id, student_id, installment_id, amount, payment_date, method, reference, bank, receipt_number, cheque_status, cancelled, cancelled_at, created_at.
method: especes (cash), cheque, virement (bank transfer), carte (card), autre (other). cheque_status: recu (received), remis (deposited), encaisse (cleared), impaye (bounced).

`absences` — absences and late arrivals

Parameters: student_id, class_id, type, status, date_from, date_to.
Fields: id, student_id, school_year_id, date, type (absence, retard = late), minutes_late, status, slot (code, label, start_time, end_time).
status: a_justifier (to be justified), justifiee (justified), injustifiee (unjustified).

5. Personal data

The API follows the data-minimisation principle of Moroccan law 09-08 and of the GDPR. It does not return: addresses, photos, birth places, internal notes, the reason of an absence or its supporting document (often health data), free comments on payments, nor the parents' contact details. The school remains the data controller: it decides which software gets a key, and can revoke it at any time. Each call is logged (date, resource, number of records, IP address) and kept 90 days; the management sees, for each key, when it was last used and how many calls it made.

6. Versioning and contact

This is version 1. Fields may be added to v1; none will be renamed or removed without a new version (/api/v2.php), announced in advance. Need another resource or a write access? Write to contact@scoliom.com.