Carousel PortalThe Carousel Portal — workflows, applications, and settings in one workspace.

Carousel is a modular platform that simplifies how businesses collect, verify, and process applicant data — turning complex workflows into intuitive digital flows.

You choose the steps that matter for your decision. Applicants complete them in one guided flow on their phone. Results arrive in the Portal, and optionally in your own systems, as structured data.

What it replaces

• PDF forms and email attachments
• Separate vendor portals for identity, banking, and credit
• Manual re-keying of applicant data
• Chasing missing documents before review can start

Mix any of these steps into a single flow. Each is verified at the source and billed only when an applicant completes it.

How it works

1. The applicant photographs the front and back of a government-issued ID.
2. A liveness selfie is captured and matched against the document portrait.
3. Fields are extracted and returned as structured data.

What it returns

• Full name, date of birth, gender
• Document number, type, and issuing province or country
• Date of issue and expiry
• Front and back images, stored as signed URLs

At a glance

Provider

Onfido / Ondato

Billing

Per completed step

Most other steps can require identity verification first, so the result is tied to a verified person rather than a typed-in name.

How it works

1. The applicant logs into their bank in a secure window.
2. Accounts are confirmed and transaction history is retrieved.
3. Income and cash-flow insights are generated from the raw transactions.

What it returns

• Account ownership and institution
• Balances and account numbers (masked)
• Income estimates and transaction categories
• Rule-engine outcomes where configured

At a glance

Provider

Plaid / Flinks

Billing

Per completed step

Credentials are never seen or stored by Carousel or by your business. Where a bank is unsupported, a document-upload fallback can be enabled.

How it works

1. Consent language is presented and accepted as part of the step.
2. The bureau is queried against the verified identity.
3. The report is attached to the application.

What it returns

• Score and score factors
• Tradelines and balances
• Inquiries and public records

At a glance

Provider

TransUnion / Equifax · Experian coming soon

Billing

Per completed step

Requires first

Identity verification

This step normally requires identity verification first. Soft or hard pull depends on your bureau agreement.

How it works

1. The verified name and date of birth are submitted for search.
2. Jurisdictional sources are queried.
3. Findings are returned with source and date.

What it returns

• Matches with offence, jurisdiction, and date
• A clear result where nothing is found

At a glance

Provider

Fastkey / Checkr

Billing

Per completed step

Requires first

Identity verification

Turnaround is usually seconds but can take minutes where a manual court search is required.

How it works

1. The verified identity is searched against court and tribunal sources.
2. Filings are matched and returned with case references.

What it returns

• Court filings and dispositions
• Tenancy tribunal history, including eviction filings
• Case numbers and dates

At a glance

Provider

OpenRoom / SOQUIJ / TAL / Checkr

Billing

Per completed step

Requires first

Identity verification

Coverage varies by province. Quebec results come from SOQUIJ and the TAL.

How it works

1. Upload or select the document template in the Portal.
2. The applicant reviews and signs on their phone.
3. The executed copy is stored with the application.

What it returns

• The signed PDF
• Signer identity, timestamp, and IP
• Audit trail of views and actions

At a glance

Provider

PandaDoc

Billing

Per completed step

Signed documents are included in the PDF export of the application.

How it works

1. Configure what you are asking for and whether it is required.
2. The applicant uploads a file or types an answer in the flow.

What it returns

• Uploaded files, stored as signed URLs
• Typed answers as structured fields

At a glance

Provider

Carousel

Billing

Per completed step

Useful for a void cheque, a letter of employment, or a photo of an asset.

How it works

1. The amount is configured on the step.
2. The applicant pays by card in the flow.
3. The receipt is attached to the application.

What it returns

• Payment status and amount
• Stripe payment reference
• Receipt for the applicant

At a glance

Provider

Stripe

Billing

Per completed step

In an applicant-paid workflow this step prepays every verification in the flow. Refunds are handled per Request a refund.

How it works

1. The applicant enters the legal entity details.
2. Registries are queried for standing and ownership.
3. Beneficial owners can be pushed through identity verification.

What it returns

• Legal name, number, and jurisdiction
• Registration status and incorporation date
• Directors and beneficial owners

At a glance

Provider

Carousel

Billing

Per completed step

Pair with identity verification on the signing officer for a complete file.

How it works

1. Alternative data sources are queried where bureau history is limited.
2. A usable creditworthiness picture is assembled from what exists.

What it returns

• Alternative score or risk band
• Contributing data sources

At a glance

Provider

Carousel

Billing

Per completed step

Most useful for newcomers, students, and applicants without a Canadian bureau history.

How it works

1. The verified identity is screened against sanctions and AML watchlists.
2. Any hits are returned with the list and match confidence.

What it returns

• Watchlist matches with source and confidence
• PEP status
• A clear result where nothing is found

At a glance

Provider

Sanction Scanner

Billing

Per completed step

Requires first

Identity verification

The result and its timestamp are recorded for audit.

How it works

1. Build the question set in the Portal.
2. Add conditions so later questions depend on earlier answers.
3. Answers arrive as fields on the application.

What it returns

• Question id, text, and answer for every question
• Branch taken, where conditions applied

At a glance

Provider

Carousel built-in

Billing

Per completed step

Answers appear in the webhook payload under the Custom Questionnaire step.

How it works

1. Define the statement the applicant must attest to.
2. The applicant accepts it in the flow.

What it returns

• The statement text as presented
• Acceptance, timestamp, and IP

At a glance

Provider

Carousel

Billing

Per completed step

Use where a formal signature is unnecessary but a record is required.

Carousel replaces the patchwork of PDF forms, email attachments, and vendor portals with a single applicant-facing flow. Your team assembles the steps; Carousel handles the verification, the applicant experience, and the delivery of a finished file.

What changes for your team

• Files arrive complete — identity, income, records, and signatures already verified.
• Nothing is re-keyed. Every result is structured data, not an attachment.
• Reviewers spend their time on decisions instead of chasing documents.

The two sides

For your team is the Portal — building workflows and reviewing what comes back. For applicants is the flow itself, on their phone. This guide covers the first; see For applicants for the second.

Carousel PortalWorkflows — view, create, share, preview, and disable every flow.

Three areas

1. Workflows — build, preview, share, and disable every flow.
2. Applications — the shared queue of everything applicants have submitted.
3. Settings — branding, team access, and integrations.

Getting around

• The icon rail on the left switches areas.
• Search finds an applicant by name, phone, or application ID.
• Filters narrow the queue by workflow, stage, status, or assignee.

Carousel PortalThe drag-and-drop workflow builder — Available Tools on the left, your flow on the right.

Build it in the Portal

1. Log in to the Carousel Portal.
2. Navigate to Dashboard → Workflows → Create New Workflow.
3. Use the drag-and-drop builder to assemble your flow from the available steps.
4. Customize and white-label the workflow — branding, copy, and step order.

Choose what each step requires

Every step can be marked as requiring manual approval before the flow continues, or left to complete automatically. Some steps have prerequisites — a credit check, for example, requires identity verification first.

Decide who pays

A workflow is either business-paid, where you cover the verification costs, or applicant-paid, where the applicant prepays and owns their verified profile. See Pricing and usage.

What you can include

A workflow is assembled from the steps below. Mix and match whatever your application needs — each step links to more detail.

Send the results onward

Add a CRM Integration step at the end to post the finished file to your own system as JSON. See the Webhook guide.

Carousel PortalWorkflows — view, create, share, preview, and disable every flow.

The Workflows list shows each flow you have built, whether it is active, and how many applications it has produced.

What you can do from the list

• Preview — walk through the flow exactly as an applicant would.
• Share — copy the link or grab the embed code.
• Duplicate — spin up a variant without rebuilding it.
• Disable — stop accepting new applications without deleting history.

Carousel PortalThe share dialog — general link, personal share link, tenancy link, and default language.

Three ways to share

1. General link — one URL for everyone; best for a website button or campaign.
2. Share link — attributed to a specific team member, so submissions arrive assigned.
3. Embed — the flow inside a page on your own site.

Direct links are recommended over embedding. See Direct link or embed for the tradeoffs and code.

Language

Each workflow has a default language (EN or FR). Applicants can switch, but the link opens in the default you set.

Carousel PortalManage All Applications — every submission across every workflow.

Applications lists every submission across every workflow, newest first.

Columns

• Name and phone number of the applicant.
• Stage — the step-by-step progress icons.
• Assignee — who owns the file.
• Lead origin — which link or workflow it came from.
• Last updated and Status.

Finding a file

Search by name, phone, or application ID; filter by workflow, stage, status, or assignee. See Stages & statuses for how to read each row.

Statuses

• In progress — the applicant has started but not finished.
• Completed — every required step is done; the file is ready to review.
• Processing — a provider is still returning a result.
• Timed out — a step took too long and can be reprocessed.
• Cancelled — the application was abandoned or withdrawn.

Stage icons

Each row shows one icon per step in the workflow, in order. A filled icon means the step completed; an outlined icon means it has not run yet.

Carousel PortalA submission in review — every step, verification output, and document in one place.

Open any submission to see each step’s result in the order the applicant completed it, with the underlying documents attached. There are no tabs to reconcile and nothing to download separately.

What a reviewer sees

• Verified identity fields, with the ID images.
• Bank-linked income and transaction insight.
• Credit, background, and court results where configured.
• Signed documents and questionnaire answers.

Acting on it

Approve, decline, or request more information. Where a step needed manual approval, the decision is recorded against that step. Export the file with Export as PDF.

Carousel PortalThe application ⋮ menu — Export as PDF sits here.

Any completed submission exports as a single PDF containing every verified result and document, suitable for a credit file, an investor, or an audit.

What the export includes

• A cover summary of the applicant and workflow.
• Each step’s result in order, with timestamps.
• Attached documents and signatures.

Invite someone

