Applicant results
Each check’s results and the documents behind them — for keys allowed to read them.
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 id | Results key |
|---|---|
id | identity |
credit | credit |
credit | alternativeCredit: extra bureau data from the same credit pull. |
court_roc | court |
court_qc | court |
penal_qc | court |
criminal | police |
bank | bank |
records (US) | court and police |
| None | selfDeclaration: what the applicant declared. |
| None | questionnaire: what the applicant answered. |
Is a result there?
Each key in checks has an availability:
| availability | Means |
|---|---|
present | The results are in result. |
withheld | The 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_bought | This screening didn’t include the check. |
absent | Nothing 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. |
error | The 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— asummaryfor the Court & Eviction searches and, when bought, apenalSummaryfor the Penal Search —clear,possible_matchesornot_clear_yet, as the report says them — and each provider’s items, tagged with their search.police— theresult—negative,confirmationorincomplete— with the convictions declared and the address history. When the check timed out, was cancelled or hit an applicant error: only"hidden": trueand 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_frontandid_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
documentsinstead. - 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.
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.

