Skip to content

Marketing Consent

Learners taking FSA content through your LMS are asked once whether UL Research Institutes (ULRI) may send them news and updates. You own the prompt UI; the API owns the wording and the record.

The flow

  1. Read the consent state before launching content. GET /users/{uuid} returns two fields:

    Field Type Meaning
    marketingConsent string unset (never asked), granted, or declined
    marketingConsentAt ISO 8601 timestamp, or null When the decision was recorded; null while unset

    Show your prompt only when marketingConsent is unset: ask once, never again after any answer.

  2. Fetch the prompt wording and version:

    GET /consents/ulri-marketing

    {
  "consentType": "ulri-marketing",
  "version": "2026-08-07.v2",
  "text": "…the sentence to display, verbatim…",
  "presentation": "Render as a checkbox that is unchecked by default, so the learner makes an explicit choice. Submit the learner's answer either way: leaving it unticked records a decline, which is a different fact from never having been asked."
}

    Render text verbatim — do not paraphrase, translate or reformat it. Fetching it rather than hardcoding the sentence is what allows ULRI legal to change the wording without every partner shipping a release. Keep version: you echo it back on submit, and it records exactly which wording each learner saw.

  3. Render the prompt — a modal, an inline panel, whatever fits your product — with a checkbox that is unchecked by default, per the presentation value. The learner must make an explicit choice: an unticked box is recorded as a decline, which is a different fact from never having been asked. A single Submit button records whichever state they chose. Consent requirements vary by jurisdiction, and compliance for your own learners remains your responsibility.

  4. Submit the answer:

    PUT /users/{uuid}/consents/ulri-marketing

    {
  "granted": false,
  "promptVersion": "2026-08-07.v2"
}

    Both fields are required. promptVersion must be a version this API has issued: send back the one you rendered. An older version is still accepted, so a learner who answered just before the wording changed is recorded against the wording they actually saw. A version the API never issued returns 400, with a message pointing you to GET /consents/ulri-marketing.

    Call this whichever way they answered — omitting the call for a decline leaves the learner as "never asked", and every partner will keep prompting them. Requires the partner-api/write scope. The partner identity and timestamp are stamped server side and cannot be supplied.

    The response tells you the decision that now governs:

    {
  "consentType": "ulri-marketing",
  "state": "declined",
  "recordedAt": "2026-09-17T14:02:11+00:00",
  "promptVersion": "2026-08-07.v2"
}

    state may not match what you just submitted

    The learner may have a more recent decision recorded on the Fire Safety Academy itself. The latest decision wins, whichever side it was made on. Treat the returned state as authoritative rather than assuming your submission won.

    Status Cause
    400 Missing or invalid granted, or a missing or unissued promptVersion
    401 Missing or invalid JWT
    403 Your client lacks the partner-api/write scope
    404 No such learner, or the learner belongs to another partner

Rules that matter

  • Ask at first content launch, not at registration — registration is often a bulk or SSO operation with no learner present. The canonical moment is the first time the learner opens a lesson.

  • The value can change without you. Consent is collected in two places, and the most recent decision wins:

    • Through you: the unchecked checkbox above. The learner may change their answer through you later; re-submission is allowed, and earlier answers are kept as the record of what they said before.
    • On the Fire Safety Academy itself: agreeing to ULRI communications is part of creating an FSA account, or linking one to the learner's record from your LMS. There is no checkbox there; submitting the form records a grant. Learners can change their preference afterwards in their FSA profile.

    So a learner you recorded as declined can later read granted, for example after they create or link an FSA account, and a granted can later read declined. Read the current state with GET /users/{uuid} rather than caching it.

  • Erasure includes consent. DELETE /users/{uuid} erases the consent record along with the learner.

Reference implementation

The reference partner LMS demonstrates the canonical flow: a modal at first lesson open, unchecked checkbox, single Submit, recorded with the prompt version.