1. Open Settings → Team.
2. Click Add Team Member and enter their work email.
3. Assign a role, then send the invite.

Roles

• Admin — full access, including billing and integrations.
• Reviewer — sees the queue and reviews submissions.
• Builder — creates and edits workflows.

Access is enforced per workspace with role-based access control and token-based authentication. See the Developer FAQ for the security detail.

Workflows

Can I change a workflow after it is live? Yes. Edits apply to new applications; in-flight ones keep the version they started.

Can I preview a flow before sharing it? Yes — preview walks through it exactly as an applicant would see it.

Access

Can two teams share a workspace? Yes, with roles scoped per member.

Can I restrict who sees submissions? Yes — reviewers only see the queue, not billing or integrations.

Branding

Can I white-label the flow? Yes — your logo and brand colours on the applicant experience.

A business sends you a link. You verify what is being asked for — your identity, your banking information, a signature — and submit. Each step happens in a secure window, and the business receives only the result they requested.

What it takes

• About eleven minutes for a typical application.
• A phone with a camera for identity verification.
• Your online banking login, if financial verification is included.

You can pause and return using the same link. See Complete an application.

Verifying at the source means you do not have to gather statements, scan documents, or email anything. It also means the business can decide faster, because nothing has to be checked by hand afterwards.

What is shared

• Only the results the business asked for — not your banking credentials.
• Documents you upload, and the fields read from your ID.
• Nothing else from your accounts.

Step by step

1. Open the link on your phone.
2. Enter your phone number to start or resume.
3. Complete each step — the flow tells you exactly what it needs.
4. Review and submit.

If something goes wrong

• ID photo rejected — retake it in even light, no glare, all four corners visible.
• Bank not listed — upload statements instead where the business allows it.
• Interrupted — reopen the same link; your progress is saved.

Your completed file goes to the business that requested it. If a step is still processing, it finishes on its own — you do not need to do anything else.

Timing

• Most steps return in seconds.
• Credit and record checks can take a few minutes.
• The business decides on its own timeline; Carousel does not make the decision.

In an applicant-paid workflow you prepay for the verifications, own the resulting profile, and choose who sees it.

What you control

• Share the profile with the business that asked, or with another one.
• Track progress of each step as it completes.
• Request a refund if there are issues — see Request a refund.

1. Option A: Direct Link (Recommended)

• Carousel provides you with a unique WORKFLOW URL after you create a workflow on the Carousel Portal.
• Share this link with your applicants (e.g., via email, SMS, or your website).
• Example: https://apply.oncarousel.com/v2/application?domain=https%3A%2F%2Facmeinc.com&lead=

This launches the workflow as a standalone, full-page interface — similar to Stripe Checkout. It’s optimized for speed, branding, and mobile responsiveness.

Why we recommend this approach:

• Mobile-optimized, distraction-free
• No layout constraints
• Easier to track completions and drop-offs
• Fully configurable from within the Portal — no developer support needed

2. Option B: Embed via iFrame

You can embed the Carousel POS directly into your website using an <iframe>.

Example Code

<iframe 
  src="https://apply.oncarousel.com/v2/application?domain=acme.ca" 
  width="100%" 
  height="800" 
  style="border:none;">
</iframe>

Important Disclosure on iframes

While iframe embedding is supported, it limits layout control and may degrade the applicant experience — especially on mobile.

Carousel workflows are designed to be used as a dedicated, full-page interface, and perform best when launched via direct link.

3. Customization

• Additional query parameters may be supported (contact support if needed).

4. Testing

• Add the link or iframe to your test environment.
• Submit a test application.
• Confirm the application appears in your Portal → Manage All Applications.

5. Security Notes

• Always use HTTPS when embedding or sharing the workflow link.
• Do not expose internal system URLs in the iframe.

Carousel PortalA workflow with a CRM Integration step added at the end.

Creating a Workflow with CRM Integration

Carousel lets you collect and verify applicant data using configurable, step-based workflows. You can customize, configure and white-label each workflow directly from the Portal — no code needed.

How to Set It Up

1. Log in to the Carousel Portal
2. Navigate to: Dashboard → Workflows → Create New Workflow
3. Use the drag-and-drop builder to build your flow
4. Add a CRM Integration step at the end

Configuring the CRM Integration Step

The CRM Integration step automatically sends collected applicant data to your system using a secure POST request.

Setup Instructions

1. Set Export Destination to Webhook
2. Enter your POST URL (the endpoint on your system)
3. Click Confirm to save

Once the applicant reaches this step, Carousel will send the workflow data as structured JSON.

Webhook Events

Carousel will automatically send webhook events to your configured POST URL as the applicant progresses through the workflow. There are three main events:

1. Application Created

Triggered when an applicant first creates an application (logs in with phone number).

Sample Payload

{
  "loanApplicationId": "28b25f25-43b7-4871-ab47-239faaefbe10",
  "phoneNumber": "+1 (605) 555-5555",
	"apiUrl": "https://yourwebhook.com",
  "createdAt": "2025-08-14T20:52:22.589Z",
	"externalCustomerId":"your_customer_id",
  "system": {
    "step": "Loan Product",
    "status": "Initializing",
    "updatedAt": "2025-08-14T20:52:21.233Z"
  },
  "application": {
    "status": "In Progress",
    "updatedAt": "2025-08-14T20:52:21.233Z"
  },
  "updatedAt": "2025-08-14T20:52:22.589Z"
}

2. Application Finished All Steps

Triggered when the applicant finishes all required steps.

{
	"loanApplicationId": "20ca981e-b94d-426a-a74a-9e17f315c7fc",
  "phoneNumber": "+1 (605) 555-5555",
	"apiUrl": "https://yourwebhook.com",
  "createdAt": "2025-08-14T20:52:22.589Z",
  "externalCustomerId":"your_customer_id",
	"system": {
    "step": "Loan Product",
    "status": "Initializing",
    "updatedAt": "2025-08-14T20:52:21.233Z"
  },
	"application": {
		"status": "Completed",
		"updatedAt": "2025-08-14T20:52:21.233Z"
	},
	"dataStep": [
		{
			"step": "Loan Product",
			"data": {
				"id": "4361048b-5a52-46e6-ade6-a923ce39bb71",
				"calculatorConfig": {
					"upfrontFee": 0,
					"originationFee": 0,
					"brokerageFeePercent": 0
				},
				"calculatorType": 0,
				"annualInterest": 5,
				"minimumLoanAmount": 500,
				"name": "cll",
				"amount": 500,
				"assignments": [],
				"applicationDate": "2025-02-17T16:08:00.304Z",
				"approvalDate": "2025-02-17T16:10:09.001Z",
				"businessId": "e35cba52-a7f3-53c1-a47c-e539aa26d681",
				"externalCustomerId": null,
				"detailsOnUseOfFunds": null,
				"purposes": ["Inventory"],
				"urgencyOfFunds": null
			}
		},
		{
			"step": "Identity",
			"data": {
				"gender": "Male",
				"dateOfIssue": "2024-10-10T00:00:00.000Z",
				"fullName": "JOHN DOE",
				"country": "CAN",
				"dateOfBirth": "1998-03-08T00:00:00.000Z",
				"dateOfExpiration": "2027-06-30T00:00:00.000Z",
				"documentNumber": "H0653-00009-80308",
				"province": "ON",
				"frontImageUrl": "https://cdn.example.com/uploads/kyc/EXAMPLE-FILE"
			}
		},
		{
			"step": "Bank Account",
			"data": {
				"loginId": "6433cf6a-0879-4ef0-5a2a-08d91642f9c6",
				"bankAccount": [] // This step is still processing so no bank accounts were saved 
			}
		},
		{
			"step": "Custom Questionnaire",
			"data": {
				"questions": [
					{
						"id": "5bbb1eb4-57c3-4c0c-aa08-b1a4a29eab85",
						"name": "What is the full legal name of your company ?",
						"answer": "Spheregbs"
					},
					{
						"id": "5f3edc6e-6247-47f1-8a15-be6c271b8788",
						"name": "Would you like for the lease to be under your company or personal ?",
						"answer": "Company"
					},
					{
						"id": "2de688e5-3ae1-46bb-b587-669f2168652d",
						"name": "Address from where vehicle will operate?",
						"answer": ""
					}
				]
			}
		}
	],
	"updatedAt": "2025-07-22T15:55:23.986Z"
}

3. Full Payload — Every Step

A complete example with every step type present, including financial accounts, questionnaire answers, e-signature, credit, background, court and self-declaration data.

