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

Concepts

What Carousel does, who’s involved, and the words the API uses. Read this before the quickstart.

What Carousel is

Carousel screens rental applicants for landlords and property managers. You send a screening — a set of checks — to an applicant’s email, and they complete it on Carousel’s own hosted flow, which includes ID and selfie, credit, court, police and bank checks, and a short self-declaration of their income, household and history. Each provider’s result is collected into a report your team reads at portalUrl.

No pass or fail

Carousel never approves or rejects an applicant. Each check reports what its provider returned. The decision is yours.

Who’s who

  • You — a landlord or property manager with a Carousel account. Your system calls the API with a key made in that account.
  • Your team — the people who read reports in Carousel, at portalUrl. They sign in with Google.
  • The applicant — the person being screened. The API knows them by email only, and they complete their checks from applicantLink. Their name comes from their ID once they’ve completed it.
  • Carousel — emails the invitation, runs the hosted flow, takes the applicant’s payment when they pay, and collects each result into the report.
  • Providers — the sources behind the checks, such as TransUnion or Equifax for credit. They’re listed under Where it works, below.

How a screening flows

  1. Your system sends POST /screenings: the checks, the applicant’s email, and where to file it.
  2. Carousel emails the applicant their applicantLink. With "delivery": "none", it hands you the link to pass on instead.
  3. The applicant completes the checks on Carousel’s hosted flow — and pays at checkout, when the payer is renter.
  4. Each provider returns its result, and Carousel adds it to the report.
  5. Each change is recorded as an event. Read them from GET /events, or have them pushed to your webhook.
  6. Your team opens portalUrl to read the report — or your system reads /results, with a key allowed to.

The nouns

Account and key

  • Account. Sign up at app.oncarousel.com with Google — Google sign-in is the only way in. Each person signs in as themselves. To manage your company account’s keys, webhook and allowed sites, ask its owner to add you as a developer in Developers → Access. To read its reports, ask them to share the workspace with you — see Share with your team. Your keys that reach every workspace you can use then reach it too, at your role there.
  • Developers. The account’s owner can add up to 25 developers in Developers → Access. Nothing is emailed: each opens Developers, chooses Accept, then picks the account under Account at the top — Developers opens on their own account each time. They manage its keys, webhook and allowed sites from their own sign-in, and a developer’s keys act for the account, as the owner’s do — this account’s workspaces only: they never reach a workspace shared with the owner. A live key that reads results or shows reports needs the owner to switch on Can see applicant data for that developer; test keys don’t. Switching it off later doesn’t stop keys they already made: revoke those under Keys. Without it, a developer can still make test keys, and live keys that send screenings — spending your tokens — and see every applicant’s email; revoke any key, yours included; change or turn off the webhook; and change allowed sites. When you remove a developer, choose Remove and revoke their keys, or their keys keep working. If they saw the webhook’s signing secret, save the webhook again to get a new one.
  • Key. Made in Carousel: account menu → Developers → Keys. Live keys look like cp_live_…, test keys cp_test_…. An account has at most 10 of each in use, counting its developers’ keys and any connected assistant’s (named “… (connected app)”), each with a name of up to 60 characters.
  • What a key reaches. A key acts with the access of its account’s owner: every workspace they can use — this account’s workspaces, buildings and Private, and the workspaces other accounts shared with them, at their role there. View only reads; Can screen and Can spend … tokens (Carousel names the sharing owner: “Can spend Priya’s tokens”) send. Wherever it reaches, it sees every screening filed there, whoever sent it, including screenings sent from Carousel’s own screens. That’s the default, Every workspace you can use. When you make a key, you can limit it instead to the workspaces you tick and the workspaces inside them — never Private. Which workspaces a key reaches is fixed when it’s made: make a new key to change it. GET /me says the key’s reach, and GET /workspaces lists each workspace it reaches with its account, your role and canSend. A key made before this choice existed reaches this account’s workspaces only, and a developer’s keys never reach past the account. If your platform serves several customers from one account, a key limited to a customer’s workspace reaches only that customer’s screenings — but the account’s one webhook gets them all.
  • Results. Only a key made with Read applicant results ticked reads results and documents through the API — for every screening the key reaches, shared workspaces included. Every key sees each screening’s applicantEmail.
  • Show reports in my app. A key made with it can make view links that show any report the key reaches, documents and PDF included, inside your app — see Show reports in your platform. It can’t call /results. Guard it like a results key.

Workspace, building, unit and Private

  • Workspace. Where your team works in Carousel. Each workspace has one region.
  • Building. An address in a workspace. Carousel reads its province from the address. Its monthly rent, if you give one, is what the report weighs the applicant’s income against.
  • Unit. A rental in a building, with a label like “4B”. You send a unit by its id, from GET /buildings.
  • Private. Screenings with no workspace or building. Carousel lists them under “Private” in Applications, for the account’s owner only.

A screening is filed under a building (and, if you like, one of its units), in a workspace with no building, or in Private. See Workspaces and buildings.

Application, screening and report

  • Screening. One person’s checks: what POST /screenings sends.
  • Application. Carousel’s file for one rental lead. Each send creates one. Co-applicants and guarantors added in Carousel join the same application, each with their own screening; the API can’t add them yet. application.* events list the application’s screenings.
  • Report. What each provider returned for a screening, at portalUrl.

Check, combination and custom workflow

  • Check. One verification, sent by its id: id, credit, court_roc and so on. The check id id means identity verification; it’s unrelated to the id field objects carry.
  • Combination. A set of checks that go together. A screening runs exactly one combination, and no other mix can be sent. GET /checks lists them.
  • Custom workflow. A set of checks Carousel sets up for an account — contact Carousel for one. Listed under workflows in GET /checks, and sent with "workflow": "<id>". Its payer is fixed.

