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

Send and follow screenings

One request sends a screening: what to run, who it’s for, where it’s filed. Its answer carries the link to show.

The request

POST /screenings, with these fields — every one, with its options and where its values come from. Anything else is refused.

FieldOptions
checks
One of checks or workflow
The ids of exactly one combination of checks, in any order — for example ["id", "credit"], or in Québec ["id", "credit", "court_qc", "penal_qc", "bank"]. The ids — Canada, Québec: id, credit, court_qc, penal_qc, criminal, bank. Canada, rest of Canada: id, credit, court_roc, criminal, bank. US: id, credit, records, bank. Québec’s court checks are accepted for a building anywhere; a building in Québec refuses court_roc. GET /checks lists every combination; Carousel adds more over time.
Values from: Checks and combinations · GET /checks
workflow
One of checks or workflow
A custom workflow’s id, in place of checks.
Values from: workflows in GET /checks · Custom workflows
applicant
Required
{ "email": "…" } — an email address, up to 254 characters. No phone or name.
region
Required with no workspace or building
CA or US. On its own, files it in your Private pool — not with a key limited to some workspaces; with a workspace or building, it must match theirs.
More: Workspaces and buildings
workspace
Optional
A workspace’s id: files it there, with no building.
Values from: GET /workspaces · Workspaces
building
Optional
A building’s id: files it under that building, in its workspace.
Values from: GET /buildings, POST /buildings · Buildings and units
unit
Optional, with building
A unit’s id in that building.
Values from: Buildings and units
payer
Optional
tokens (the default for checks): your token balance. renter: the applicant pays at checkout. A custom workflow’s payer is fixed.
More: Tokens and billing
delivery
Optional
email (the default): Carousel emails the link. none: you hand the applicant applicantLink yourself.
More: The answer
externalId
Optional
Your own id for this record, up to 200 characters. On every event.
More: Find by your own id
Idempotency-Key
Optional header — recommended
Any string up to 255 characters, new for each send you mean. A repeat within 24 hours returns the first answer and sends nothing.
More: Retrying safely
  • checks or workflow. Send exactly one. checks is the ids of one combination’s checks, such as ["id", "credit", "court_roc"] — the combinations are below, and in GET /checks. A custom workflow is sent by its id, from workflows in GET /checks.
  • applicant. The applicant’s email address. There are no phone or name fields; their name comes from their ID once they complete it.
  • payer. tokens: you pay from your token balance. renter: the applicant pays Carousel at checkout. Left out: tokens for checks, the workflow’s own payer for a custom workflow. In a workspace shared with you, tokens is billed as Carousel bills you there as a member: the sharing account’s balance when they let you spend their tokens, your own otherwise. The screening is filed in their account either way.
  • Where it’s filed. A building files it under that building, in the building’s own workspace; add unit for one of its units. A workspace files it there with no building. With neither, it’s filed in Private, and region is required — a key limited to some workspaces gets 400 invalid_request instead: name a workspace or building. The place must be one the key reaches (404 not_found otherwise), and in a workspace shared with you your role there must be able to send: View only is 403 not_allowed.
  • region. CA or US. With a workspace or building it’s optional; if you send it, it must match the property’s region, or the answer is 409 region_mismatch.
  • externalId. Your own id for this record. Stored, searchable, and on every event.
  • delivery. email: we email the link. none: we don’t, and you hand the applicant applicantLink yourself — to text it, for example.

A field the request doesn’t take is refused with invalid_request, naming it — a misspelt externalId is never dropped in silence.

A malformed checks — not a list, empty, more than 12, with a duplicate, or with an id that isn’t lowercase letters and _ — is 400 invalid_request. A well-formed list that isn’t exactly one combination is 422 unknown_combination.

Checks and combinations

Send the checks to run by their ids. They must be exactly one combination’s checks, in any order — no more, no fewer. GET /checks?region=CA lists the checks and combinations, with each one’s live price in tokens. The check id id is identity verification; it’s unrelated to the id field objects carry.

Canada

  • id — Identity verification.
  • credit — Credit check. It’s a hard inquiry: it’s recorded on the applicant’s credit file.
  • court_roc — Court & Eviction Check (Rest of Canada).
  • court_qc and penal_qc — Court & Eviction Search (QC) and Penal Search (QC), Québec’s court checks. They’re separate searches, so a combination can run either or both.
  • criminal — Police Check (All of Canada).
  • bank — Bank verification.

