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.
| Field | Options |
|---|---|
checksOne 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 |
workflowOne of checks or workflow | A custom workflow’s id, in place of checks.Values from: workflows in GET /checks · Custom workflows |
applicantRequired | { "email": "…" } — an email address, up to 254 characters. No phone or name. |
regionRequired 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 |
workspaceOptional | A workspace’s id: files it there, with no building.Values from: GET /workspaces · Workspaces |
buildingOptional | A building’s id: files it under that building, in its workspace.Values from: GET /buildings, POST /buildings · Buildings and units |
unitOptional, with building | A unit’s id in that building.Values from: Buildings and units |
payerOptional | 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 |
deliveryOptional | email (the default): Carousel emails the link. none: you hand the applicant applicantLink yourself.More: The answer |
externalIdOptional | Your own id for this record, up to 200 characters. On every event. More: Find by your own id |
Idempotency-KeyOptional 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 |
checksorworkflow. Send exactly one.checksis the ids of one combination’s checks, such as["id", "credit", "court_roc"]— the combinations are below, and inGET /checks. A custom workflow is sent by itsid, fromworkflowsinGET /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:tokensfor checks, the workflow’s own payer for a custom workflow. In a workspace shared with you,tokensis 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
buildingfiles it under that building, in the building’s own workspace; addunitfor one of its units. Aworkspacefiles it there with no building. With neither, it’s filed in Private, andregionis required — a key limited to some workspaces gets400 invalid_requestinstead: name a workspace or building. The place must be one the key reaches (404 not_foundotherwise), and in a workspace shared with you your role there must be able to send: View only is403 not_allowed. region.CAorUS. With a workspace or building it’s optional; if you send it, it must match the property’s region, or the answer is409 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 applicantapplicantLinkyourself — 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_qcandpenal_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 checks | Checks to send |
|---|---|
| None | id, credit |
| None | id, credit, bank |
| None | id, credit, criminal, bank |
| Rest of Canada | id, credit, court_roc |
| Rest of Canada | id, credit, court_roc, bank |
| Rest of Canada | id, credit, court_roc, criminal, bank |
| Québec | id, credit, court_qc |
| Québec | id, credit, penal_qc |
| Québec | id, credit, court_qc, penal_qc |
| Québec | id, credit, court_qc, bank |
| Québec | id, credit, penal_qc, bank |
| Québec | id, credit, court_qc, penal_qc, bank |
| Québec | id, 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,creditid,credit,bankid,credit,recordsid,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:
| Field | Type | What it is |
|---|---|---|
id | string | The screening’s id. |
status | string | Always invited. |
externalId | string | Your own id, if you sent one. |
region | string | CA or US: the region it’s filed in. |
workspace | string | The workspace it’s filed in: the one you sent, or the building’s own. |
building, unit | string | The building and unit it’s filed under, when you sent them. |
portalUrl | string | The 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. |
applicantLink | string | The link the applicant opens to complete their checks. It’s for the applicant only. |
delivery | string | What happened to the invitation email: below. |
tokenCost | number | The 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. |
createdAt | string | When 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 applicantapplicantLinkyourself.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 is200with the screening asGET /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_errorandinternal_error. A503 busynever 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 the400 invalid_requesta key limited to some workspaces gets for a send with onlyregion(“This key is limited to some workspaces — name a workspace or building.”): that 400 uses up the Idempotency-Key. After fixing a403, that400, a404, a409 region_mismatchor a422, send with a new key: the old one replays its refusal, and a changed body with it is409 idempotency_conflict. A400for 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
400for 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:
| Field | Type | What it is |
|---|---|---|
id | string | The screening’s id. |
status | string | Where it is: see Lifecycle and timing, below. |
externalId | string | Your own id, if one was sent. |
applicantEmail | string | The applicant’s email address. Every key sees it. |
checks | array | The check ids it was sent with. |
workflow | string or null | A custom workflow’s id, or null. |
payer | string | tokens or renter. |
tokenCost | number | The most it can cost in tokens, when every check completes; 0 when the applicant pays. |
portalUrl | string | The screening’s page in Carousel, for your team. |
applicantLink | string | The applicant’s link, for the applicant only. |
createdAt | string | When it was created. |
invitedAt, startedAt, completedAt | string | When 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. |
steps | array | One per check: its check id, name, status and completedAt. |
livemode | boolean | false 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
| Status | Means |
|---|---|
invited | Sent; the applicant hasn’t started. |
in_progress | The applicant has started. |
completed | Every check is done — the report is ready at portalUrl. |
expired | Nobody started it within 30 days of the invitation. Only unstarted screenings expire. |
cancelled | Cancelled 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. applicantLinkis 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 textapplicantLinkyourself.
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.
limitis 1 to 100; 50 if you leave it out.- Pass
cursorback asafterwhilehasMoreis true. Treat cursors as opaque: store and send them as they are. - Narrow it with
status(invited,in_progress,completed,expired,cancelled),workspace,buildingorupdatedSince.statustakes one or more, comma-separated:status=invited,in_progress.updatedSincecan 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.

