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

Applicant results

Each check’s results and the documents behind them — for keys allowed to read them.

A permission of its own

Only a key made with “Read applicant results” ticked (account menu → Developers → Keys) can read results or documents here. Any other key gets 403 results_not_allowed here. A key made with “Show reports in my app” can’t call these endpoints either, but it can open any report the key reaches, documents and PDF included, through a view link: guard it like a results key. A key with neither option sees each applicant’s email in /screenings, and never their results or documents. If you’re a developer on someone else’s account, a live key with either option needs the owner to switch on “Can see applicant data” for you (Developers → Access); test keys don’t. Results, documents and view links follow the key’s reach: a screening in a workspace shared with you reads as one of your own. Every read is logged, in the account the screening is filed in.

Read them

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

Fetch them when screening.completed arrives, or after each screening.step_completed — a check that finished has its result within minutes; one that stopped may have none. The answer has the screening, its steps, every check, and its documents:

{
  "screening": { "id": "6f0c…", "status": "completed", "externalId": "lead-1042", "portalUrl": "…" },
  "steps": [ { "key": "credit", "name": "Credit check", "status": { "state": "clear", "label": "Clear" }, … } ],
  "checks": {
    "identity": { "availability": "present", "result": { … } },
    "credit":   { "availability": "present", "result": { … } },
    "court":    { "availability": "present", "result": { … } },
    "police":   { "availability": "not_bought", "result": null },
    "bank":     { "availability": "present", "result": { … } },
    …
  },
  "documents": [ { "id": "…", "kind": "id_front", "downloadUrl": "…" } ]
}

Which check fills which key

Each check you send fills a key in the answer’s checks:

Check idResults key
ididentity
creditcredit
creditalternativeCredit: extra bureau data from the same credit pull.
court_roccourt
court_qccourt
penal_qccourt
criminalpolice
bankbank
records (US)court and police
NoneselfDeclaration: what the applicant declared.
Nonequestionnaire: what the applicant answered.

Is a result there?

Each key in checks has an availability:

availabilityMeans
presentThe results are in result.
withheldThe screening was cancelled or expired before this check finished, so it isn’t shown. note says which: “Not shown — this screening was cancelled before this check finished.”, or the same with “expired”. That’s its only meaning.
not_boughtThis screening didn’t include the check.
absentNothing is stored for it. note says which: “Not completed yet.” (still to come) or “Nothing came back for this check.” (its step finished with nothing to show, and it won’t change). selfDeclaration, questionnaire and alternativeCredit read absent when the screening has none.
errorThe result couldn’t be read. note is one fixed sentence, the same every time.

A check’s status

Each check’s status, as on the steps above, is { "state": "clear", "label": "Clear" }. Branch on state; label is its wording for people. state is one of clear, incomplete, processing, retry_asked, applicant_error, timed_out, cancelled, not_started or unknown.

state says how far the provider got — clear means it finished — not whether the applicant passed: what it found is in result, and label is what Carousel’s report shows. A screening’s steps (GET /screenings/{id}) answer a different question: where each check is — waiting, in_progress, done or stopped.

None of them approves or rejects the applicant. The decision is yours.

What each check returns

  • identity — the document (type, number, country, issue and expiry dates), the person on it, the address, and the ids of its images.
  • credit — the bureau, scores with their factors, trades with monthly payment history, enquiries, collections, bankruptcies, employments and addresses.
  • court — a summary for the Court & Eviction searches and, when bought, a penalSummary for the Penal Search — clear, possible_matches or not_clear_yet, as the report says them — and each provider’s items, tagged with their search.
  • police — the result — negative, confirmation or incomplete — with the convictions declared and the address history. When the check timed out, was cancelled or hit an applicant error: only "hidden": true and where it is.
  • bank — connections, accounts — the account number as its last four digits — and how many transactions; the transactions themselves page through their own endpoint (below).
  • alternativeCredit, selfDeclaration, questionnaire — what was returned, or what the applicant declared.

Money in results — balances, payments, transaction amounts, income — is in the currency the provider gave, in dollars with decimals for cents (for example "amount": 48.85). Never cents, never tokens.

The API reference lists each check’s result with an example.

Bank transactions

curl "https://app.oncarousel.com/api/v1/screenings/<id>/transactions?after=0&limit=500" \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

In ledger order, up to 500 a page: { "data": [ … ], "cursor": "500.1791060000000", "hasMore": true, "total": 1240 }. Pass cursor back as after while hasMore is true. If the bank data changes between pages, the old cursor answers 409 results_changed — start again from after=0. truncated is true when an account had more transactions than Carousel keeps (the bank result says so too, as transactionsTruncated); the rest aren’t available.

Documents

documents lists the stored files, each with its id, kind and downloadUrl. The kinds:

  • id_front and id_back — the ID document’s two sides.
  • id_face — the selfie.
  • background_pdf — the police certificate.
  • legal_item — a copy of a court file.
  • questionnaire_upload — a file uploaded with the questionnaire.
  • self_declaration_doc — a document from the self-declaration.
  • bureau_report — the credit bureau’s report.
curl -o id-front.jpg https://app.oncarousel.com/api/v1/screenings/<id>/documents/<document id> \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

A file over 4 MB comes in ranges: send Range: bytes=0-4194303, then the next 4 MB, and onward until Content-Range shows the whole file. A range longer than 4 MB is cut to 4 MB. Without a range, a file that size answers 413 document_too_large; a bad range answers 416.

Results, transactions and documents share a budget of 30 reads a minute per key. Every read is logged, in the account the screening is filed in.

What never leaves

  • Approvals and rejections. Carousel makes none. Every status is read from what the provider returned.
  • Providers’ own links and raw data. Download the stored copies from documents instead.
  • Full bank account numbers. The last four digits only. ID document numbers do come in full.

Events and webhooks never carry results — ids, your externalId and the link only.

Applicant data

Results are regulated personal information. Use them only to assess the rental application, store them only as long as you need them, 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.