Canada’s thirteen combinations today, by the court checks each runs. Carousel adds more over time, so build any list you show from GET /checks rather than copying this one:

Court checksChecks to send
Noneid, credit
Noneid, credit, bank
Noneid, credit, criminal, bank
Rest of Canadaid, credit, court_roc
Rest of Canadaid, credit, court_roc, bank
Rest of Canadaid, credit, court_roc, criminal, bank
Québecid, credit, court_qc
Québecid, credit, penal_qc
Québecid, credit, court_qc, penal_qc
Québecid, credit, court_qc, bank
Québecid, credit, penal_qc, bank
Québecid, credit, court_qc, penal_qc, bank
Québecid, credit, court_qc, penal_qc, criminal, bank

The court checks set the court area: each combination’s courtArea in GET /checks is ROC, QC or null. Only a building in Québec refuses court_roc, with 422 court_area_mismatch: send court_qc, penal_qc or both for it. Québec’s checks sent for a building elsewhere, or with no building, are accepted — you choose. What each search covers: Court & eviction checks.

United States

GET /checks?region=US lists id, credit, records (criminal and legal records) and bank, in four combinations today:

  • id, credit
  • id, credit, bank
  • id, credit, records
  • id, credit, records, bank

Custom workflows

Carousel sets them up for an account — contact Carousel. They’re listed under workflows in GET /checks; send one with "workflow": "<id>" in place of checks. A workflow’s payer is fixed: leave payer out, or send the same one. A different payer is 422 workflow_unavailable. A workflow listed with workspaces can be filed only there, not in Private. Its court checks must suit the building: a Québec workflow is refused for a building outside Québec, and the other way round, also with 422 workflow_unavailable.

The answer

201 with the screening:

FieldTypeWhat it is
idstringThe screening’s id.
statusstringAlways invited.
externalIdstringYour own id, if you sent one.
regionstringCA or US: the region it’s filed in.
workspacestringThe workspace it’s filed in: the one you sent, or the building’s own.
building, unitstringThe building and unit it’s filed under, when you sent them.
portalUrlstringThe screening’s page in Carousel, for people who sign in to Carousel — your team. For users with no Carousel login, show the report with a view link instead (Integrate your CRM, steps 4 and 5). Never send it to the applicant.
applicantLinkstringThe link the applicant opens to complete their checks. It’s for the applicant only.
deliverystringWhat happened to the invitation email: below.
tokenCostnumberThe most this screening can cost in tokens, when every check completes — e.g. 336 for ["id", "credit", "court_roc"] at shipped prices. 0 when the applicant pays.
createdAtstringWhen Carousel created it, by the server’s clock.

delivery is one of:

  • sent — our mail service accepted the email.
  • failed — it was refused right away. Hand the applicant applicantLink yourself.
  • none — you sent "delivery": "none", or the email wasn’t sent at that moment.

A bounce after the mail service accepted the email isn’t reported. To be sure the applicant has their link, send "delivery": "none" and hand them applicantLink yourself.

Retrying safely

Send an Idempotency-Key header — any string up to 255 characters, new for each send you mean: a UUID, or your record’s id plus an attempt number (lead-1042-send-1). Never your record’s id alone — a later re-send to the same applicant would replay the first send and email nobody. Keys are per API key, last 24 hours, and a blank header counts as none. Then:

  • The same key with a byte-identical body within 24 hours returns the first answer — its status and body — with Idempotent-Replayed: true, and sends nothing. If the first request died after the screening went out, the repeat is 200 with the screening as GET /screenings/{id} returns it.
  • The same key with a different body — even the same JSON, formatted differently — is 409 idempotency_conflict.
  • A repeat while the first is still running is 409 request_in_progress — wait a few seconds and repeat.
  • A refusal about the moment frees the key, so the same request can go through later with the same key: rate_limited, insufficient_tokens, combination_unavailable, workflow_unavailable, carousel_error and internal_error. A 503 busy never reached the send at all: retry it with the same key.
  • Any other refusal is kept for that key, and the same request gets the same answer: don’t retry it unchanged. That includes 403 not_allowed, and the 400 invalid_request a key limited to some workspaces gets for a send with only region (“This key is limited to some workspaces — name a workspace or building.”): that 400 uses up the Idempotency-Key. After fixing a 403, that 400, a 404, a 409 region_mismatch or a 422, send with a new key: the old one replays its refusal, and a changed body with it is 409 idempotency_conflict. A 400 for a malformed body never reaches the key, so the fixed request can use it.
  • Sends count toward the limit of 30 a minute even when they’re replays or refusals — all but a 400 for a malformed body, which is refused first. Test sends have their own 30 a minute.

