Build with an AI agent
The API describes itself, so an agent like Claude can learn it, build with it, and use it.
Four addresses, no key needed
https://app.oncarousel.com/api/v1— what the API is: its endpoints, how to authenticate, where the rest lives.https://app.oncarousel.com/api/v1/guide.md— a one-page walkthrough in plain text — the best first read for an agent.https://app.oncarousel.com/api/v1/openapi.json— the full contract (OpenAPI 3.1): every endpoint, field and error. Tools that generate clients import it.https://app.oncarousel.com/api/reference— the same contract as a page for people, with a request console.
Add Carousel to your AI assistant (MCP)
Carousel is also an MCP server, so Claude, ChatGPT, Cursor or any MCP client can use it as tools: list what you can send, add buildings, send screenings, follow them, and — with a results key — read the results. It acts with a key — one it makes for the connection when you sign in, or one you send — with the same limits and refusals.
| Connection | How it works |
|---|---|
| claude.ai or ChatGPT, Live | Add https://mcp.oncarousel.com as a custom connector and sign in with Carousel. Choose Live, and tick Also read applicant results on that screen if the assistant should read them. Carousel makes a key for the connection, named after the app, in Developers → Keys — it counts toward your 10 live keys; revoke it there to disconnect. Under Workspaces, keep Every workspace you can use or choose Only these workspaces… and tick the ones it may reach; the connection reaches what you chose, like any key. Connecting the same assistant again (say, to switch results on) replaces its earlier connection in that mode; the old key is revoked. |
| claude.ai or ChatGPT, Test | The same, choosing Test: a test key and a simulated applicant — nobody is emailed and no tokens are spent. Buildings it adds are real ones in your workspaces. |
| Claude Code, Cursor, others | Send a key you made: Authorization: Bearer <your key>. A test key (cp_test_…) to try it. |
Signing in connects the account you own. As a developer on your company’s account, make a key on that account (pick it at the top of Developers) and use it from Claude Code, Cursor or another client that sends a key — or ask the owner to connect the assistant.
Carousel doesn’t ask for confirmation: the assistant asks before send_screening when its app asks before sensitive tools. A live send emails the applicant and can’t be cancelled through the API or the assistant, and a live credit check is a hard inquiry. Try it in Test first.
- Address:
https://mcp.oncarousel.com(Streamable HTTP). - In claude.ai or ChatGPT: add it as a custom connector, then sign in with Carousel and choose Live or Test (above).
- Anywhere else: send a key,
Authorization: Bearer <your key>— a test key (cp_test_…) to try it without emailing anyone or spending tokens.
In Claude Code:
claude mcp add --transport http carousel https://mcp.oncarousel.com \
--header "Authorization: Bearer $CAROUSEL_API_KEY"In Cursor (mcp.json):
{
"mcpServers": {
"carousel": {
"url": "https://mcp.oncarousel.com",
"headers": { "Authorization": "Bearer ${env:CAROUSEL_API_KEY}" }
}
}
}In Claude Desktop, through mcp-remote:
{
"mcpServers": {
"carousel": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.oncarousel.com", "--header", "Authorization:${AUTH_HEADER}"],
"env": { "AUTH_HEADER": "Bearer <your key>" }
}
}
}The same setups are in Carousel: account menu → Developers → Resources.
The assistant’s tools
Each tool is one call to the API, with the connection’s own key. Each is marked as reading or changing data, so most assistants ask you before a write — that’s the assistant’s setting, not Carousel’s.
Reads
whoami— the account and key the connection acts for, and which workspaces it reaches (key.reach).list_checks— the checks and combinations you can send in a region, with their prices.list_workspaces— the workspaces it reaches, each with itsaccount, yourroleandcanSend.list_buildings— a workspace’s buildings and units.get_screening— one screening’s status and each check’s progress.list_screenings— the screenings it reaches, newest first, or the ones your account sent with an id of yours.get_results— each check’s results, only when the connection may read results.list_events— everything that happened to the screenings it reaches, oldest first: the webhook’s events.
Writes
add_building— adds a building and its units. An address that’s already a building returns it.advance_test_screening— test mode only: finishes a test screening now.
Sensitive write
send_screening— sends a screening. With a live connection it emails the applicant and can spend tokens.
Results through an assistant leave out ID document numbers (the number on the identity check’s document and the police check’s documentNumber are null). The report in Carousel, and the API itself, keep them.
Give your agent a task
Read https://app.oncarousel.com/api/v1/guide.md — it explains the Carousel API.
My test API key is in the CAROUSEL_API_KEY environment variable; never print it.
Send identity verification, a credit check and Québec's court checks to tenant@example.com,
filed under 3645 Boulevard Gouin Ouest, unit 4B, in my "Plateau portfolio" workspace
(add the building if it isn't there).
Use the Idempotency-Key "lead-1042-send-1" and externalId "lead-1042".
Tell me the portalUrl, then check the screening's status.The agent finds “Plateau portfolio” by name with GET /workspaces, which lists each workspace’s id and name.
Put it in an environment variable or secret store the agent can read. A key can send screenings, which spend tokens — make one per agent, limited to the workspaces it works in, and revoke it when you’re done.
What makes it easy for an agent
- Every error has a hint — the next thing to do, naming the endpoint or field.
- Nothing is guessed. An unknown field in a request body is refused, never dropped. A misspelt query parameter is ignored, so spell them as in the reference.
- Retries are safe. With an Idempotency-Key, a repeated send never sends twice.
- What you can send is listed.
GET /checksgives every combination of checks; a send that isn’t one is refused with a hint that points back to it. - Places by name.
GET /workspaceslists workspaces with their names, andGET /buildingsa workspace’s buildings with their addresses. - Plain values. Check ids, regions and statuses are short words:
credit,CA,completed. - Adding is safe to repeat. Sending an address that’s already a building returns that building.

