Onboarding onto Advantage
No stop on the rail is callable until an account exists, and an account only exists once a register has confirmed it.
Every page after this one assumes you already hold a credential. This page covers how one is issued.
Self-service onboarding is a public, unauthenticated funnel. A registrant arrives at the welcome landing with no token and leaves with an activated account they can sign in to. Identity is never self-asserted anywhere in it. The registrant supplies an identifier, the rail retrieves the official record behind it, and the verification code goes to the email address on that record rather than to one the registrant types. By the time the account exists, whoever holds it has shown they can read mail at an address a licensing body published.
Two tracks run off the same funnel. An individual, meaning a solo practitioner, verifies one identity and activates. A business, meaning a clinic or facility with one location or many, verifies the admin, then the facility, then activates. Both are the same four moves: look up, confirm, enter the code, continue.
Both tracks on one diagram. Dotted edges are the branches: a registry with no record, or an inbox nobody can open.
The map
| # | Step | The question it answers | What the registrant leaves with |
|---|---|---|---|
| 0 | Account type | Solo practitioner, or a business with locations? | the track, and whether it runs two steps or three |
| 1 | Verify admin identity | Who is setting this up, and are they licensed to? | registry_result_id and verification_token |
| 2 | Setup business (business only) | Which facility is this, and is its registration current? | the facility's confirmed record |
| 3 | Activate account | Can they read mail at the address the registry holds? | a temporary password, then a real one |
| Plan and billing (where required) | Is there an active subscription behind this org? | a receipt, and the app unlocked |
The step count is the only difference between the tracks. Individual runs two steps, verify then activate. Business runs three, verify the admin, set up the business, then activate. The stepper at the top of the screen is built from that choice.
Step 0 · Which account is being set up
The choice travels as a route parameter for the rest of the funnel, so it survives a refresh or a back-navigation. It is also the last thing the registrant asserts on their own. Everything after it is checked against a register.
Step 1 · Verify the admin identity
Whoever sets up an account may be an admin, the owner, or a staff member assigned to do it, and is not always the person the account is about. This step establishes who is at the keyboard and whether a licensing body knows them.
It opens on a choice of identifier, and that choice decides how much typing follows.
identifier.numberPOST registry-searchA hit comes back as a complete professional record, so the next screen reviews it instead of asking for it. The fields are read only, and the screen says where to go when something is wrong: the licensing body holds the record and Advantage only displays it. A copy anyone could edit would prove nothing.
full_namespeciality_cadrelicensing_bodyregistration_numberlicence_statuslicence_validity_end_dateemailPOST send-verificationThe code is six digits, expires in minutes, and can be resent. Verifying it returns a
verification_token, and what happens next is the one place the two tracks diverge:
| Call | What it does | What you keep |
|---|---|---|
Individual | The registration completes here. The token is spent immediately and the registrant goes straight to activation. | an account, pending activation |
Business | The result id and token are held rather than spent, and travel into the business payload later. A business account exists only once the facility behind it is confirmed too. | registry_result_id and verification_token |
Business admins skip the KMPDC lookup and land straight on the manual admin form. Whoever registers a clinic is often an administrator with no clinical licence to look up, so asking them for a practitioner number first would strand them on the first screen.
full_nameprofessionemailphoneis_business_ownerPOST manual-registrationStep 2 · Setup business
Business only. It repeats step 1 one level up, asking the same four questions about a facility instead of a person.
| Call | What it does | What you keep |
|---|---|---|
Registered with KMPDC | The facility register is read live. Details come back complete: name, level, ownership, type, licence validity, location. | the facility's record |
Other business registration | KRA, BRS, county government, or any other permit. The registrant supplies business name, industry, business email, phone, physical and postal address by hand. | the same record, typed |
The code for this step goes to the facility's registered email, often a reception or practice manager address rather than the admin's own inbox. That is deliberate. Verifying a person and verifying the business they claim to represent are two separate checks, and running both through one inbox would make the second one free.
Completing this step creates the business account. The admin's held registry_result_id and
verification_token go up alongside the facility's, and both identities are registered in one call.
business_namefacility_level, business_ownershipbusiness_idlicensing_bodylicence_statuslicence_validity_end_datebusiness_locationPOST facility/send-verificationStep 3 · Activate the account
Registration and activation are deliberately separate. Registration establishes that the identities check out; activation establishes that a human can read the mailbox they are attached to.
After that the account is live and the registrant lands on the dashboard.
Where the funnel forks
Three branches, each there so a registrant who falls out of the happy path still has a way to finish.
| Call | What it does | What you keep |
|---|---|---|
The registry has nothing | Every lookup screen carries a 'can't find your identifier' link into the manual form. The registrant types what the registry would have supplied. | the same account, a form later |
The inbox is unreachable | The address on the registry record is stale, or belongs to a former employer. Manual verification is queued instead and reviewed within 1 to 2 business days. | a pending verification |
A licence needs evidence | The compliance screen takes the regulator and a licence or accreditation upload (PDF, JPG or PNG). Checks run automatically, and a failed automatic check queues a manual review within 48 hours. | an uploaded licence, verified or queued |
Two behaviours that generate support tickets when nobody knows about them:
- 01A refresh resumes the step, a restart clears itProgress inside a step is cached: the retrieved record, the view the registrant is on, and the verification token. A reload picks up where it left off. Entering the funnel again clears all of it, so a half finished attempt from last week cannot leak stale details into a new one.
- 02Signed-in users are redirected off the funnelEvery public onboarding screen sends an authenticated user elsewhere, including on a typed URL or a back-navigation. Somebody who already has an account and wants to attach it to an organisation needs account linking, which is a separate flow.
The calls behind the screens
The funnel is unauthenticated by design. There is no bearer token yet, so the check that carries the weight is the code sent to the address the registry holds.
| Call | What it does | What you keep |
|---|---|---|
POST /api/v1/onboarding/individual/registry-search | Look up a professional by identifier type and number. | registry_result_id and the record |
POST /api/v1/onboarding/individual/send-verification | Send a 6-digit code to the email on the retrieved record. | nothing |
POST /api/v1/onboarding/individual/verify-code | Exchange the code for a token proving the address was read. | verification_token |
POST /api/v1/onboarding/individual/complete-registration | Create the account from the confirmed record and token. | an account, pending activation |
POST /api/v1/onboarding/individual/manual-registration | The same, from details typed by hand when no register answers. | an account, pending activation |
POST /api/v1/onboarding/business/facility/registry-search | The facility equivalent of the first call. | registry_result_id and the facility record |
POST /api/v1/onboarding/business/facility/send-verification · verify-code | Code to the facility's registered email, then the exchange. | the facility's verification_token |
POST /api/v1/onboarding/business/admin/validate | Check the admin identity against the facility being registered before the two are joined. | a validated admin |
POST /api/v1/onboarding/business/complete-registration | Register admin and facility together, both tokens in one payload. | a business account |
After activation, before the rail
One gate can still sit between an activated account and the app. Where the organisation needs a subscription, the first navigation into any authenticated screen is intercepted and sent to plan selection: a plan, then billing, then an M-Pesa STK push confirmed on the phone, then a receipt. It runs as a hook on the router, so it fires however the user arrived, whether straight out of onboarding or from a bookmark six weeks later.
Past that the account holds credentials, which is where the rest of this documentation starts.
Next00 · AuthenticateThe account exists, so now get your system onto the rail. Client credentials, the facility your token is scoped to, and the token every later call carries.
RelatedSelf-onboard on eTIMSInvoicing through the revenue branch needs a separate registration against KRA, done once and independently of this one.