Show reports in your platform

What your user sees

How it works

One Carousel account is enough for a whole platform: its key sends every screening and makes every link, and your own login decides which of your users sees which application. Carousel doesn’t keep your customers apart — your server does: a key that shows reports can make a link for any report the key reaches, so check which customer an application belongs to before each link — or give each customer a key limited to their own workspace, which reaches no one else’s reports. Integrate your CRM says what else they share.

Set it up once

Ask for a link when your user opens the report

From your server, once you’ve checked that this user may see this application:

curl -X POST https://app.oncarousel.com/api/v1/screenings/<id>/view-links \
  -H "Authorization: Bearer $CAROUSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "viewer": "jane@agency.example" }'

201:

{
  "url": "https://app.oncarousel.com/embed/r/kV9q2xR7mPz4tLwB8nYc3hJd6sFg1aEu5oKiQvXbN0e",
  "expiresAt": "2026-10-06T15:02:00.000Z"
}

viewer is your user, as you name them — an email or your own id, up to 200 characters. Carousel records it with the link and every view; it doesn’t check it. A key can make 120 links a minute, apart from its 120 requests.

Put it in a frame straight away

<iframe src="https://app.oncarousel.com/embed/r/kV9q2xR7…"
        title="Screening report"
        style="width:100%; height:calc(100vh - 64px); border:0"></iframe>

The same thing in a Node server, from your user’s click to the page:

app.get('/applications/:id/report', requireLogin, async (req, res) => {
  const record = await db.applications.find(req.params.id);
  // Your rule: only the user's own applications.
  if (!record || record.agencyId !== req.user.agencyId) return res.sendStatus(404);

  const answer = await fetch(
    `https://app.oncarousel.com/api/v1/screenings/${record.carouselScreeningId}/view-links`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.CAROUSEL_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ viewer: req.user.email }),
    },
  );
  if (!answer.ok) {
    const { error } = await answer.json(); // { code, message, hint }
    return res.status(502).render('report-unavailable', { code: error.code });
  }
  const { url } = await answer.json();
  res.set('Cache-Control', 'no-store'); // the link works once: never serve this page from a cache
  res.render('report', { frameUrl: url }); // <iframe src="{{frameUrl}}">
});

Your page

• Allow the frame in your own CSP. If your page sends a Content-Security-Policy, add frame-src https://app.oncarousel.com.
• Don’t sandbox the iframe. The report runs scripts and downloads its PDF; a sandbox attribute breaks both.
• Load each link once. The first load spends it, so a frame that mounts twice — a re-render that resets src, React’s StrictMode in development — shows “This view has ended”. Ask for a new link instead of reusing one.
• Give it room. The report scrolls inside the frame. It shows two columns from 900 px wide and stacks below that; a height of the window less your header works well.
• Native apps: open an HTTPS page of yours, on your allowed sites, that holds the frame — not the link itself.

One link, two clocks

• The link works once, within 2 minutes: long enough for your page to load the frame, and useless after.
• The view it opens lasts 30 minutes. Switching tabs, opening documents and downloading the PDF all happen inside it.
• When it ends, the frame shows “This view has ended” and tells your page, so you can offer a fresh one:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.oncarousel.com') return;
  if (event.data?.type === 'carousel.view_ended') showReopenButton(); // asks your server for a new link
});

The message comes when an open view’s 30 minutes run out. A link that was already used, or is over 2 minutes old, shows the same words without it — so keep a way to reopen on your page as well.

Build it with a test key

A test key’s link opens Carousel’s sample report — a fictional applicant under a Test mode bar — through exactly the same steps: one use, 2 minutes, 30 minutes, the PDF, the ending. Send a test screening, ask for its link, and frame it from localhost once that address is in your allowed sites. No real applicant’s data is read, nothing is charged or logged, and no screening.viewed is sent.

What’s in the frame

Nothing in the frame leads into Carousel. Before the applicant finishes, the report says what’s still waiting (“Nothing back yet — 3 checks waiting on the applicant”). A Québec court file that hasn’t been opened shows its number only.

Who viewed it

Each time the report loads in the frame — the first load, a reload, the print view, every PDF download — your webhook gets a screening.viewed, saying whose it was, once the applicant has opened their link. One view can send several:

{
  "type": "screening.viewed",
  "data": {
    "screening": { "id": "6f0c…", "externalId": "APP-88231", "portalUrl": "…" },
    "via": "embed",
    "viewer": "jane@agency.example"
  }
}

via is embed for a view through a link, carousel for your team in Carousel. See Events and webhooks.

How it stays safe

When something goes wrong

Asking for a link:

In the frame:

Questions