{
  "loanApplicationId": "dc8ef61b-35a2-4634-88d8-38e637abb2c4",
  "phoneNumber": "+1 (500) 555-0006",
  "apiUrl": "https://yourwebhook.example.com/endpoint",
  "createdAt": "2026-04-10T16:30:32.649Z",
  "externalCustomerId": "",
  "system": {
    "status": [
      {
        "step": "Loan Request",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Applicant Payment",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Financial Verification",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "E-Signature",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "CRM Integration",
        "statuses": [
          "Completed"
        ]
      },
      {
        "step": "Credit Check",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Identity Verification",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Custom Questionnaire",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Self Declaration",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Background Check",
        "statuses": [
          "Approved"
        ]
      },
      {
        "step": "Court & Eviction Checks",
        "statuses": [
          "Approved"
        ]
      }
    ],
    "updatedAt": "2026-04-10T16:30:32.013Z"
  },
  "application": {
    "status": "In Progress",
    "updatedAt": "2026-04-10T16:30:32.013Z"
  },
  "dataStep": [
    {
      "step": "Loan Request",
      "data": {
        "id": "35827328-61cc-47c4-b5c9-809c6630784a",
        "annualInterest": 100,
        "calculatorConfig": {
          "upfrontFee": 0,
          "originationFee": 0,
          "brokerageFeePercent": 0
        },
        "calculatorType": "Installment",
        "minimumLoanAmount": 100,
        "applicationDate": "2026-04-10T15:44:27.955Z",
        "approvalDate": "",
        "businessId": "9956134d-c746-57e6-8a7e-0be300dfe5c7",
        "detailsOnUseOfFunds": "",
        "externalCustomerId": "",
        "purposes": [],
        "urgencyOfFunds": "",
        "name": "Full",
        "amount": "200.00",
        "assignments": [
          {
            "fullName": "",
            "email": "",
            "phoneNumber": "",
            "id": ""
          }
        ]
      }
    },
    {
      "step": "Identity Verification",
      "data": {
        "gender": "Male",
        "dateOfIssue": "2012-11-30T00:00:00.000Z",
        "fullName": "TEST CARD SAMPLE",
        "country": "CAN",
        "dateOfBirth": "1982-01-04T00:00:00.000Z",
        "dateOfExpiration": "2017-11-30T00:00:00.000Z",
        "documentNumber": "2222222",
        "documentType": 3,
        "province": "BC",
        "frontImageUrl": "https://cdn.example.com/uploads/kyc/EXAMPLE-FILE",
        "address": "910 GOVERNMENT ST, VICTORIA BC V8W 3Y8"
      }
    },
    {
      "step": "Financial Verification",
      "data": {
        "loginId": "f4847c89-9d93-4e1f-1544-08ddf53a0c5c",
        "bankAccount": [
          {
            "accountTitle": "Chequing CAD",
            "accountNumber": "1111000",
            "institutionNumber": "777",
            "institutionName": "FlinksCapital",
            "transitNumber": "77777",
            "category": "Operations",
            "type": "Chequing",
            "currency": "CAD",
            "balanceAvailable": 50300,
            "balanceCurrent": 50000,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "First Home Savings Account",
            "accountNumber": "FHSA1234567",
            "institutionNumber": "",
            "institutionName": "FlinksCapital",
            "transitNumber": "",
            "category": "Products",
            "type": "FHSA",
            "currency": "CAD",
            "balanceAvailable": 0,
            "balanceCurrent": 200000,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Plaid Saving",
            "accountNumber": "1111",
            "institutionNumber": "",
            "institutionName": "RBC Royal Bank",
            "transitNumber": "",
            "category": "other",
            "type": "depository",
            "currency": "CAD",
            "balanceAvailable": 200,
            "balanceCurrent": 210,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "Alberta Bobbeth Charleson",
              "email": "accountholder0@example.com",
              "phoneNumber": "1112223333",
              "address": {
                "address": "478 Plaid Street",
                "city": "Gingham",
                "province": "AB",
                "zipCode": "T0B 0Z0",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Credit card",
            "accountNumber": "420024******4242",
            "institutionNumber": "",
            "institutionName": "FlinksCapital",
            "transitNumber": "",
            "category": "Credits",
            "type": "CreditCard",
            "currency": "CAD",
            "balanceAvailable": 20000,
            "balanceCurrent": 10000,
            "balanceLimit": 30000,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Line of Credit",
            "accountNumber": "LC010101",
            "institutionNumber": "",
            "institutionName": "FlinksCapital",
            "transitNumber": "",
            "category": "Credits",
            "type": "LineOfCredit",
            "currency": "CAD",
            "balanceAvailable": 6000,
            "balanceCurrent": 3000,
            "balanceLimit": 9000,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Investments",
            "accountNumber": "INV00001",
            "institutionNumber": "",
            "institutionName": "FlinksCapital",
            "transitNumber": "",
            "category": "Products",
            "type": "RRSP",
            "currency": "CAD",
            "balanceAvailable": 0,
            "balanceCurrent": 100000,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Plaid Cash Management",
            "accountNumber": "9002",
            "institutionNumber": "",
            "institutionName": "RBC Royal Bank",
            "transitNumber": "",
            "category": "other",
            "type": "depository",
            "currency": "CAD",
            "balanceAvailable": 12060,
            "balanceCurrent": 12060,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "Alberta Bobbeth Charleson",
              "email": "accountholder0@example.com",
              "phoneNumber": "1112223333",
              "address": {
                "address": "478 Plaid Street",
                "city": "Gingham",
                "province": "AB",
                "zipCode": "T0B 0Z0",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Chequing US",
            "accountNumber": "1111001",
            "institutionNumber": "777",
            "institutionName": "FlinksCapital",
            "transitNumber": "77777",
            "category": "Operations",
            "type": "Chequing",
            "currency": "USD",
            "balanceAvailable": 25300,
            "balanceCurrent": 25000,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Plaid Checking",
            "accountNumber": "0000",
            "institutionNumber": "",
            "institutionName": "RBC Royal Bank",
            "transitNumber": "",
            "category": "checking",
            "type": "depository",
            "currency": "CAD",
            "balanceAvailable": 100,
            "balanceCurrent": 110,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "Alberta Bobbeth Charleson",
              "email": "accountholder0@example.com",
              "phoneNumber": "1112223333",
              "address": {
                "address": "478 Plaid Street",
                "city": "Gingham",
                "province": "AB",
                "zipCode": "T0B 0Z0",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Another Business Account",
            "accountNumber": "BA777",
            "institutionNumber": "777",
            "institutionName": "FlinksCapital",
            "transitNumber": "77777",
            "category": "Credits",
            "type": "Chequing",
            "currency": "CAD",
            "balanceAvailable": 84,
            "balanceCurrent": 42,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "Mo'e Money Inc.",
              "email": "biz@flinks.com",
              "phoneNumber": "514-123-4567",
              "address": {
                "address": "1000 de la Gaucheti\ufffdre",
                "city": "Montreal",
                "province": "QC",
                "zipCode": "A1A 1A1",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Personal loan",
            "accountNumber": "LO020202",
            "institutionNumber": "",
            "institutionName": "FlinksCapital",
            "transitNumber": "",
            "category": "Credits",
            "type": "LoanPersonal",
            "currency": "CAD",
            "balanceAvailable": 0,
            "balanceCurrent": 200000,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "John Doe",
              "email": "johndoe@flinks.io",
              "phoneNumber": "(514) 333-7777",
              "address": {
                "address": "1275 avenue des Canadiens-de-Montréal",
                "city": "Montréal",
                "province": "QC",
                "zipCode": "H3B 5E8",
                "country": "CA"
              }
            }
          },
          {
            "accountTitle": "Business Account",
            "accountNumber": "BA-12345",
            "institutionNumber": "777",
            "institutionName": "FlinksCapital",
            "transitNumber": "77777",
            "category": "Operations",
            "type": "Unknown",
            "currency": "CAD",
            "balanceAvailable": 0,
            "balanceCurrent": 1000000,
            "balanceLimit": 0,
            "overdraftLimit": 0,
            "holder": {
              "fullname": "Very Successful Inc.",
              "email": "success@flinks.com",
              "phoneNumber": "514-777-7777",
              "address": {
                "address": "123 Moon Dr.",
                "city": "Golden City",
                "province": "QC",
                "zipCode": "H0H 0H0",
                "country": "CA"
              }
            }
          }
        ]
      }
    },
    {
      "step": "Custom Questionnaire",
      "data": {
        "questions": [
          {
            "id": "f913043a-c667-41c2-8dcc-b7ffe8bbb301",
            "name": "What is your phone number - Email?",
            "answer": "123"
          }
        ]
      }
    },
    {
      "step": "E-Signature",
      "data": {
        "documentId": "44MMZgzKoH7nMeRMLjR7mL",
        "document": "https://cdn.example.com/uploads/legal-contract/EXAMPLE-FILE"
      }
    },
    {
      "step": "Credit Check",
      "data": "https://cdn.example.com/uploads/credit-check/EXAMPLE-FILE"
    },
    {
      "step": "Background Check",
      "data": {
        "criminalChecks": {
          "reportId": "69d924ca4658d28470210cd5",
          "status": "Incomplete",
          "serviceType": "STANDARD_CRIMINAL_RECORD_CHECK",
          "standardResult": "Incomplete",
          "submittedAt": null,
          "completedAt": "2026-04-10T16:30:30.764Z",
          "info": {
            "birthCity": "111",
            "birthCountry": "111",
            "birthProvince": "111",
            "dateOfBirth": "1982-01-04T00:00:00.000Z",
            "email": "admin@oncarousel.com",
            "firstName": "TEST CARD",
            "lastName": "SAMPLE",
            "phone": "+15005550006",
            "gender": "Male"
          },
          "addressHistory": [
            {
              "address": "910 GOVERNMENT ST",
              "city": null,
              "country": "CAN",
              "province": "BC",
              "zipCode": null
            }
          ],
          "verification": {
            "passed": true,
            "verifiedAt": "2026-04-10T16:26:51.532Z"
          },
          "convictions": [],
          "pdfs": [
            {
              "note": "This is a test document - not a real criminal check result",
              "label": "Standard Criminal Record Check (TEST)",
              "docRefId": "test_doc_1775838416763",
              "pdfUrl": "https://cdn.example.com/uploads/criminal-check/EXAMPLE-FILE",
              "isSecure": true
            }
          ]
        }
      }
    },
    {
      "step": "Court & Eviction Checks",
      "data": {
        "legalChecks": [
          {
            "status": "Completed",
            "reporter": "Openroom Sandbox",
            "isMatch": true,
            "message": "Cleared, no matching court records found in available databases",
            "items": [
              {
                "url": "https://openroom.ca/dashboard/document/19b33f3e-dceb-4a81-9fcc-6e81f29ec771",
                "title": "OR-SANDBOX-4: Filed by landlord on 2022-05-05",
                "name": "Dama Ging",
                "address": "BASEMENT, 13 DEBTOR DRIVE, OSHAWA, B2B2B2"
              }
            ]
          }
        ]
      }
    },
    {
      "step": "Self Declaration",
      "data": {
        "monthlyIncomeAmount": 13300,
        "employmentStatusDetail": {
          "status": "Employed Full Time",
          "position": "123",
          "startDate": "2026-04-10",
          "companyName": "123",
          "employerEmail": "123@gmail.com",
          "employerFullName": "123",
          "employerPhoneNumber": "+15555555555"
        },
        "lifestyleInformation": [
          "I vape or smoke",
          "I own pets",
          "I have a criminal background"
        ],
        "livingStatusDetail": {
          "status": "Other",
          "detail": "2323232"
        }
      }
    }
  ],
  "updatedAt": "2026-04-10T16:30:32.649Z"
}

Important: Document & Image Handling (S3 Links)

Carousel no longer sends documents or images as base64 in webhook payloads. Instead, file fields (for example frontImageUrl) contain a temporary, pre-signed Amazon S3 URL.

How It Works

• The URL points to a file stored in Carousel’s Amazon S3 bucket
• The URL is publicly accessible but expires after 15 minutes
• After expiration, the link will no longer be valid

Required Action (Recommended)

When your system receives a webhook containing file URLs:

1. Immediately download the file from the S3 URL
2. Store it securely in your own system or storage provider
3. Do not rely on the URL for long-term access

Webhook Failure & Retry

If your webhook endpoint is unavailable, times out, or fails to process the payload (for example due to expired file links), you can manually re-trigger the webhook.

Retry from the Portal

1. Log in to the Carousel Portal
2. Open the relevant Application
3. Navigate to the Webhook section
4. Click Re-send Webhook

This will send the latest available payload again, including fresh S3 URLs for any files.

Carousel PortalThe application ⋮ menu — re-deliver the payload from here.

Support

Need help with:

• Configuring workflows
• Webhook setup
• Payload troubleshooting
• POS launch methods

We’re here to help: Speak to Support

Overview

Carousel charges per billable step — there are no platform fees beyond the steps applicants actually complete.

A billable step is any verification an applicant completes in a workflow — identity, KYB, financial, credit, background, court & eviction, fraud & compliance screening, e-signature, or payment. Only completed steps are charged.

Who Pays: Applicant or Business

Every workflow can be configured with one of two payment structures:

• Business pays — your business covers the verification costs and applicants complete the workflow at no charge. Results are delivered to your business as part of the application.
• Applicant pays — the applicant prepays for all the verifications they are about to undergo. They own their verified profile, choose whether to share it with the requester — or with others — and can request a refund if there are issues with their workflow.

When Charges Happen

A charge occurs when an applicant completes a billable step in your workflow — nothing is charged before that.

• Completed steps — charged at the step’s fee.
• Abandoned steps — never charged, if the applicant never reached them.
• Failed steps — charged: the step ran.
• Applicant-paid workflows — the applicant prepays for all the verifications in the workflow; if there are issues, they can request a refund.
• Invoices — itemized by billable step.

Fees by Billable Step

All Billable Steps Supported by Carousel

Example Workflow and Total Cost

Let’s say your workflow includes:

1. Identity Verification
2. Financial Verification
3. Credit Check
4. E-Signature
5. Applicant Payment

If an applicant completes every step, here’s what you’re charged:

FAQ

About Carousel

Integrations & Workflow Setup

Pricing & Billing

Security & Compliance

Additional questions? Speak to Support

Start here for anything account-related. If you cannot find an answer, contact the team — we reply within one business day.

For applicants

• How Carousel works — what to expect end to end.
• The verification fee — why it exists and what it covers.
• Request a refund — how and when to ask.

For account holders

• Invoices are itemized by billable step — see Pricing and usage.
• Team access and roles are covered in Add your team.

Reaching a person

In an applicant-paid workflow, the applicant prepays for the verifications in that workflow. The fee covers every step in the flow — nothing else is billed to the applicant afterwards.

What it covers

• Each verification step configured in the workflow.
• The verified profile the applicant keeps and can share.
• Re-sharing that profile with another business at no extra charge.

When it is charged

• Once, upfront, before the verifications run.
• Steps that never complete are refundable — see Request a refund.

How to request one

1. Reopen the link you used to apply.
2. Choose Request a refund, or write to support@oncarousel.com with your phone number and the business you applied to.
3. You will get confirmation the same business day.

When a refund applies

• A step failed or could not complete.
• The workflow was duplicated or charged twice.
• A verification returned nothing usable through no fault of yours.

Timing

Approved refunds return to the original payment method, typically within 5–10 business days.

Timing

How long does a refund take? Typically 5–10 business days back to the original method.

Can I check the status? Yes — reply to your confirmation email and support will confirm where it is.

Amount

Can I get a partial refund? Yes, where only some steps failed.

Do completed verifications get refunded? No — those results stay in your profile and remain shareable.

Contact

Who do I contact? support@oncarousel.com, or +1 (855) 508-8989 for anything urgent.

Carousel is where you send tenant screenings and read the reports. The applicant completes the checks through a personal link you send them.

How it works

What it is not

• A workflow builder. You pick a package, or a custom workflow Carousel’s team set up for your business. See Packages and custom workflows.
• A tool for other industries. Carousel screens tenants. The composer lists other industries, and picking one points you to book a call with Carousel’s team.

Carousel runs every check on its own platform. The names here are the ones Carousel uses.

When the applicant pays, Carousel collects the fee in its own payment step: see Applicant payment. For which checks each package includes, see Packages and custom workflows.

You send a screening to one person. Carousel runs the checks with them, and the results come back to you as a report.

The two sides

For you: send a screening, follow its progress, read the report and download the PDF. For the applicant, Carousel’s own application flow: they open their personal link and complete the checks you chose. This guide covers the first; see For applicants for the second.

Signing in

• Press Sign in or Sign up on the Carousel app’s home page. Both continue with Google.
• Google asks which account to use each time, so you can choose between a work and a personal account.
• Your first sign-in creates your account.

Try it before you sign up

You don’t need an account to start. The home page asks “Who do you want to screen?” Type the applicant’s email or phone number and choose who pays. To change the checks, or when you press send, you’re asked to sign in with Google, and you come back to the screening you wrote. It isn’t sent until you review it.

Your account

• Your first workspace, My Workspace, is ready the first time you open home.
• If you signed up on your own, not through a teammate’s invitation, a short welcome sheet opens that first time. It asks what you’ll screen for and whether you work alone or with a team. Teammates you invite from it start on View only; you can change that for each one. At the end, Show me around starts a short tour; Explore on my own skips it.
• In Settings, set your business name. Applicants see it: the invitation email names it.
• Your account menu, at the top right, holds Settings, Usage & billing and Sign out.

The header

• The Carousel mark takes you home.
• The workspace switcher, beside it, lists your workspaces and the ones shared with you, with Manage workspaces and New workspace.
• Your token balance and Buy tokens.
• Your account menu: Settings, Usage & billing and Sign out.

Home

1. Invitations to join a workspace, when one is waiting.
2. The composer: type an applicant’s email or phone number to start a screening. See Send a screening.
3. Your applications. See Your applications.

Other pages

• Each workspace and each building has its own page, with its own applications.
• Settings: your business name, report emails and billing.

Finding a file

• Search applications matches the applicant, the property, the stage and the assignee.
• Open or All. Open, the default, hides cancelled and expired screenings.
• Sort: Newest first, Needs action first, Furthest along or Oldest first.
• By group or Flat: grouped by building, or one list.

Step by step

On the review sheet

• The package. Open the menu to change it, or to pick one of your custom workflows.
• What’s included. Tap a check to add or remove it. The package switches to the closest match, and the sheet says which.
• Saves to. The workspace and building the application files under. A unit is optional. Unlisted folder files it in the workspace with no building.
• Who pays. Applicant or You, or Workspace when the tokens are a workspace owner’s.
• + Add a co-applicant. Screen more than one person in the same send. See Co-applicants and occupants.

What stops a send

A badge above the package says Ready to send, or names what’s in the way:

• Add a recipient: there’s no email or phone number yet.
• Quebec or elsewhere?: a court check needs to know whether the property is in Quebec. Answer Quebec or Elsewhere in Canada. See Workspaces, buildings and units.
• Not available yet: the package isn’t set up in Carousel yet. When another package is ready, the sheet offers to switch.
• Low balance: you’re paying and your balance doesn’t cover the screening. Buy tokens is right there.

Paying

• When you pay, your balance must cover the whole screening before it sends. Tokens are charged per check, as Carousel completes each one. See Tokens and billing.
• When the applicant pays, the sheet reads Free for you. The applicant pays at checkout, in Carousel’s flow.

Packages

Each package is a set of checks. Prices show in Carousel before you send.

A package costs the sum of its checks. In Quebec the court checks are the two SOQUIJ searches, so the same package can be priced differently there. See Court & eviction checks.

A package tagged Not set up in the package menu can’t be sent yet. When another package is ready, the review sheet offers to switch.

Custom workflows

• Carousel can build a workflow for your business and make it available in one of your workspaces, or across your account. When you send there, it appears in the package menu under Custom workflows.
• Its checks, and who pays, are fixed by how it was built. The sheet says so: “This workflow’s payment mode is fixed by how it was built in Carousel.”
• Carousel can also make one of its workflows available in every tenant-screening workspace.

One link per applicant

Each send creates a link for one applicant and one application. It isn’t a link to post or pass around: a co-applicant gets a link of their own.

How it reaches them

• Email invite. Carousel emails the link. The email carries your business name: “Sent via Carousel on behalf of” your business. If the applicant replies, the reply goes to whoever started the application in Carousel.
• Text invite. Carousel doesn’t send texts. It gives you the link to text yourself.
• Either way, the link shows once you’ve sent, with a copy button. If an email doesn’t go through, Carousel says so, and the link still works.

To get the link again later, open the application’s row, then Checks, move, cancel, and press Refresh link. It reminds the applicant, then shows the link with Copy link. See Remind, cancel and expiry.

Where they complete it

On Carousel’s own application flow, as the articles For applicants describe.

The levels

• Workspace. Where you and your team work. Everyone starts with My Workspace; add more with New workspace in the workspace switcher.
• Group. A folder of buildings inside a workspace.
• Building. An address, with an optional monthly rent.
• Unit. Optional, with its own rent when it differs from the building’s.
• Unlisted folder. The catch-all in each workspace, for applications with no building.

Why the building matters

• Its province decides the court checks. Carousel uses the province saved on the building, or reads it from the address. If neither says, the review sheet asks: “Is this property in Quebec? The court checks differ there.” When you own the building, your answer is saved on it.
• Its rent is what the report weighs income against. A unit’s own rent comes first, then the building’s.

Adding and changing them

• Add a building or a group from + Add on a workspace’s list, or from Saves to while you send. A new building can take its units right away.
• To add many buildings at once, choose Add a new building under + Add, then Import a list. Drop in a CSV with the columns address, unit and rent: one row per unit, with the address repeated on each. Leave unit blank for a house. You see every building and unit before you import.
• The owner sets a building’s or a unit’s rent in place, on the list.
• Only the owner adds, renames or deletes buildings and groups, and deletes units. Anyone who can screen there can add a unit.
• The owner can drag a building or group by its header to change the order of the list.
• The owner renames or deletes a workspace in Manage workspaces. A workspace can’t be deleted while it still has buildings, groups or people shared into it, or while it’s your only one. Its applications move to Private; none are deleted.

Moving an application

Open an application’s row and use Move to file it under another building or unit. Or drag the row onto a building or unit on the list; on a phone, hold the row for a moment first.

More than one person in a send

On the review sheet, press + Add a co-applicant and add each person. Everyone gets the same set of checks. With more than one person, choose how they’re filed:

• “One shared application — co-applicants on the same file.”
• “Separate applications — one report each.”

Either way, each person is their own screening, with their own link and their own charges. A shared application shares the file, not the cost.

Adding someone later

From an application, Add a co-applicant or guarantor sends that person their own screening link. A guarantor is labelled apart from co-applicants.

Occupants

• An occupant lives there but isn’t screened. Add one under Also living there, in the application’s row.
• Adults the applicant lists on their self-declaration show up as occupants too, as suggested co-applicants.
• Screen, beside an occupant, sends them their own screening, charged like any other send. An occupant with no email needs one first.

Where the list appears

Under the composer on home, and on each workspace and building page. Group it By group, by building, or see it Flat. Search and filters are in Parts of Carousel.

Each row

• The applicant and the property.
• A state, and how many checks are done. See Statuses and stages.
• The stage you set, and who it’s assigned to.

Opening one

• Click the row to open the report, in any state: what has come back shows, and the rest says it isn’t completed yet. See Review a screening.
• The chevron opens the row in place: everyone on the application, each with their own state and Remind, and the team’s notes. Checks, move, cancel then shows the checks, Move, Refresh link and Cancel screening. Refresh link reminds the applicant, then shows the link with Copy link.

State, set by Carousel

• Not started: the applicant hasn’t started yet.
• Started: the applicant has started, and checks are still out.
• Complete: Carousel has completed every check. The report is ready.
• Cancelled: the screening was cancelled.
• Expired: the invitation ran out while it was still Not started.

Each row shows how many checks are done beside its state. Open, the list’s default, hides Cancelled and Expired.

Stage, set by you

Your own label for where you are with the file: Reviewing, Approved, Declined or Leased. Set it from Set stage on the row. The owner, and anyone who can screen in the workspace, can set it.

The owner can also add a stage of their own: choose + Custom stage at the bottom of the menu, name it, pick a colour and press Create. The file moves to the new stage, and the stage is shared with the workspace, so anyone who can screen there can pick it.

“Approved” is a stage you set. Carousel never shows an approve or reject decision.

Each check

In the report, each check shows what its provider returned: for example Verified, Report received, Clear or No record found.

Remind

• Remind sends the applicant the same link again. An emailed invitation is re-sent by email. Otherwise, hand the link over yourself: the row’s Refresh link shows it, with Copy link.
• You can remind while a screening is still open. If you reminded them recently, Carousel asks you to give them a little time: the same link still works.
• In the report, one Remind on the Overview covers everyone with steps left. In the list, each person has their own, and the row’s Refresh link does the same.

Cancel

• Cancel screening is in the application’s row. It stops charges for anything completed afterwards, and those later results aren’t shown.
• It doesn’t stop the applicant. There’s no way to take their link down from Carousel, so it keeps working.
• When you paid, the row then says how many tokens went back to your balance, and how many were already spent on completed checks.
• The owner, and anyone who can screen in the workspace, can cancel.

Expiry

An invitation nobody starts expires 30 days after it was sent. Its state reads Expired. Only unstarted screenings expire, and nothing is charged for checks that never complete. As with a cancel, the applicant’s link isn’t taken down, and nothing Carousel completes afterwards is charged or shown.

Click an application in your list and its report opens over the list; a direct link opens it as a page of its own. It opens in any state: what has come back shows, and the rest says it isn’t completed yet.

The tabs

• Overview. The applicant, the property and its rent, and the figures a landlord looks at first: rent to income, monthly income, credit score, payments on time, rent in the bank, and the court and police checks in a word. They’re figures, not a pass or fail.
• Checks. Every check, with what its provider returned. Open one for its detail, including documents such as the ID photos.
• PDF. Choose what prints, and download it. See The PDF report.

Also on the report

• Remind, on the Overview, for everyone with steps left.
• Notes: internal, on this file.
• Who the file is assigned to.
• ⟳ Refresh: pulls the latest from Carousel.
• The people on the file, and Add a co-applicant or guarantor.

No approve or decline

Carousel shows what each provider returned. It never shows an approve or reject decision, and there’s no approve, decline or request for more information. The decision is yours: record it as the file’s stage. See Statuses and stages.

Cancelled or expired

A cancelled or expired screening shows only the checks Carousel completed before it closed. Anything that finished later reads Not shown.

Open the report’s PDF tab. The controls sit beside a preview of the real pages.

Choosing what prints

• Start from a preset: Everything, Landlord standard or Identity + verdict only.
• Then switch sections, or parts of them, in or out, and move sections up or down.
• Your choices only take things out. They never add anything the report doesn’t already hold.
• Applicant payment is left out in every preset.

Getting it

Download the PDF saves it. Open the print view opens a page you can print.

Page one

Page one is the summary. A report printed before every check is back says so there: In progress, with how many checks are back.

Invite someone

1. On your workspace’s list, press Share. You can also use Manage workspaces, in the workspace switcher.
2. Under Invite by email, type their email and choose what they can do.
3. Press Add. They get an email, sign in with Google as that address, and choose Join workspace.

Or give them the workspace’s invite code, from Manage workspaces. They enter it under Join an existing workspace, on their home page while it has no applications yet, and join able to screen with your tokens. You can make a new code, or turn it off.

What each person can do

Who can do what

Managing people

• In the share panel, change what someone can do, or remove them.
• Anyone you’ve shared with can leave, from Manage workspaces.
• Workspaces others share with you are listed under Shared with you, in the workspace switcher.

The bell

Each workspace and building on your list has a bell. Choose one:

• First step completed: a heads-up the moment any check finishes.
• Each step completed: one email per completed check.
• When the report is ready: once every check is done.
• Muted: no emails for this property.

With nothing chosen, you get the report-ready email. A building’s choice wins over its workspace’s. A check counts as done when Carousel completes it.

Who gets them

These emails go to the account owner, and only while Email me when a report is ready is on in Settings.

Other emails

• Low balance: an email when your token balance runs low.
• Receipts: for token purchases and automatic top-ups.

Workflows

Can I build my own workflow? No. Pick a package, or use a custom workflow Carousel set up for your business.

Can I see a report before I send anything? Yes. Preview a sample report, on the review sheet, opens one on a fictional applicant.

Access

Can two teams work in one workspace? Yes: share it with them. See Share with your team.

Can I limit what someone can do? Yes. View only sees applications and reports, and never sends or spends tokens.

Can people I share with use my tokens? Only if you choose Can screen — may use your tokens. Can screen — their own tokens only leaves your balance alone.

Paying

Who pays for a screening? You choose on each send: you, with tokens, or the applicant, who pays Carousel in its own flow. A custom workflow’s payer is fixed. See Tokens and billing.

Invitations

Can Carousel text the invitation? No. Type a phone number instead of an email, and Carousel gives you the link to text yourself.

Branding

Can I brand what the applicant sees? The invitation email carries your business name. Carousel has no logo or brand settings.

Decisions

Does Carousel decide who to rent to? No. It shows what each provider returned, and never shows an approve or reject decision. The decision is yours: record it as the file’s stage.

How it works

1. On Carousel’s hosted flow, the applicant photographs their government ID and takes a short selfie video.
2. Carousel verifies the ID and returns what it reads from it.
3. Carousel pulls the result into your report.

What your report shows

• Document — its type and number, who issued it, and when it was issued and expires.
• Person on the ID — full name, date of birth and gender.
• Address — the address on the ID beside the one the applicant declared, and whether they match.
• The ID images and the selfie video.

Once the ID is verified, the check reads Verified, or ID expired if the document’s expiry date has passed. Until then it reads Not started or In progress. A finished step with nothing back reads No result.

At a glance

Packages

Every package

In the report

Identity verification

The selfie is shown, not judged: the report gives no separate selfie-match result.

How it works

1. The applicant completes the credit step on Carousel’s hosted flow.
2. Carousel gets their credit report from the bureau: TransUnion or Equifax.
3. Carousel pulls it into your report.

The credit check is a hard inquiry: it’s recorded on the applicant’s credit file.

What your report shows

• The score and its band, from Poor to Excellent.
• Payment history, balances and credit utilisation.
• Trade lines, enquiries, collections, legal items and bankruptcies.
• The names, addresses and employers the bureau has on file.
• The score factors: the bureau’s commentary, not findings.

When the report comes back, the check reads Report received, or Poor score when the score is in the Poor band. It reads No file found when the bureau has no file for the applicant.

At a glance

Provider

TransUnion or Equifax

Packages

Every package

In the report

Credit check

The Overview shows the credit score and payments on time.

How it works

1. Carousel looks at the building you send to: the province saved on it, or else what its address says.
2. If neither says, the review sheet asks Is this property in Quebec? The court checks differ there. Nothing sends until you answer. If the building is yours, the answer is saved on it, so you are not asked again.
3. When the applicant reaches the court step on Carousel’s hosted flow, the searches for that area run. Each one comes back into your report on its own.

The searches

In Quebec, the court & eviction search and the penal search go together: choosing one chooses both. Each is its own check.

What your report shows

• A search reads Clear when it found nothing, and only once the registry reports the search completed.
• Otherwise it counts what the search found: possible matches from OpenRoom, court files from SOQUIJ.
• Each possible match is listed with the filing’s details as the registry returned them. Each SOQUIJ file is listed with its file number and what it matched on.
• SOQUIJ files from courts other than the TAL aren’t tenancy cases. They’re listed apart, after the searches, under Other civil court files, and no search counts them.
• In Quebec, the penal search has its own row, Penal search, beside Court & eviction checks.

At a glance

Provider

OpenRoom · SOQUIJ in Quebec

Packages

Verified+, Verified Pro, Verified Max

In the report

Court & eviction checks · Penal search in Quebec

A search that stopped before it finished reads Didn’t finish; one whose report couldn’t be loaded reads Report not loaded. Older screenings may name the earlier combined check, Court & eviction records.

How it works

1. The applicant reaches the police check on Carousel’s hosted flow.
2. Carousel sends FastKey the name, date of birth and gender from identity verification, the applicant’s place of birth, and the ID document.
3. FastKey returns its result, and Carousel pulls it into your report.

What the result means

• No record found — no criminal records were identified. It only ever means a completed check whose answer is no record.
• Record confirmed — criminal records were identified.
• Needs verification — additional information is required to verify the record: what was provided does not align with official records.
• Provider issue — the check could not be submitted, or did not complete.

Before a result, the check reads Not started or In progress. A finished check with no result back reads No result.

What your report shows

• FastKey’s result.
• The offences the applicant declared, if any. They are the applicant’s own declaration, not findings.
• The details FastKey was sent, and the ID document sent with the check.
• The address history the applicant stated.
• A copy of FastKey’s report, when one came back.

At a glance

Provider

FastKey

Packages

Verified Max

In the report

Police check

In the package list it is Police Check (All of Canada).

How it works

1. On Carousel’s hosted flow, the applicant connects their bank account.
2. Plaid or Flinks returns the accounts and their transactions.
3. Carousel works out income from the transactions, and says so when it can’t.

What your report shows

• The connected accounts and the state of each connection.
• Income and employment, where the transactions show it.
• Affordability: the rent on the file against that income.
• The transactions themselves.

The check reads Connected once the accounts come through, Connection issue when a connection reports a problem, and In progress while the bank data is still arriving. If the applicant was asked to redo the connection, or it stopped on their side before any account came through, it reads Retry asked or Didn’t finish.

The Overview’s rent to income, monthly income and rent in the bank read this check when it has data. Each figure says whether it was checked or self-declared.

At a glance

Provider

Plaid or Flinks

Packages

Verified Pro, Verified Max

In the report

Financial verification

The report calls this check Financial verification; the package list calls it Bank verification.

How it works

1. When you send, choose They pay. On the review sheet, Who pays then reads Applicant.
2. On Carousel’s hosted flow, the applicant pays Carousel in the payment step.
3. Nothing leaves your balance: the review sheet reads Free for you.

A custom workflow’s payer is fixed by how it was built in Carousel. The review sheet shows it, and you can’t change it.

What it costs the applicant

The amount is set on Carousel’s side, on the workflow. For a package, the review sheet shows what the applicant will pay before you send. For a custom workflow, it reads The applicant pays at checkout.

What your report shows

• The step and where it is: Completed, In progress or Not started.
• It is left out of the PDF by default, and in every preset.

At a glance

Provider

Carousel

Runs when

The applicant pays

In the report

Applicant payment

This payment never passes through your balance, so there’s nothing to refund to you. The applicant asks for any refund of it: see Request a refund. For the applicant’s side, see The verification fee.

What it does

• Send a screening from your CRM. Choose the checks, file it under a building, and Carousel emails the applicant their link — or hands the link to you.
• Get back the link to show. Every answer carries portalUrl, the screening’s page in Carousel, for your team. They sign in once and open it from your CRM.
• Follow it. Sent, started, each check done, completed, viewed, and more — read them when you like, or have them pushed to your webhook.
• Read the results, if you choose. A key made with Read applicant results gets each check’s results and documents — identity, credit, court, police, bank. Other keys never see them.

Carousel never approves or rejects an applicant. Each check reports what its provider returned; the decision is yours.

Where to start

1. Sign up at app.oncarousel.com with Google — it’s the only way to sign in. Each person has their own account.
2. Open the account menu (your initials, top right) and choose Developers. Its Quickstart has the base URL and requests you can paste; Keys creates a key; Webhook sets where events are sent.
3. Read Concepts, then follow the API quickstart.

Link into Carousel

Without the API, your site can still open the composer with a screening already filled in. Link to /screen/new on Carousel and add any of these to the query:

• recipient — the applicant’s email address. Without it, nothing is filled in.
• package — v (Verified), vp (Verified+), pro (Verified Pro) or max (Verified Max). Without it, Verified+.
• payer — renter (the applicant pays) or self (you pay). Without it, the applicant pays.
• region — CA for Canada.
• mode — screen, the default, opens the composer; send opens it and asks a signed-out visitor to sign in straight away; signin and signup open the sign-in page.

The link carries no price and no authority. Nothing is sent until the sender signs in and reviews the screening.

The Carousel Classic API

Carousel Classic is the original platform: workflows built in its dashboard, and its own API at api.oncarousel.com. New integrations use the Carousel API at https://app.oncarousel.com/api/v1, which these pages describe. Classic’s guides and full reference are in the Carousel Classic developer docs.

If a custom workflow runs on a Carousel Classic workspace of your own, the account owner sees that workspace’s Carousel API key in Settings. It works with the Carousel Classic API only, and returns only that workspace’s applications.

Questions

What Carousel is

Carousel screens rental applicants for landlords and property managers. You send a screening — a set of checks — to an applicant’s email, and they complete it on Carousel’s own hosted flow, which includes ID and selfie, credit, court, police and bank checks, and a short self-declaration of their income, household and history. Each provider’s result is collected into a report your team reads at portalUrl.

Who’s who

• You — a landlord or property manager with a Carousel account. Your system calls the API with a key made in that account.
• Your team — the people who read reports in Carousel, at portalUrl. They sign in with Google.
• The applicant — the person being screened. The API knows them by email only, and they complete their checks from applicantLink. Their name comes from their ID once they’ve completed it.
• Carousel — emails the invitation, runs the hosted flow, takes the applicant’s payment when they pay, and collects each result into the report.
• Providers — the sources behind the checks, such as TransUnion or Equifax for credit. They’re listed under Where it works, below.

How a screening flows

1. Your system sends POST /screenings: the checks, the applicant’s email, and where to file it.
2. Carousel emails the applicant their applicantLink. With "delivery": "none", it hands you the link to pass on instead.
3. The applicant completes the checks on Carousel’s hosted flow — and pays at checkout, when the payer is renter.
4. Each provider returns its result, and Carousel adds it to the report.
5. Each change is recorded as an event. Read them from GET /events, or have them pushed to your webhook.
6. Your team opens portalUrl to read the report — or your system reads /results, with a key allowed to.

The nouns

Account and key

• Account. Sign up at app.oncarousel.com with Google — Google sign-in is the only way in. Each person has their own account.
• Key. Made in Carousel: account menu → Developers → Keys. Live keys look like cp_live_…, test keys cp_test_…. An account has at most 10 of each in use, each with a name of up to 60 characters.
• What a key sees. A key acts for the account it’s made in. It sees every screening filed in that account — its workspaces, its buildings and Private — whoever sent it, including screenings sent from Carousel’s own screens. It doesn’t see screenings in workspaces another account shared with you. So make the key in the account whose screenings your system should see.
• Results. Only a key made with Read applicant results ticked reads results and documents. Every key sees each screening’s applicantEmail.

Workspace, building, unit and Private

• Workspace. Where your team works in Carousel. Each workspace has one region.
• Building. An address in a workspace. Carousel reads its province from the address. Its monthly rent, if you give one, is what the report weighs the applicant’s income against.
• Unit. A rental in a building, by its label: “4B”.
• Private. Screenings with no workspace or building. Carousel lists them under “Private” in Applications, for the account’s own people.

A screening is filed under a building (and, if you like, one of its units), in a workspace with no building, or in Private. See Workspaces and buildings.

Application, screening and report

• Screening. One person’s checks: what POST /screenings sends.
• Application. Carousel’s file for one rental lead. Each send creates one. Co-applicants and guarantors added in Carousel join the same application, each with their own screening; the API can’t add them yet. application.* events list the application’s screenings.
• Report. What each provider returned for a screening, at portalUrl.

Check, combination and custom workflow

• Check. One verification, sent by its id: id, credit, court_roc and so on. The check id id means identity verification; it’s unrelated to the id field objects carry.
• Combination. A set of checks that go together. A screening runs exactly one combination, and no other mix can be sent. GET /checks lists them.
• Custom workflow. A set of checks Carousel sets up for an account — contact Carousel for one. Listed under workflows in GET /checks, and sent with "workflow": "<id>". Its payer is fixed.

Payer

• tokens — you pay, from your token balance.
• renter — the applicant pays Carousel at checkout, and you’re charged no tokens.

Leave payer out and it’s tokens for checks, or the workflow’s own payer for a custom workflow.

Region and court area

• Region. CA (Canada, in CAD) or US (the United States, in USD). Each region has its own token balance, checks and prices.
• Court area, in Canada only. QC is Québec: court_qc and penal_qc, which always come as a pair. ROC is the rest of Canada: court_roc.
• A building whose address is in Québec runs Québec’s checks, and court_roc for it is refused with 422 court_area_mismatch. For a building elsewhere, or with no building, either set is accepted: you choose.

Money

• Tokens. 12 tokens = $1: Canadian dollars in Canada, US dollars in the US. Each region has its own balance. Buy tokens in Carousel — see Tokens and billing.
• What a screening costs. A combination’s tokens is the sum of its checks’ prices. Prices can change, and GET /checks always has the live ones.
• When you’re charged. Per check, as each one completes. A check that never completes is never charged. tokenCost, on every screening, is the most it can cost.
• Not enough tokens. A send your balance can’t cover is refused with 402 insufficient_tokens, and nothing is sent.
• When the applicant pays. With "payer": "renter", the applicant pays the combination’s applicantPrice at checkout — CA$24.99 for id and credit, CA$32.99 for id, credit and court_roc, at shipped prices — and you’re charged no tokens.

Shipped prices in Canada:

So ["id", "credit", "court_roc"] costs at most 72 + 192 + 72 = 336 tokens.

Lifecycle and timing

• invited — sent; the applicant hasn’t started.
• in_progress — the applicant has started.
• completed — every check is done, and the report is at portalUrl.
• expired — nobody started it within 30 days of the invitation. Only unstarted screenings expire.
• cancelled — cancelled in Carousel.

Cancel and remind are done in Carousel, from the application’s row; the API has neither. A cancelled or expired screening’s link still works for the applicant, but checks finished afterwards are neither shown nor charged. More in Send and follow screenings.

Two links

Testing

Build against a test key (cp_test_… — Developers → Keys → Test key). Same address, same requests, same answers, but nothing real happens: nobody is emailed, no tokens are spent, no real check runs. With a live key every send is real — and so is every request from the API reference’s console.

• A simulated applicant. Each test screening is invited, started 30 seconds later, gets one check done every 15 seconds, then completes. POST /screenings/{id}/advance does the rest at once.
• Choose what happens with the applicant email’s +tag: tenant+record@example.com finds a court record, +stopped stops the first check, +expire never starts (expires after two minutes), +bounce bounces the invitation. No tag: everything clear.
• Results are Carousel’s fictional sample applicant, cut to the checks you sent. portalUrl opens the sample report.
• Events go to the test stream: GET /events with the test key. POST /webhook/test sends one signed sample event to your webhook now and tells you what it answered.
• Kept apart. Every answer and event says "livemode". Test screenings never appear in your team’s lists or billing. Workspaces and buildings are your real ones.

To try a live send on yourself, the cheapest is ["id", "credit"] with "payer": "renter" (CA$24.99 at checkout, at shipped prices) or "payer": "tokens" (264 tokens, about $22, charged as each check completes). The credit check is a hard inquiry on your own credit file, and there’s no cancel endpoint — cancel in Carousel, from the application’s row.

Where it works

GET /checks?region=US names each US check’s provider.

Carousel and Carousel Classic

Carousel Classic is the original platform: workflows built in its dashboard, and its API at api.oncarousel.com. New integrations use the Carousel API at https://app.oncarousel.com/api/v1, which these pages describe. A Carousel Classic key works with the Classic API only; Classic has its own developer docs.

Applicant data

Applicant data is regulated personal information. Use it only to assess the rental application, store it only as long as you need it, and follow your privacy obligations. See Carousel’s Privacy Policy and Terms.

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. Copy it straight away: it’s shown once. It starts cp_live_.

Make it in the account whose screenings your system should see. A key acts for the account it’s made in: it sees every screening filed there, whoever sent it, but not screenings in workspaces another account shared with you.

Tick Read applicant results only if this system should receive the checks’ results — see Applicant results. A key without it sends and follows screenings and sees each applicant’s email, but never their results or documents.

Keep it on your server, for example as CAROUSEL_API_KEY. A key can send screenings, which spend tokens. You can have up to 10 live keys and 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" }
}

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$32.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. Canada’s seven are in Send and follow screenings. workflows lists custom workflows Carousel set up for you; send those by id.

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 building’s rent 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.

To file under a building, list your workspaces, then a workspace’s buildings — or add the building: if its address is already there, you get that building back. 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" \
  -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" \
  -d '{
    "checks": ["id", "credit", "court_roc"],
    "applicant": { "email": "tenant@example.com" },
    "region": "CA",
    "externalId": "lead-1043"
  }' 

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 and penal_qc 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 — it never sends twice.

{
  "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.

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 people signed in to Carousel who belong to your account, or who are members of the screening’s workspace or building, so share the workspace with teammates in Carousel first. They sign in with Google the first time; after that it opens straight away.

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.

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"

The request

POST /screenings, with these fields.

• checks or workflow. Send exactly one. checks is the ids of one combination’s checks, such as ["id", "credit", "court_roc"] — the combinations are below, and in GET /checks. A custom workflow is sent by its id, from workflows in GET /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: tokens for checks, the workflow’s own payer for a custom workflow.
• Where it’s filed. A building files it under that building, in the building’s own workspace; add unit for one of its units. A workspace files it there with no building. With neither, it’s filed in Private, and region is required.
• region. CA or US. With a workspace or building it’s optional; if you send it, it must match the property’s region, or the answer is 409 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 applicant applicantLink yourself — 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_qc and penal_qc — Court & Eviction Search (QC) and Penal Search (QC), Québec’s court checks. They always come as a pair.
• criminal — Police Check (All of Canada).
• bank — Bank verification.

The seven combinations, by the court checks each runs:

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 and penal_qc 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 three combinations:

• id, credit
• id, credit, records
• id, 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.

The answer

201 with the screening:

delivery is one of:

• sent — our mail service accepted the email.
• failed — it was refused right away. Hand the applicant applicantLink yourself.
• none — you sent "delivery": "none", or the email wasn’t sent at that moment.

A bounce that happens later arrives as the event screening.invitation_failed.

Retrying safely

Send an Idempotency-Key header — any string up to 255 characters, unique per send, such as your record’s id. Keys are per API key, and a blank header counts as none. Then:

• The same key with a byte-identical body returns the first answer, with Idempotent-Replayed: true, and sends nothing. For a send that went through, that’s 200 with the screening as GET /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_error and internal_error.
• Any other refusal is kept for that key. After fixing a 400, 404 or 422, send with a new key.
• Sends count toward the limit of 30 a minute even when they’re replays or refusals.

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:

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

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. It isn’t charged as completed, and 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.
• applicantLink is 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 text applicantLink yourself.

List your screenings

curl "https://app.oncarousel.com/api/v1/screenings?limit=50" \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

Every screening in your account — sent through the API or from Carousel, by anyone on your team, 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.

• limit is up to 100.
• Pass cursor back as after while hasMore is true. Treat cursors as opaque: store and send them as they are.
• Narrow it with status (invited, in_progress, completed, expired, cancelled), workspace, building or updatedSince.

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.

What a key sees

Every screening filed in your account — its workspaces, its buildings and Private — whoever on your team sent it, including from Carousel’s own screens, once its invitation went out. Not screenings in workspaces another account shared with you.

Every key sees each screening’s status, links and applicantEmail. Only a key made with Read applicant results sees the checks’ results and documents, at their own endpoint.

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 result is there within minutes of its step. The answer has the screening, its steps, every check, and its documents:

{
  "screening": { "id": "6f0c…", "status": "completed", "externalId": "lead-1042", "portalUrl": "…" },
  "steps": [ { "key": "creditCheck", "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:

Is a result there?

Each key in checks has an availability:

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.

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 — a summary for the Court & Eviction searches and, when bought, a penalSummary for the Penal Search — clear, possible_matches or not_clear_yet, as the report says them — and each provider’s items, tagged with their search.
• police — the result — negative, confirmation or incomplete — with the convictions declared and the address history. When the check timed out, was cancelled or hit an applicant error: only "hidden": true and 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.

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.

Documents

documents lists the stored files, each with its id, kind and downloadUrl. The kinds:

• id_front and id_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.

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 documents instead.
• 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.

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 same workspaces and buildings your team sees in Carousel — see Workspaces, buildings and units.

The places

• Workspace → building → unit. A workspace holds buildings; a building holds units.
• One region per workspace. A workspace is CA or US. A region sent with a screening must match its workspace’s or building’s, or the answer is 409 region_mismatch.
• Private. Screenings with no workspace or building. Carousel lists them under “Private” in Applications, for the account’s own people. Send "region": "CA" (or "US") with no workspace or building to file one there.

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 — and parent (the workspace it sits in, or null; read-only in the API). To find a workspace by name, list them and match name.

To add one — it’s created as a tenant workspace:

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" }'

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.

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 is already a building in that workspace, you get that building back with 200 and "created": false, plus any units it didn’t have — never a duplicate. So you can send the address every time without checking first.

• 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 unit 1203.
• 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, or null. The report weighs the applicant’s income against it.

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 and penal_qc for it. court_roc is refused with 422 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.

An event

{
  "id": "0d6e…",
  "seq": 1042,
  "type": "screening.completed",
  "createdAt": "2026-10-03T18:42:10.512Z",
  "data": {
    "screening": {
      "id": "6f0c…",
      "externalId": "lead-1042",
      "portalUrl": "https://app.oncarousel.com/report/6f0c…"
    }
  }
}

seq only increases: it’s your place in the stream. Its numbering is shared, so expect gaps, and order by seq. Events carry ids, your externalId and the link — never applicant data. They cover screenings sent from Carousel’s own screens too, where externalId is null. Your account’s stream starts when it creates its first key or webhook, and a new event appears within about a minute.

Event types

GET /events/types returns each type with a one-line description.

Screenings

• screening.sent — The screening was created and its applicant link issued.
• screening.invitation_delivered — The invitation email reached the applicant’s mail provider.
• screening.invitation_failed — The invitation email bounced — hand the applicant the link yourself.
• screening.reminded — A reminder was sent to the applicant.
• screening.started — The applicant opened the application and started.
• screening.step_completed — One check finished.
• screening.completed — Every check is done — the report is ready.
• screening.viewed — Someone opened the report in Carousel.
• screening.cancelled — The screening was cancelled; nothing more is charged.
• screening.expired — The applicant never started within 30 days; the invitation expired.

data.screening is the screening’s id, externalId and portalUrl; step_completed adds data.check, the check’s id.

Applications

• application.stage_changed — The application moved to another stage.
• application.note_added — Your team added a note (its text is not sent).
• application.moved — The application was filed under another workspace or building.

data.application is the application’s id and portalUrl; data.screenings lists its screenings with their id and externalId; stage_changed adds data.stage with its id and name.

Buildings and balance

• building.created — A building was added.
• unit.created — A unit was added to a building.
• balance.low — Your token balance fell below the low-balance threshold.
• balance.exhausted — Your token balance ran out; token-paid sends are refused until a top-up.

data.building has its id, address and workspace; data.unit its id, label and building; balance events give the region.

Read them

curl "https://app.oncarousel.com/api/v1/events?after=0&limit=50" \
  -H "Authorization: Bearer $CAROUSEL_API_KEY"

Oldest first: { "data": [ … ], "cursor": 1042, "hasMore": false }. Save cursor and pass it as after next time; while hasMore is true, ask again straight away. types narrows it, comma-separated: types=screening.completed,screening.viewed. limit is 50 by default, and at most 200.

Events are kept. A webhook delivery you missed can always be read again here.

A webhook

In Carousel: account menu → Developers → Webhook. Enter one HTTPS address — an account has one — keep Every event or pick some, and save. Your signing secret (whsec_…) is shown once — copy it.

POST <your URL>
Content-Type: application/json
User-Agent: Carousel-Webhooks/1
Carousel-Event: screening.completed
Carousel-Delivery: <delivery id>
Carousel-Signature: t=1791060000,v1=<hex>

{ the event, as above }

• Answer with any 2xx within 10 seconds. Otherwise we try again after at least 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then stop. The event stays in GET /events.
• Delivery is at least once, and not in order. Ignore a Carousel-Delivery you’ve already handled, and order by seq.
• Events are sent if they were recorded after you saved the address.
• Saving the address again creates a new signing secret, shown once, and stops pending deliveries to the old setup.
• The address must be public HTTPS, up to 500 characters: no IP addresses, no internal hosts. We don’t follow redirects.
• The Webhook tab lists the last ten deliveries and what your server answered.

Check the signature

The Carousel-Signature header is t=<unix seconds>,v1=<hex>. v1 is the hex HMAC-SHA256 of <t>.<raw body> — t, a dot, and the raw body — keyed with your signing secret. Recompute it before trusting a delivery. t and the signature are new on each attempt, and you may refuse an old t.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before any JSON parsing
function isFromCarousel(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac

def is_from_carousel(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

An error

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Not enough tokens for this screening — nothing was sent.",
    "hint": "Top up tokens in Carousel, then retry the same request …"
  }
}

code is stable — branch on it. message says what happened; hint is the next thing to do.

Codes

• 400 invalid_request — Fix the field the message names. Unknown fields are refused too, and so is a malformed checks: not a list, empty, more than 12, with a duplicate, or with an id that isn’t lowercase letters and _.
• 400 invalid_email — Send the applicant’s email address in applicant.email — phone numbers aren’t accepted.
• 401 unauthorized — Send Authorization: Bearer <key> with a live key.
• 402 insufficient_tokens — Top up tokens in Carousel, then retry the same request (the same Idempotency-Key works) — or send with "payer": "renter".
• 403 results_not_allowed — This key wasn’t made to read applicant results — create one with Read applicant results ticked.
• 404 not_found — Use an id from your own account: GET /workspaces, /buildings or /screenings.
• 409 idempotency_conflict — That Idempotency-Key was used with a different body, even one only formatted differently — use a new key for a new send.
• 409 request_in_progress — The first request with that key is still running — repeat it in a few seconds.
• 409 results_changed — The bank data changed between transaction pages — start again with after=0.
• 409 region_mismatch — The region you sent isn’t the workspace’s or building’s. Leave it out, or send theirs.
• 413 document_too_large — Download the file in ranges: Range: bytes=0-4194303, then the next 4 MB.
• 400 test_mode_only — POST /screenings/{id}/advance works with a test key only (cp_test_…).
• 503 test_mode_not_ready — Test mode isn’t switched on yet. Use a live key meanwhile, or try again later.
• 416 — The Range header is bad. Ask for bytes=0-4194303, then onward, within the file.
• 422 unknown_combination — A well-formed checks that isn’t exactly one combination. Send exactly the checks of one combination, in any order — GET /checks?region=CA lists them.
• 422 court_area_mismatch — Only a building in Québec refuses court_roc. Send court_qc and penal_qc for it.
• 422 combination_unavailable — That combination isn’t set up to send there yet. Retry later, or send one whose sendable is true for your payer — GET /checks?region=CA.
• 422 workflow_unavailable — That custom workflow isn’t offered where you’re sending, or its payer isn’t the payer you sent. Leave payer out, use a workflow GET /checks offers there, or retry later.
• 429 rate_limited — Wait the seconds in the Retry-After header, then retry.
• 500 internal_error — Retry later. If it keeps happening, write to support with the time of the request.
• 502 carousel_error — A provider or service behind Carousel didn’t answer. Nothing was sent or charged — retry with the same Idempotency-Key.

Limits

• 120 requests a minute per key.
• 30 screenings sent a minute per account — replays and refusals count too.
• 30 reads a minute per key across results, transactions and documents.
• 10 live keys per account.

Over a limit, the answer is 429 rate_limited with a Retry-After header in seconds. There are no other rate headers.

When to retry

• Retry 429, 500, 502 and 409 request_in_progress — with the same Idempotency-Key, so nothing sends twice.
• Retry after fixing something 402 (top up) — the same key works.
• Retry later 422 combination_unavailable and 422 workflow_unavailable, with the same key — or send another combination or workflow.
• Don’t retry unchanged the 400s, 404s and other 422s: the same request gets the same answer, and the key keeps it. Fix the request, then send it with a new Idempotency-Key.

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 takes the same API key, with the same limits and refusals. Sends are still real, so a good assistant asks you before each one.

• 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. The connection appears under Developers → Keys, where you can disconnect it.
• Anywhere else: send a key, Authorization: Bearer <your key> — a test key (cp_test_…) to try it with nothing real.

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}" }
    }
  }
}

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. Reads run without asking; an assistant asks you before every write.

Reads

• whoami — the account and key the connection acts for.
• list_checks — the checks and combinations you can send in a region, with their prices.
• list_workspaces — your workspaces.
• list_buildings — a workspace’s buildings and units.
• get_screening — one screening’s status and each check’s progress.
• list_screenings — your screenings, newest first, or the ones sent with an id of yours.
• get_results — each check’s results, only when the connection may read results.
• list_events — everything that happened, 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 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" 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.

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 is refused, never dropped.
• Retries are safe. With an Idempotency-Key, a repeated send never sends twice.
• What you can send is listed. GET /checks gives every combination of checks; a send that isn’t one is refused with a hint that points back to it.
• Places by name. GET /workspaces lists workspaces with their names, and GET /buildings a 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.

For account holders

• Tokens and billing — how you pay for screenings, and when tokens are charged.
• Share with your team — who sees a workspace, and whose tokens they use.

For applicants

• How Carousel works — what to expect end to end.
• The verification fee — what an applicant pays when you choose They pay.
• Request a refund — how an applicant asks Carousel for one.

Reaching a person

Write to support@oncarousel.com with a question about a report, your tokens or your account.

What tokens are

Tokens pay for the screenings you pay for yourself: You pay on the composer. Your balance sits in the header, beside Buy tokens.

What a screening costs

A screening costs the sum of its checks. The review sheet shows the cost in tokens before you send.

The price is fixed when you send. A later price change never changes a screening already sent.

When tokens are charged

• Per check — when Carousel completes it, whatever the result.
• Never completed — a check Carousel never completes is never charged.
• Only your checks — only the checks in the screening you sent are charged.
• Cancelled or expired — after you cancel a screening, or its invitation expires, nothing more is charged.

Your balance

To send, your balance must cover the full cost of the send, for everyone on it. Because checks are charged as Carousel completes them, your balance can fall below zero after you send. New sends are then blocked until it covers them again.

In Settings, Usage & billing lists every token in and out, itemized by billable step.

Buying tokens

Choose Buy tokens, in the header or in Settings. You pick how many screenings’ worth to buy, and pay on a Stripe checkout page. Buying more at once lowers the price per screening, and Carousel shows the price before you pay. Each purchase is charged once, with no renewal.

Auto refill: save a card, and when your balance goes under a level you choose, Carousel buys the number of tokens you set. You can turn it off.

When the applicant pays

Choose They pay and nothing leaves your balance: the applicant pays Carousel, in Carousel’s own payment step. The review sheet shows “Free for you”.

A custom workflow’s payer is fixed by how it was built in Carousel.

Your team

When you share a workspace, you choose whether each person may use your tokens, uses only their own, or only views. See Share with your team.

Refunds

If the applicant paid, they ask Carousel about a refund: see Request a refund. For a question about a token purchase or a charge, write to support@oncarousel.com.