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.
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
- Your system sends
POST /screenings: the checks, the applicant’s email, and where to file it. - Carousel emails the applicant their
applicantLink. With"delivery": "none", it hands you the link to pass on instead. - The applicant completes the checks on Carousel’s hosted flow — and pays at checkout, when the payer is
renter. - Each provider returns its result, and Carousel adds it to the report.
- Each change is recorded as an event. Read them from
GET /events, or have them pushed to your webhook. - Your team opens
portalUrlto 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 keyscp_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 /mesays the key’sreach, andGET /workspaceslists each workspace it reaches with itsaccount, yourroleandcanSend. 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, fromGET /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 /screeningssends. - 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_rocand so on. The check ididmeans identity verification; it’s unrelated to theidfield objects carry. - Combination. A set of checks that go together. A screening runs exactly one combination, and no other mix can be sent.
GET /checkslists them. - Custom workflow. A set of checks Carousel sets up for an account — contact Carousel for one. Listed under
workflowsinGET /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) orUS(the United States, in USD). Each region has its own token balance, checks and prices. - Court area, in Canada only.
QCis Québec:court_qcandpenal_qc. They’re separate searches, so a combination can run either or both.ROCis the rest of Canada:court_roc. - A building whose address is in Québec runs Québec’s checks, and
court_rocfor it is refused with422 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
tokensis the sum of its checks’ prices. Prices can change, andGET /checksalways 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’sapplicantPriceat checkout — CA$21.99 foridandcredit, CA$27.99 forid,creditandcourt_roc, at shipped prices — and you’re charged no tokens.
Shipped prices in Canada:
| Check id | What it is | Tokens |
|---|---|---|
id | Identity verification | 72 |
credit | Credit check | 192 |
court_roc | Court & eviction, rest of Canada | 72 |
court_qc | Court & eviction, Québec | 120 |
penal_qc | Penal search, Québec | 180 |
criminal | Police check | 240 |
bank | Bank verification | 96 |
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 atportalUrl.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.
Two links
| Link | Who it’s for |
|---|---|
portalUrl | Your 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. |
applicantLink | The applicant only: where they complete their checks. |
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}/advancedoes the rest at once. - Choose what happens with the applicant email’s +tag:
tenant+record@example.comfinds a court record,+stoppedstops the first check,+expirenever starts (expires after two minutes),+bouncehas the mail service refuse the invitation. No tag: everything clear. - Results are Carousel’s fictional sample applicant, cut to the checks you sent.
portalUrlopens the sample report. - Events go to the test stream:
GET /eventswith the test key.POST /webhook/testsends 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":falsefor 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 itsbuilding.createdandunit.createdevents 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
| Canada | United States | |
|---|---|---|
| Region | CA, in Canadian dollars | US, in US dollars |
| Checks | id, credit, court_roc, court_qc, penal_qc, criminal, bank | id, credit, records, bank |
| Combinations | Thirteen today | Four today |
| Providers | Identity: 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 checks | By 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.

