API quickstart
From a new key to a screening shown in your CRM, step by step. New to Carousel? Start with Concepts.
You need a Carousel account: sign up at app.oncarousel.com with Google. Base URL https://app.oncarousel.com/api/v1. Send JSON, get JSON. Every request carries Authorization: Bearer <your key>. Build with a test key (cp_test_…): no email, no tokens, no real check. Workspaces and buildings are your real ones, though — one you add with a test key is real, and shows in Carousel. With a live key every send is real — see Concepts.
1. Create a key
In Carousel, open the account menu and choose Developers, then Keys. Name the key after what will use it — “Our CRM”, up to 60 characters — and choose Create key. Switch on Test key first: it starts cp_test_ — no email, no tokens, a simulated applicant. Copy it straight away: it’s shown once. When you go live, make a live key the same way (it starts cp_live_).
Choose which workspaces it reaches. Every workspace you can use, on by default, reaches this account’s workspaces and the ones other accounts shared with you, at your role in each: View only reads; Can screen and Can spend … tokens send. Switch it off to tick only some workspaces: the key then reaches those and the workspaces inside them, and never Private. Wherever a key reaches, it sees every screening filed there, whoever sent it. Which workspaces it reaches is fixed when it’s made: make a new key to change it.
Working on your company’s account as a developer? Its owner adds you in Developers → Access. Nothing is emailed: open Developers, choose Accept on the invite, then pick the company account under Account at the top. Developers opens on your own account each time, so check it before you create a key. There the switch reads Every workspace in this account: a developer’s keys never reach a workspace shared with the owner.
Tick Read applicant results only if this system should receive the checks’ results — see Applicant results. Show reports in my app, for reports inside your product, sees them too, through view links — see Show reports in your platform. A key with neither sends and follows screenings and sees each applicant’s email, never their results or documents. Both options are set when the key is made: make a new key to change them. If you’re a developer on someone else’s account, a live key with either option needs its owner to switch on Can see applicant data for you in Developers → Access. Test keys don’t.
Keep it on your server, for example as CAROUSEL_API_KEY. A key can send screenings, which spend tokens. An account can have up to 10 live keys and 10 test keys in use, counting its developers’ keys and any connected assistant’s (named “… (connected app)”). Revoke any of them in the same place; whatever uses a revoked key stops at once.
2. Check the key
curl https://app.oncarousel.com/api/v1/me \
-H "Authorization: Bearer $CAROUSEL_API_KEY"{
"account": { "id": "…", "name": "Your business" },
"key": { "id": "…", "name": "Our CRM", "reach": "all" },
"livemode": false
}livemode is false for a test key. reach says which workspaces the key reaches: all, every workspace you can use; listed, only the ones it was made for, given in key.workspaces; account, this account’s workspaces only — every key made before the choice existed, and a developer’s key for every workspace in this account.
3. Pick what to send
curl "https://app.oncarousel.com/api/v1/checks?region=CA" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"{
"region": "CA",
"currency": "CAD",
"checks": [
{ "id": "court_roc", "name": "…", "provider": "…",
"tokens": 72, "courtArea": "ROC" },
…
],
"combinations": [
{
"checks": ["id", "credit", "court_roc"],
"courtArea": "ROC",
"tokens": 336,
"applicantPrice": { "amount": …, "currency": "CAD" },
"sendable": { "tokens": true, "renter": true }
},
…
],
"workflows": [ … ]
}checks lists each check by its id — id (identity verification), credit, court_roc and so on — with its provider and its price in tokens. combinations lists what you can send: the checks that go together, the most each combination can cost in tokens, and what the applicant pays when they pay. At shipped prices, ["id", "credit", "court_roc"] is 72 + 192 + 72 = 336 tokens, or CA$27.99 when the applicant pays. Prices can change, so read them here.
Send the checks of one combination whose sendable is true for your payer: tokens when you pay, renter when the applicant pays. Today’s combinations are in Send and follow screenings. Carousel adds more over time, so build any list you show your users from this answer, not from a saved copy. workflows lists custom workflows Carousel set up for you; send those by id.
To see what can be sent in one workspace, add &workspace=<id> (or &building=<id>): the answer is for that workspace, and names its kind. For a workspace shared with you, it answers for the account it belongs to, with the custom workflows offered there.
4. Choose where it’s filed
Every screening is filed in one of three places:
- Under a building, and if you like one of its units. It shows on that building in Carousel, a building in Québec runs Québec’s court checks, and the unit’s rent — or the building’s, when the unit has none — is what the report weighs income against.
- In a workspace, with no building.
- In Private, with neither. Send
"region": "CA"in their place. Carousel lists it under “Private” in Applications. Not with a key limited to some workspaces: see below.
To file under a building, list the workspaces the key reaches — your own first, then, for a key that reaches them, the ones shared with you, each with its account, your role and canSend — then a workspace’s buildings — or add the building: if its address is already there, you get that building back. Your account starts with one workspace, My Workspace, made the first time you open Carousel, in the region you opened it in. Add more with POST /workspaces. With none in a region, file in Private. A key limited to some workspaces can do neither. It can’t make a workspace (403 not_allowed): make it in Carousel, then make a key that names it. And it can’t file in Private: a send with only region is 400 invalid_request, “This key is limited to some workspaces — name a workspace or building.” In a workspace shared with you, canSend must be true: View only can’t send there (403 not_allowed). See Workspaces and buildings.
curl "https://app.oncarousel.com/api/v1/workspaces?region=CA" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"
curl "https://app.oncarousel.com/api/v1/buildings?workspace=<workspace id>" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"5. Send it
Filed under a building:
curl -X POST https://app.oncarousel.com/api/v1/screenings \
-H "Authorization: Bearer $CAROUSEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lead-1042-send-1" \
-d '{
"checks": ["id", "credit", "court_roc"],
"applicant": { "email": "tenant@example.com" },
"building": "<building id>",
"externalId": "lead-1042"
}' Or in Private, with no workspace or building — region is then required:
curl -X POST https://app.oncarousel.com/api/v1/screenings \
-H "Authorization: Bearer $CAROUSEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lead-1043-send-1" \
-d '{
"checks": ["id", "credit", "court_roc"],
"applicant": { "email": "tenant@example.com" },
"region": "CA",
"externalId": "lead-1043"
}' With a test key, nobody is emailed: a simulated applicant completes it within a couple of minutes, and the email’s +tag picks what happens — tenant+record@example.com adds a court record, +stopped stops the first check, +expire expires it at 2 minutes, +bounce has the mail service refuse the invitation. POST /screenings/{id}/advance finishes it at once. With a live key we email the applicant their link. court_roc is the court check for the rest of Canada; for a building in Québec, send court_qc, penal_qc or both in its place — court_roc is refused there. externalId is your own id for this record; it comes back on the screening and in every event. If a request times out, send it again with the same Idempotency-Key and the same body, within 24 hours — it never sends twice. See Retrying safely.
{
"id": "6f0c…",
"status": "invited",
"externalId": "lead-1042",
"region": "CA",
"portalUrl": "https://app.oncarousel.com/report/6f0c…",
"applicantLink": "https://…",
"delivery": "sent",
"tokenCost": 336,
…
}delivery is sent when our mail service accepted the email; Send and follow screenings explains failed and none. tokenCost is the most this screening can cost, charged per check as each one completes. With a test key, portalUrl opens the sample report for every screening, applicantLink opens a test page, and delivery reads sent though nothing is emailed.
6. Show the link
Store id and portalUrl on your record, and show portalUrl to your team as a button — “View screening”. It opens for your account’s owner, signed in to Carousel, and for people the screening’s workspace or building is shared with — so share the workspace with teammates in Carousel first. Developers added in Developers → Access don’t get it, and a screening in Private opens for the owner only. They sign in with Google the first time; after that it opens straight away. For users with no Carousel login, show the report inside your product instead: Integrate your CRM.
Never email portalUrl to the applicant. Their link is applicantLink, which Carousel has already emailed them.
7. Follow it
Read what happened since last time, or set a webhook and have it pushed to you — see Events and webhooks. Events stay in GET /events, so a webhook delivery you missed can always be read again. Oldest first: save the answer’s cursor and pass it as after next time; while hasMore is true, ask again straight away. With a test key, this is how you see a test screening’s events — they aren’t pushed to your webhook.
curl "https://app.oncarousel.com/api/v1/events?after=0" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"8. Read the results (optional)
With a key allowed to read them, fetch each check’s results once screening.completed arrives — see Applicant results.
curl https://app.oncarousel.com/api/v1/screenings/<id>/results \
-H "Authorization: Bearer $CAROUSEL_API_KEY"

