API — connect systems to your school's MIS data

API — connect systems to your school's MIS data

The API area (sidebar → Data → API) exposes your school's MIS data through a read-only API that speaks the same language as Wonde, so systems already built for Wonde can connect to it by changing just the address and the token. This is sometimes called the SOS API internally, because it's backed by SOS-sourced MIS data.

This is a different, separate feature from Advanced features (also under the Data group in some schools' sidebars), which is a smaller Realsmart-native API. If you're looking for that instead, see Advanced features — the Realsmart API. The two use different tokens, different base URLs and are not interchangeable.

Why you might not see "API" in your sidebar {#step-1}

API only appears once your school is registered for the SOS API. If your school's MIS integration hasn't been set up for it, the nav item simply doesn't show — this isn't a permissions problem you can fix yourself. If you believe your school should have it and it's missing, contact Realsmart support.

Base URL & authentication {#step-2}

Every request is scoped to your school and versioned. Your school's base URL follows this pattern:

https://<your-adadmin-domain>/v1.0/schools/{school_id}/{resource}

{school_id} is a Wonde-style id (e.g. A0000003929) — your exact id and ready-to-copy URLs are shown on the Tokens and Documentation tabs once you're on the page.

Two equivalent ways to authenticate, matching Wonde exactly:

• Bearer token (most common):

  curl -H "Authorization: Bearer YOUR_TOKEN" "https://<your-adadmin-domain>/v1.0/schools/{school_id}/students"
  

• HTTP Basic — the token as the username, empty password (what the official Wonde PHP client sends):

  curl -u "YOUR_TOKEN:" "https://<your-adadmin-domain>/v1.0/schools/{school_id}/students"
  

Use a placeholder like YOUR_TOKEN in anything you share — never paste a real token into docs, tickets, or source control.

Example request & response {#step-3}

A request for students, with a couple of results:

curl -H "Authorization: Bearer YOUR_TOKEN" "https://<your-adadmin-domain>/v1.0/schools/A0000003929/students?per_page=2"

{
  "data": [
    { "id": "10231", "mis_id": "A0421", "forename": "Ada", "surname": "Lovelace",
      "gender": "F", "date_of_birth": { "date": "2012-03-14 00:00:00.000000", "timezone_type": 3, "timezone": "UTC" },
      "upi": "A042112030001" },
    { "id": "10232", "mis_id": "A0422", "forename": "Alan", "surname": "Turing",
      "gender": "M", "date_of_birth": { "date": "2011-11-02 00:00:00.000000", "timezone_type": 3, "timezone": "UTC" },
      "upi": "A042211110002" }
  ],
  "meta": {
    "includes": ["contacts", "classes", "groups"],
    "pagination": {
      "next": "https://<your-adadmin-domain>/v1.0/schools/A0000003929/students?per_page=2&page=2",
      "previous": null,
      "more": true,
      "per_page": "2",
      "current_page": 1
    }
  }
}

(Example data is representative — not real pupils.) Dates are serialised the same way Wonde emits them (the date/timezone_type/timezone object above), and meta.pagination is omitted entirely when a result fits on one page. Add ?include=contacts,classes to pull related objects inline — the includes actually available for each resource are always listed in meta.includes and on the Documentation tab, so read them rather than hard-coding.

Documentation tab {#step-4}

The Documentation tab explains authentication, the response format, pagination, includes and delta filtering (updated_after/updated_before) and errors — generated from the implemented endpoints, so it always matches reality and always shows your school's real base URL. Use Download docs (.md) to take the whole reference (or a single page) as Markdown for other tools.

Endpoints tab {#step-5}

The Endpoints tab lists every resource the API serves — students, employees (staff), contacts (parents/guardians), classes, groups, subjects, attendance summaries, session attendance, employee absences, exclusions, behaviours, achievements, events, deletions and the rest — each with its scope, query parameters, available includes and a ready-to-run curl example using your school's real URL. Resources the MIS doesn't hold for SOS schools (like lessons, periods, rooms and photos) are marked empty for SOS and return valid, correctly-shaped empty responses rather than errors — so a consumer built for the full Wonde API doesn't break.

Tokens tab {#step-6}

The Tokens tab issues access. Each token:

• reads only the schools it was granted — this school here, or a ticked set of schools when created from the trust's MAT area (consumers see exactly that set from GET /schools);
• reads only the scopes you tick (least privilege);
• is shown once at creation — copy it then; only a hashed copy is stored;
• can be revoked (takes effect immediately, on the very next request) or rotated (revoke + reissue with the same name and scopes);
• can be given an expiry when your environment supports it.

Every API call is logged (token, resource, status, IP — never the data), and the tab shows the last 24 hours of activity.

Sensitive student data has its own scopes {#step-7}

Three student includes carry safeguarding and special-category data — extended details (ethnicity, religion, free school meals, pupil premium, in-care and child-protection indicators), SEN needs, and medical details. Each sits behind its own scope, ticked separately when you create a token:

A token without the scope simply never sees that data — requests still succeed; the include is silently absent and not advertised in meta.includes. Every time this data is served, an entry is written to the school's audit trail recording which token accessed it, when, and for how many students — so grant these scopes only to systems that genuinely need them.

Treat tokens like passwords {#step-8}

Anyone holding a token can read the scoped data. If a token may have leaked, revoke it — anything using it stops working instantly, on its very next request.