Integrate your CRM

What you’ll build

This guide covers tenant screening: someone applying to rent. Your CRM keeps two ids per application, yours and Carousel’s; the applicant’s data stays with Carousel.

Set up once, in Carousel

Three settings, all under your initials (top right) → Developers at app.oncarousel.com.

Part 1 · Send a tenant screening

Step 1 · Send it when your user clicks “Screen applicant”

Pick the checks, give the applicant’s email, and put your application’s id in externalId.

curl -X POST https://app.oncarousel.com/api/v1/screenings \
  -H "Authorization: Bearer $CAROUSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: APP-1042-send-1" \
  -d '{
    "checks": ["id", "credit", "court_qc", "penal_qc", "bank"],
    "applicant": { "email": "nora@example.com" },
    "region": "CA",
    "externalId": "APP-1042"
  }'

Carousel emails the applicant their link. This example has no property, so it’s filed in Private: its report has no rent to weigh income against, and only the account’s owner can open its portalUrl. To file it under the rental, add the building once — POST /buildings with its address, units and rent; repeating it is safe — and send its building and unit ids instead of region. Every field you can send, with its options:

The same table, with more on each field: Send and follow screenings.

Step 2 · Save Carousel’s id with your application

Keep the answer’s id next to your application — step 4 uses it.

201 Created
{
  "id": "6f0c2d1e-5b7a-4c8e-9f10-2a3b4c5d6e7f",
  "status": "invited",
  "externalId": "APP-1042"
}

Part 2 · Track it

Step 3 · Update the status when an event arrives

Carousel sends each event to your webhook (B), with your externalId — never the applicant’s data. Check its signature with your signing secret (the whsec_… string, as it is), and answer with any 2xx within 10 seconds. Deliveries can come twice and out of order: the Carousel-Delivery header is the same on every retry, so ignore one you’ve handled, and apply an event only if its seq is higher than the last one you applied for that screening — then a delivery that arrives late never moves a status back, and a screening’s screening.started is never numbered after its end. Events and webhooks shows how.

POST https://crm.your-company.com/webhooks/carousel

{
  "id": "0d6e…",
  "seq": 1042,
  "type": "screening.completed",
  "createdAt": "2026-10-03T18:42:10.512Z",
  "data": { "screening": { "id": "6f0c2d1e-…", "externalId": "APP-1042" } }
}

Find the application by externalId. An event whose externalId is null is a screening someone added in Carousel, such as a co-applicant: match it through the application.* events, whose data.screenings lists every screening on the application. Those come only when someone in Carousel changes the application’s stage, adds a note or moves it; until then, nothing in the API ties that screening to yours. Every screening event Carousel sends, and what to show:

A quick screening can go straight to screening.completed, with no screening.started. Carousel also sends application, building and balance events: Event types.

No webhook yet? Ask whenever you like: GET /api/v1/screenings?externalId=APP-1042.

Part 3 · Show the report

Step 4 · When your user clicks “View report”, ask for a link

From your server, after checking this user may see this application. viewer says who they are, for Carousel’s log. Ask for a new link each time the report is opened.

curl -X POST https://app.oncarousel.com/api/v1/screenings/6f0c2d1e-…/view-links \
  -H "Authorization: Bearer $CAROUSEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "viewer": "jane@your-company.com" }'

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

If it fails: 403 view_links_not_allowed — the key wasn’t made with Show reports in my app (A) or Read applicant results; 404 not_found — the screening isn’t one this key reaches. The rest: Errors and limits.

Step 5 · Show it in an iframe

On a page of a site you allowed (C). Use the link straight away: it works once, within 2 minutes. The report then stays open for 30 minutes, with its PDF.

<iframe src="{url}" title="Screening report"
        style="width:100%; height:100vh; border:0"></iframe>

After 30 minutes the frame says the view has ended and tells your page — show an “Open again” button that repeats step 4. A link that was already used, or is over 2 minutes old, shows the same words without telling your page, so keep the button there anyway. Details: Show reports in your platform.

Two sides must agree. Carousel’s side is your allowed sites (C). Your side: if your page sends a Content-Security-Policy, it must allow Carousel’s frame — frame-src https://app.oncarousel.com. Don’t sandbox the iframe. If the frame sits inside another frame, that outer page’s site must be allowed too. Give the report room: it shows two columns from 900 px wide.

If the report doesn’t show:

Try it in a sample CRM

Click through it all — the setup, send, track, then Carousel’s real report — with every request shown. It opens on a page of its own, full width.

SampleA sample CRM, not your account — nothing in it is real.

Open the sample CRM →

Before you go live

1. A live key (not a test key) with Show reports in my app, on your server only.
2. Your webhook address set in Carousel, and each delivery’s signature checked.
3. Your live site’s address under Allowed sites — localhost shows test reports only.
4. Your server checks which of your customers an application belongs to before every view link and every read.
5. If your site sends a Content-Security-Policy, it allows frame-src https://app.oncarousel.com. Don’t sandbox the iframe.

Every detail, part by part: Send and follow screenings · Events and webhooks · Show reports in your platform.