Payer

  • tokens — you pay, from your token balance.
  • renter — the applicant pays Carousel at checkout, and you’re charged no tokens.

Leave payer out and it’s tokens for checks, or the workflow’s own payer for a custom workflow.

Region and court area

  • Region. CA (Canada, in CAD) or US (the United States, in USD). Each region has its own token balance, checks and prices.
  • Court area, in Canada only. QC is Québec: court_qc and penal_qc. They’re separate searches, so a combination can run either or both. ROC is the rest of Canada: court_roc.
  • A building whose address is in Québec runs Québec’s checks, and court_roc for it is refused with 422 court_area_mismatch. For a building elsewhere, or with no building, either set is accepted: you choose.

Money

  • Tokens. 12 tokens = $1: Canadian dollars in Canada, US dollars in the US. Each region has its own balance. Buy tokens in Carousel — see Tokens and billing.
  • What a screening costs. A combination’s tokens is the sum of its checks’ prices. Prices can change, and GET /checks always has the live ones.
  • When you’re charged. Per check, as the provider finishes each one, whatever it found — even when the check reads stopped. A check the provider never finishes is never charged. tokenCost, on every screening, is the most it can cost.
  • Not enough tokens. A send your balance can’t cover is refused with 402 insufficient_tokens, and nothing is sent.
  • When the applicant pays. With "payer": "renter", the applicant pays the combination’s applicantPrice at checkout — CA$21.99 for id and credit, CA$27.99 for id, credit and court_roc, at shipped prices — and you’re charged no tokens.

Shipped prices in Canada:

Check idWhat it isTokens
idIdentity verification72
creditCredit check192
court_rocCourt & eviction, rest of Canada72
court_qcCourt & eviction, Québec120
penal_qcPenal search, Québec180
criminalPolice check240
bankBank verification96

So ["id", "credit", "court_roc"] costs at most 72 + 192 + 72 = 336 tokens.

Lifecycle and timing

  • invited — sent; the applicant hasn’t started.
  • in_progress — the applicant has started.
  • completed — every check is done, and the report is at portalUrl.
  • expired — nobody started it within 30 days of the invitation. Only unstarted screenings expire.
  • cancelled — cancelled in Carousel.

Cancel and remind are done in Carousel, from the application’s row; the API has neither. A cancelled or expired screening’s link still works for the applicant, but checks finished afterwards are neither shown nor charged. More in Send and follow screenings.

LinkWho it’s for
portalUrlYour team. It opens for the account’s owner, and for people the screening’s workspace or building is shared with — share it in Carousel first. Developers added in Developers → Access don’t get it, and a screening in Private opens for the owner only.
applicantLinkThe applicant only: where they complete their checks.
Never cross them

Never send portalUrl to an applicant, or applicantLink to your team.

Testing

Build against a test key (cp_test_… — Developers → Keys → Test key). Same address, same requests, same answers, but nobody is emailed, no tokens are spent and no real check runs. With a live key every send is real — and so is every request from the API reference’s console.

  • A simulated applicant. Each test screening is invited, started 30 seconds later, gets one check done every 15 seconds, then completes. POST /screenings/{id}/advance does the rest at once.
  • Choose what happens with the applicant email’s +tag: tenant+record@example.com finds a court record, +stopped stops the first check, +expire never starts (expires after two minutes), +bounce has the mail service refuse the invitation. No tag: everything clear.
  • Results are Carousel’s fictional sample applicant, cut to the checks you sent. portalUrl opens the sample report.
  • Events go to the test stream: GET /events with the test key. POST /webhook/test sends one signed sample event to your webhook now and tells you what it answered.
  • Kept apart. Your key (GET /me), every screening and every event say "livemode": false for test. Test screenings never appear in your team’s lists or billing. Workspaces and buildings are your real ones: one you add with a test key is real, shows in Carousel, but its building.created and unit.created events stay out of your live stream and webhook.

To try a live send on yourself, the cheapest is ["id", "credit"] with "payer": "renter" (CA$21.99 at checkout, at shipped prices) or "payer": "tokens" (264 tokens, about $22, charged as each check completes). The credit check is a hard inquiry on your own credit file, and there’s no cancel endpoint — cancel in Carousel, from the application’s row.

Where it works

 CanadaUnited States
RegionCA, in Canadian dollarsUS, in US dollars
Checksid, credit, court_roc, court_qc, penal_qc, criminal, bankid, credit, records, bank
CombinationsThirteen todayFour today
ProvidersIdentity: Gov ID + selfie, Onfido. Credit: TransUnion or Equifax. Court, rest of Canada: OpenRoom. Court, Québec: SOQUIJ’s TAL decisions, and its penal court files for the penal search. Police: FastKey. Bank: Plaid or Flinks.Identity: Gov ID + selfie, Onfido — the same biometric scan as in Canada. Credit: TransUnion and/or Equifax. Court, eviction and criminal records: Checkr. Bank: Plaid.
Court checksBy court area: Québec’s two searches (either or both), or the rest of Canada’s check. A building in Québec runs Québec’s.records covers court, eviction and criminal records, by Checkr. There’s no court area.

GET /checks?region=US names each US check’s provider.

Carousel and Carousel Classic

Carousel Classic is the original platform: workflows built in its dashboard, and its API at api.oncarousel.com. New integrations use the Carousel API at https://app.oncarousel.com/api/v1, which these pages describe. A Carousel Classic key works with the Classic API only; Classic has its own developer docs.

Applicant data

Applicant data is regulated personal information. Use it only to assess the rental application, store it only as long as you need it, and follow your privacy obligations. See Carousel’s Privacy Policy and Terms. The Tenant Screening Acceptable Use Policy applies to your own systems and connected assistants too.

The infrastructureof yes.