Without the header, a retry sends again.

Read a screening

curl https://app.oncarousel.com/api/v1/screenings/<id> \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

GET /screenings/{id} returns exactly these fields:

FieldTypeWhat it is
idstringThe screening’s id.
statusstringWhere it is: see Lifecycle and timing, below.
externalIdstringYour own id, if one was sent.
applicantEmailstringThe applicant’s email address. Every key sees it.
checksarrayThe check ids it was sent with.
workflowstring or nullA custom workflow’s id, or null.
payerstringtokens or renter.
tokenCostnumberThe most it can cost in tokens, when every check completes; 0 when the applicant pays.
portalUrlstringThe screening’s page in Carousel, for your team.
applicantLinkstringThe applicant’s link, for the applicant only.
createdAtstringWhen it was created.
invitedAt, startedAt, completedAtstringWhen the invitation went out, when the applicant started, and when every check was done. startedAt is when Carousel first saw the applicant at work; null if every check finished before it looked.
stepsarrayOne per check: its check id, name, status and completedAt.
livemodebooleanfalse for a test key’s screening: nobody was emailed and nothing was charged.

It doesn’t return delivery, workspace, building, unit or region. Where a screening is filed is in the list’s items, below.

Lifecycle and timing

StatusMeans
invitedSent; the applicant hasn’t started.
in_progressThe applicant has started.
completedEvery check is done — the report is ready at portalUrl.
expiredNobody started it within 30 days of the invitation. Only unstarted screenings expire.
cancelledCancelled in Carousel.

Each step’s status is waiting, in_progress, done or stopped. stopped means it didn’t run to a normal finish: an applicant error, a time-out, or the provider stopped it. One the provider finished (it has a completedAt) is charged like any completed check; one that never finished isn’t. A check made of two provider steps — credit, and records in the US — is charged once either step finishes, even if it reads stopped with no completedAt. Applicant results say what the provider returned.

Tokens are charged per check, as each one completes. Checks that never complete are never charged.

Cancel and remind

Neither is in the API. Cancel or remind in Carousel, from the application’s row — see Remind, cancel and expiry.

  • A cancelled or expired screening’s link still works for the applicant, but checks they finish afterwards are neither shown nor charged. Results mark them withheld.
  • applicantLink is on every read of the screening, if you need to hand it over again.
  • To text the link instead of emailing it, send "delivery": "none" and text applicantLink yourself.

List your screenings

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

Every screening the key reaches — your account’s, and for a key that reaches them, the ones in workspaces shared with you — sent through the API or from Carousel, by anyone, before or after you had a key — newest first: { "data": [ … ], "cursor": "…", "hasMore": true }. Each item has the fields GET /screenings/{id} returns, plus workspace, building, unit and updatedAt.

  • limit is 1 to 100; 50 if you leave it out.
  • Pass cursor back as after while hasMore is true. Treat cursors as opaque: store and send them as they are.
  • Narrow it with status (invited, in_progress, completed, expired, cancelled), workspace, building or updatedSince. status takes one or more, comma-separated: status=invited,in_progress. updatedSince can include screenings with no visible change; events are the precise way to follow changes.

Co-applicants and guarantors your team adds in Carousel have screenings of their own. They’re listed here with externalId null, and the API can’t add them. To tie one to your record, use the application.* events: data.screenings lists every screening on the application, with its externalId. 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.

Import your history once this way, then follow changes with events or a webhook.

Find by your own id

curl "https://app.oncarousel.com/api/v1/screenings?externalId=lead-1042" \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

Up to 50 screenings with that externalId, newest first, with no cursor. Your account’s ids only: it finds screenings filed in your account or sent by your account’s keys, so another account’s id never matches yours. On a screening in a workspace shared with you that your account didn’t send, externalId reads null.

What a key sees

Every screening filed where the key reaches, once its invitation went out — whoever sent it, including from Carousel’s own screens. By default that’s your account’s workspaces, buildings and Private, and the workspaces other accounts shared with you, at your role there. A key limited to some workspaces sees only theirs, and one made before that choice existed sees only your account’s. See Concepts.

Every key sees each screening’s status, links and applicantEmail. Only a key made with Read applicant results reads the checks’ results and documents, at their own endpoint. A key made with Show reports in my app can’t, but it can show any report the key reaches, documents and PDF included, inside your app through a view link — see Show reports in your platform.

The infrastructureof yes.