Skip to main content
A session is one applicant’s run through a journey you published in Console. Your server starts it, the applicant completes it on Baselayer’s hosted screens, and Baselayer tells your server the outcome. Your server makes two calls and receives one webhook:

​
Start a session

Start one session per applicant. The template_id is the journey’s ID, the last part of its URL in Console:
reference_id is your own identifier for the applicant; it comes back on the session, its results and its webhook. The response carries the session’s id, an embed_url, the session_token already embedded in it, expires_at (when the link stops working) and your reference_id. A journey that was never published answers 409. Retrying the call starts a second session rather than returning the first; use reference_id to tell them apart.

​
Show it to the applicant

Open embed_url in an iframe inside your product:
Or redirect the applicant to it. Either way, the URL is the applicant’s credential for this one session: treat it like a password, and start a new session rather than reusing a link.

​
Receive the outcome

When the applicant finishes and the checks complete, Baselayer sends the OnboardingSession.completed webhook. It is a summary, not the full results: Rarely, the webhook goes out late, after a reviewer has already decided the session; verdict then carries that decision, which can be REJECTED. Treat the results as the source of truth. Then read the session’s results with GET /onboarding/sessions/{id}/results. They carry the verdict, what the applicant entered (including your custom fields), their confirmed identity, the business, beneficial owners, and what each check found. A session that hasn’t completed answers 409 with error code 6007, and a completed session whose results aren’t available answers 404 with error code 6008.