Overview

The UNSW Advance Institution API is how you feed Advance the two fundamental pieces it needs to assess credit: the curriculum data of programs and subjects/courses, and who is applying.

Your access token identifies you on every request, so there is no institution id to pass. Reads and writes are authorised from the token.

Trying it out

These pages are the reference. To poke at a running instance, each environment serves a live Swagger UI, where you can paste a token and fire real requests:

• Test, which is what an integrator can call today
• Dev, which runs ahead of test and is less stable

Both serve their raw spec at /q/openapi.json on the same host. See Authentication for getting the token you’ll need to paste in.

The two halves

The catalogue comes first. An application names a program code and year, so that program has to exist before anyone can apply to it.

Everything is identified by code and year

A program, subject or specialisation is identified by its code plus the year it applies to. 3584 in 2026 is a different record from 3584 in 2027. Curricula change between years, and an application is always assessed against the rules of its own intake year, so both parts matter.

Neither can be changed after creation. To correct a code, delete the record and create it again.

Your IDs, not ours

Two separate mechanisms let you work with your own identifiers instead of storing ours.

externalIds on catalogue records maps a record to its ID in each of your systems:

{ "externalIds": { "sis": "PRG-3584", "crm": "C-000123" } }

Send it on create or update and it merges per system, so omitting a system leaves that system’s ID alone. This helps when your own systems disagree about what a program is called.

sources on applicants and applications records where a record came from and what you call it, such as your student number or your application number. An applicant or an application can carry one entry per system of record:

{
  "sources": [
    { "sourceName": "SITS", "sourceRef": "z1234567" },
    { "sourceName": "TRIM", "sourceRef": "T-99814" }
  ]
}

You can then look records up by any of your own IDs, without having stored ours:

GET /institution/applicants?sourceRef=z1234567
GET /institution/applications?sourceRef=APP-2026-00123

A sourceRef must be unique within a sourceName, and sourceName is required whenever you send a sourceRef, since an ID with no system to interpret it isn’t findable.

The first entry is the primary: it is what list views, search results and the change feed show, and what the sourceName / sourceRef pair on every response reports. Order is yours to set — send the entries in the order you want them.

It’s worth supplying these on applicants. When you submit an application, an applicant carrying any of the references you send is matched on that first, ahead of name and date of birth. That way a returning applicant is still recognised after a name change or a corrected typo. If the applicant is matched on name and date of birth instead, the references you sent are added to the record rather than discarded.

Replace or amend: PUT and PATCH

Catalogue records offer both. Reach for PATCH when you’re changing one thing, particularly on subjects, where a PUT that forgets description or learningOutcomes will wipe them.

Applicants and applications offer PATCH only, deliberately — see Correcting records for why, and for the rules on what can still be changed once an application has been assessed.

An unrecognised field name in a PATCH body is rejected rather than ignored, so a typo can’t silently do nothing.

externalIds is the one exception in both: it always merges per system, and sending it as null is refused rather than wiping every id you’ve registered.

Curriculum structures

A program’s curriculum is a tree of containers, such as “Core Courses” or “Prescribed Electives”, each holding subject entries and, optionally, child containers.

Containers are built as DRAFT, which lets you assemble and review a tree before anything uses it. Attaching it to a program or specialisation, or nesting it under another container, is only allowed while it is a draft. Publishing sets it LIVE.

Assessment is asynchronous

Submitting an application stores it and returns immediately with status RECEIVED. Assessment happens afterwards.

GET /institution/applications/{id} reports where intake got to:

The credit itself is a separate endpoint:

GET /institution/applications/{id}/outcome

PROCESSING means an assessment has started, not that it has finished. A credit officer may still be reviewing it, so poll the outcome until its finalOutcome is true. See Credit outcomes for how to read it, and for the difference between “not assessed yet” and “assessed, and awarded nothing”.

READY and WITHDRAWN are yours to set, by posting to /institution/applications/{id}/ready and /institution/applications/{id}/withdraw. Both arrived on 18 September, along with the rename of PROCESSED to PROCESSING. See that release if you are migrating.

Getting a token

Authentication is OAuth 2.0 client credentials against Keycloak. Request a token with your client id and secret, then send it as a bearer token on every call. See Get access token for the exact request.

Tokens are short-lived. Request a new one when it expires rather than caching it indefinitely.

A typical integration

1. Load your catalogue: programs, subjects and specialisations for the intake year
2. Build curriculum structures for each program, and publish them
3. Submit applications as they arrive, with the applicant’s qualifications attached
4. Attach supporting documents (transcripts, syllabi) to the application
5. Poll the outcome until finalOutcome is true
6. Correct anything your own systems change afterwards

Steps 1 and 2 are usually a one-off load followed by incremental amendments; steps 3 to 6 are your day-to-day traffic.