Integration Workflows

You own the end-user experience entirely — FSRI publishes no UX requirements, design patterns, or visual styling rules. The flow below is the canonical consumption pattern the API was designed around; deviate where your product needs to, but each step maps to intended endpoint semantics.

The Canonical Flow

Step	Your LMS does	API call
1	Learner first touches FSA content → register them, store the UUID	POST /users/register
2	Build/refresh your catalog (scheduled delta syncs)	GET /courses + updatedAt[after]
3	Render course + modules; show passingScore for assessed modules	GET /courses/{id}
4	Click-to-play → embed the signed URL per content_type	GET /modules/{id}/content
5	Long video: refresh the URL before it expires	GET /modules/{id}/refresh-url
6	"Mark as Complete" control (video/doc/resource — not SCORM)	POST /modules/{id}/complete
7	Show progress in your dashboards	GET /course-progresses
8	Transcript shows completed → offer the certificate	GET /transcripts/{id}/certificate/pdf

Step by step

1. Register the learner on their first contact with FSA content; persist the returned uuid alongside your own user record. Registration is idempotent, so re-registering after a lost response is safe.
2. Sync the catalog — GET /courses (and /categories, /modules) to build your catalog UI. After the first full pull, use updatedAt[after] delta syncs on a schedule (daily is plenty for most partners) rather than re-fetching everything. Never call catalog endpoints in your page-render path — cache on your side.
3. Render the course — show its modules; for assessable modules surface passingScore so the threshold is visible before starting.
4. Launch content — on click, GET /modules/{id}/content, then embed content_url in an iframe/player suited to content_type. FSRI records the access and the progress record becomes in_progress automatically.
5. Keep long content alive — watch expires_at and call refresh-url shortly before expiry so playback never breaks.
6. Handle completion — see Completion Triggers below.
7. Reflect progress — poll GET /course-progresses (delta-filtered) to update status and percent-complete displays. Poll proportionately: progress freshness only matters when a human is looking.
8. Deliver credentials — when a transcript shows status: completed, expose the certificate and full transcript PDFs to the learner.

Completion Triggers by Content Type

Content type	How completion reaches FSRI
video / document / resource	You call POST /modules/{id}/complete when the learner marks it complete
scorm	The SCORM package reports its own progress/completion — no partner action (calling /complete returns 409)
Quizzes (inside SCORM)	Emitted by the content with pass/fail and score

Who writes progress? Nobody on your side.

Progress records are never written by partners — they're created automatically on first content access and updated by FSRI. This keeps a single source of truth. You just read.

Offboarding

When a learner leaves your platform:

• PATCH /users/{uuid} with {"status": "inactive"} — reversible; right for departures that might return. Their data stays intact.
• DELETE /users/{uuid} — permanent GDPR erasure; for right-to-be-forgotten requests. Identity removed; transcripts/certificates/progress retained but anonymized so issued credentials stay verifiable.

Your product's privacy policy decides which; the API supports both.

Sandbox Behavior Worth Designing For

• Monthly content refresh: sandbox content re-syncs from production monthly — content IDs can shift and test artifacts may be cleaned up. Bootstrap test state at runtime (register fresh users, discover IDs from list endpoints); never hardcode IDs.
• Only published content is visible — in both sandbox and production.