Carousel docs
Tenant screening

Screening products

Tenant screeningThese docsCredit, criminal, eviction, income and ID for rental applicants.
Commercial screeningComing soonCredit, court records, ID and bank-verified income for commercial tenants and their guarantors.
Employment screeningComing soonID, police checks and Québec penal searches for candidates, and credit where the role calls for it.
Regular screeningComing soonBackground and identity checks for staff, members or contractors.
Developer guides · Carousel API

Events and webhooks

Everything that happens to your account’s screenings, as one stream you can read when you like — or have pushed to your webhook.

An event

{
  "id": "0d6e…",
  "seq": 1042,
  "type": "screening.completed",
  "createdAt": "2026-10-03T18:42:10.512Z",
  "data": {
    "screening": {
      "id": "6f0c…",
      "externalId": "lead-1042",
      "portalUrl": "https://app.oncarousel.com/report/6f0c…"
    }
  },
  "livemode": true
}

seq only increases: it’s your place in the stream. Its numbering is shared, so expect gaps. Per screening, apply an event only if its seq is higher than the last one you applied; a screening’s screening.started is never numbered after its end. Events carry ids, your externalId and the link — never applicant data. They cover screenings sent from Carousel’s own screens too, where externalId is null. Your account’s stream starts when it creates its first key or webhook, and a new event appears within about a minute. livemode is false for a test key’s events and the webhook test.

Whose events they are

  • Your account’s stream has the events of every screening filed in your account, whoever sent it, and your account’s building, unit and balance events.
  • Copies of your sends. When one of your account’s keys sends a screening into a workspace another account shared with you, that screening’s events, and its application’s, are copied into your stream too — naming only your own externalIds — for as long as you can still open it. When the share ends, the copies stop. A building your key adds there is theirs, and so is its building.created.
  • GET /events reads your account’s stream through the key’s reach. It keeps the events of the screenings the key reaches, so a key that reaches this account’s workspaces only never reads the copies, and a key limited to some workspaces reads only their screenings’, buildings’ and units’ events. Balance events come to every key.
  • The webhook is the account’s. It gets the whole stream, copies included, whichever key sent the screening.
  • Not yet: a screening that someone else sends in a workspace shared with you shows in GET /screenings, but sends you no events.

Event types

GET /events/types returns each type with a one-line description.

Screenings

  • screening.sent — The screening was created and its applicant link issued.
  • screening.invitation_delivered — Carousel’s mail service accepted the invitation email. It isn’t proof it arrived: a bounce after this isn’t reported.
  • screening.invitation_failed — Carousel’s mail service didn’t accept the invitation email when it was sent — hand the applicant the link yourself. Carousel tries again for 24 hours, so screening.invitation_delivered can still follow.
  • screening.reminded — A reminder was sent to the applicant.
  • screening.started — The applicant opened the application and started. A quick screening can go straight to screening.completed without it.
  • screening.step_completed — One check reached its end: done or stopped. GET /screenings/{id} says which.
  • screening.completed — Every check is done — the report is ready.
  • screening.viewed — The report was opened: by your team in Carousel (data.via is carousel), or in your platform through a view link (embed, with data.viewer). Each load counts: a reload, the print view and every PDF download send one too.
  • screening.cancelled — The screening was cancelled; nothing more is charged.
  • screening.expired — The applicant never started within 30 days; the invitation expired.

data.screening is the screening’s id, externalId and portalUrl; step_completed adds data.check, the check’s id.

Applications

  • application.stage_changed — The application moved to another stage.
  • application.note_added — Your team added a note (its text is not sent).
  • application.moved — The application was filed under another workspace or building.

data.application is the application’s id and portalUrl; data.screenings lists its screenings with their id and externalId; stage_changed adds data.stage with its id and name.

Buildings and balance

  • building.created — A building was added.
  • unit.created — A unit was added to a building.
  • balance.low — Your token balance is below what one Verified+ screening costs. It comes again every 72 hours while it stays low, and after a top-up that runs low again.
  • balance.exhausted — Your token balance ran out; token-paid sends are refused until a top-up.

data.building has its id, address and workspace; data.unit its id, label and building; balance events give the region.

Read them

curl "https://app.oncarousel.com/api/v1/events?after=0&limit=50" \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

Oldest first: { "data": [ … ], "cursor": 1042, "hasMore": false }. Save cursor and pass it as after next time; while hasMore is true, ask again straight away. types narrows it, comma-separated: types=screening.completed,screening.viewed. limit is 50 by default, and at most 200.

Events are kept. A webhook delivery you missed can always be read again here.

A webhook

In Carousel: account menu → Developers → Webhook. Enter one HTTPS address — an account has one — keep Every event or pick some, and save. Your signing secret (whsec_…) is shown once — copy it.

POST <your URL>
Content-Type: application/json
User-Agent: Carousel-Webhooks/1
Carousel-Event: screening.completed
Carousel-Delivery: <delivery id>
Carousel-Signature: t=1791060000,v1=<hex>

{ the event, as above }
  • Answer with any 2xx within 10 seconds. Otherwise we try again after at least 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then stop. The event stays in GET /events.
  • Delivery is at least once, and not in order. Ignore a Carousel-Delivery you’ve already handled, and order by seq.
  • Up to 300 deliveries a minute per address, a few at a time; after a failed delivery the rest wait a minute. On a busy account, read GET /events as your main feed and treat each delivery as the prompt to read it.
  • Events are sent if they were recorded after you saved the address.
  • Saving the address again creates a new signing secret, shown once, and stops pending deliveries to the old setup.
  • The address must be public HTTPS, up to 500 characters: no IP addresses, no internal hosts. We don’t follow redirects.
  • The Webhook tab lists the last ten deliveries and what your server answered.

Test your receiver without waiting for a real screening: POST /webhook/test, with any key, sends one signed sample event to your webhook now and answers with what your server said — its status code, or the error. The sample says "livemode": false and names no real screening. Send { "type": "…" } to choose its type (screening.completed if you leave it out); nothing else is taken. Up to 10 a minute per account; with no webhook set, it’s 404 not_found. A test key’s own events aren’t pushed to the webhook; read them with GET /events and that key.

Check the signature

The Carousel-Signature header is t=<unix seconds>,v1=<hex>. v1 is the hex HMAC-SHA256 of <t>.<raw body> — t, a dot, and the raw body — keyed with your signing secret. Recompute it before trusting a delivery. t and the signature are new on each attempt, and you may refuse an old t.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before any JSON parsing
function isFromCarousel(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
import hashlib, hmac

def is_from_carousel(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

The infrastructureof yes.