Workspaces and buildings
File each screening where it belongs — and add buildings from your own system as you go.
A screening is filed under a building (and, if you like, one of its units), in a workspace with no building, or in Private, with neither. The API reads and adds the workspaces and buildings the key reaches, the same ones you see in Carousel — see Workspaces, buildings and units: your account’s own and the ones other accounts shared with you, at your role there — all of them, or only the ones a limited key was made for. One the key doesn’t reach answers 404 not_found, like an unknown id. A test key reads and adds the same real ones: a workspace or building added with it is real.
The places
- Workspace → building → unit. A workspace holds buildings; a building holds units.
- One region per workspace. A workspace is
CAorUS. Aregionsent with a screening must match its workspace’s or building’s, or the answer is409 region_mismatch. - Private. Screenings with no workspace or building. Carousel lists them under “Private” in Applications, for the account’s owner only. Send
"region": "CA"(or"US") with no workspace or building to file one there. A key limited to some workspaces can’t file there (400 invalid_request— name a workspace or building): Private, and any building outside a workspace, are never in its list.
Workspaces
curl "https://app.oncarousel.com/api/v1/workspaces?region=CA" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"{ "data": [ … ] }: each workspace’s id, name, region, kind — tenant, commercial, employment or regular — parent (the workspace it sits in, or null; read-only in the API), account (the id and name of the account it belongs to: yours, or the one that shared it), role (yours there: owner in your own account; in a shared one, screener for both Can screen and Can spend … tokens, or viewer for View only) and canSend (whether that role can send screenings there). Your account’s workspaces come first, oldest first, then — for a key that reaches every workspace you can use — the ones shared with you. A key limited to some workspaces lists only those and the workspaces inside them. To find a workspace by name, list them and match name.
To add one:
curl -X POST https://app.oncarousel.com/api/v1/workspaces \
-H "Authorization: Bearer $CAROUSEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Plateau portfolio", "region": "CA" }'name (up to 120 characters) and region (CA or US) are required. kind is optional: tenant, the default, is the only kind that can be created today, and any other is refused (400 invalid_request). Nothing else is taken. It’s made in the key’s own account, never in a shared one, and a key limited to some workspaces can’t make one (403 not_allowed). The answer is 201 with its id, name, region, kind and parent.
Buildings and units
curl "https://app.oncarousel.com/api/v1/buildings?workspace=<workspace id>" \
-H "Authorization: Bearer $CAROUSEL_API_KEY"Each building’s id, address, workspace, region, province, and units with their id and label. Rent isn’t returned, and it can’t be changed through the API: set it when you add the building or unit, or change it in Carousel. A screening in Private, or in a workspace with no building, has no rent for the report to use.
province is the province saved on the building. Carousel saves one only when the address was picked from its suggestions in Carousel, so a building you add through the API has null there. That doesn’t change the checks: on every send, Carousel reads the province from the address — a Québec postal code (G, H or J), or a province or Québec city written in it.
Add a building — or find it
curl -X POST https://app.oncarousel.com/api/v1/buildings \
-H "Authorization: Bearer $CAROUSEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace": "<workspace id>",
"address": "3645 Boulevard Gouin Ouest, Montréal, QC H4K 1B3",
"units": ["4B", "5A"],
"rent": 2150
}' 201 when it’s new. When the address names a building already in that workspace — the same number and street, and the same city, street type and direction (written on both, or left out of both) — you get that building back with 200 and "created": false, plus any units it didn’t have. An address that adds or leaves out the city or the direction makes a new building. Send each address the same way every time, or keep the building’s id.
address— the street address, up to 200 characters. Carousel reads the province from it: the postal code, or the province and city names. A unit written into the address moves to the units: “44 King St W #1203” adds unit1203.units— up to 500 unit labels of 1 to 40 characters. Leave it out for a whole-building rental.rent— optional: the monthly rent in the region’s currency, up to 1,000,000, ornull. The report weighs the applicant’s income against it. Withunits, it’s each new unit’s rent (the building gets none), so send the screening’sunitfor the report to use it. It sets the rent of what this request creates only: an existing building or unit keeps its own, which you change in Carousel.
In a workspace shared with you, adding a building needs a role that can screen — View only is 403 not_allowed — and the building is the sharing account’s, as is its building.created event: it goes to their stream, not yours.
Send into it
Send the building’s id (and a unit’s id) with the screening. Its workspace comes with it, and so does its region: leave region out, or send the same one.
- A building whose address is in Québec runs Québec’s court checks: send
court_qc,penal_qcor both for it.court_rocis refused with422 court_area_mismatch. - For a building anywhere else, either set is accepted: you choose.
- With no workspace or building, send
"region": "CA"and it goes to Private — not with a key limited to some workspaces.

