iblai-api-apply

iblai-api-apply

Operate an organization's application gate: when applications are on, a user cannot join the org directly — they fill out a form the org configured, submit it, and staff review and decide it. Approval grants membership. Covers the applicant surface (create/renew a draft, save answers, upload files, pay or waive the fee, submit, withdraw), the reviewer surface (pipeline, per-student decisions, notes, waivers, fee management, blocks, placement tests, course assignments, account provisioning), and form management (schema, config, decision templates, renewal windows).

Applications support the family shape: one adult applies on behalf of one or more students. Each student in the application gets an individual record (a candidate) with its own review status and decision — one child can be accepted while a sibling is waitlisted. A form with no student section is a plain self-apply form; the applicant is the candidate. A user's application record is called a submission in the API payloads; the two words refer to the same thing.

Three kinds of caller hit these endpoints:

• Applicant — a signed-in user. Creates and submits an application (for themselves or their students), watches its status, pays or has waived the application fee, and can renew next year.
• Reviewer / admin — an org admin. Works the pipeline, decides per student or per family, keeps internal notes, manages the fee, waives requirements, assigns placement tests and courses after acceptance.
• Form manager — an org admin. Authors the form(s), the decision message templates, the fee, and the renewal window.

Auth & conventions

• Base URL: https://api.iblai.app/dm — these are Data Manager (DM) endpoints, so the /dm prefix is required; the /api/catalog/applications/... paths below are appended to it (e.g. https://api.iblai.app/dm/api/catalog/applications/platform/status). (The same contract is also exposed edX-proxied under /api/ibl/catalog/applications/...; through this gateway use the direct /dm form.) Trailing slashes are accepted but optional on every route.
• Header: Authorization: Api-Token $IBLAI_API_KEY on every request.
• Org scope: every request is scoped to one org. Pass platform_key (= $IBLAI_ORG) as a query param on GETs and in the body on writes; platform_org (the org code) is accepted as an alternative. Reviewer endpoints that address a specific application by id resolve the org from the application itself, but list/stats/detail reads still take platform_key for the permission check.
• Authentication semantics: all endpoints require authentication; anonymous requests get 401. Reviewer and form-manager endpoints (manage paths) additionally enforce admin/role permissions and return 403 when the caller lacks them. Applicant endpoints operate only on the caller's own applications — someone else's application id is a 404, not a 403 (no existence leak).
• Pagination: only the reviewer pipeline list is paginated, with the standard envelope { "count", "next", "previous", "results": [...] } and page / page_size params. Every other list returns a plain { "results": [...] } with no paging.
• Errors: business errors return a stable machine code: { "error": "<machine_code>" } — key off error. Validation failures on submit are richer (see Answers and validation errors below). Throttled writes return 429.
• Timestamps are ISO 8601. Money is a decimal string ("50.00") plus a currency code.
• <id> in paths is a submission id unless stated otherwise.
• DELETE / destructive / outward-facing calls say "Confirm with the user first."
• Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG, IBLAI_USERNAME, and IBLAI_API_KEY.