01 · Starting point
Onboarding looks simple until it meets reality.
A new business account often begins with three fields. In reality, the service must understand which company is involved, who the person is and what the parties have actually approved.
Consider a company building a web service or CMS for Swedish business customers. The customer should register their company, sign in securely and enter an agreement before the workspace is activated. If each part is solved separately, three data models, three support flows and three ways of handling errors quickly emerge.
The important part is not merely choosing APIs. It is giving each component a clear responsibility while your product owns the coherent customer journey.
Core principle
Company data answers which company. BankID answers which person. The agreement records what was accepted. Do not confuse the three forms of evidence.
02 · Target state
One flow for the customer. Clear boundaries in the technology.
The customer should experience a single onboarding journey even when several specialised services work underneath. A robust target state can be divided into five steps.
Step 01Find the company
A company registration number or search retrieves verified core data from BolagsAPI.
Step 02Verify the person
Auth by Hugo performs BankID identification and returns a secure session.
Step 03Create the workspace
Your service links the person to a provisional company account with the correct permissions.
Step 04Approve the terms
Avtalsklart sends the right document to the right recipient and collects the signature.
Step 05Activate
A signed event activates the subscription and is stored in the product's event log.
Separate identity from authorisation
BankID shows who the person is, but not automatically what they may do in your system or whether they may represent the company alone in every situation. Permissions, signatory rights and internal approval rules must be modelled explicitly for the use case.
↳
Continue reading
Unlock the rest of the guide.
Leave your email to unlock the complete guide immediately and receive the PDF in your inbox. If you choose, we can also follow up with information relevant to Swedish company data, BankID and signing.
Your interest is tagged asDigital B2B onboardingBolagsAPI · Auth by Hugo · Avtalsklart
03 · Building blocks
Three services, each with its own responsibility.
Company dataBolagsAPI
Search, core data, status, addresses, roles and other Swedish company information through REST or MCP.
bolagsapi.se ↗
IdentitetAuth by Hugo
BankID-based identification and OIDC sign-in in a managed flow that can be adapted to the service.
auth.byhugo.se ↗
SigneringAvtalsklart
Prepare documents, invite recipients, follow status and collect verifiable BankID signatures.
avtalsklart.se ↗
04 · Architecture
Let your product be the orchestrator.
Your application should own the customer journey, internal state and relationship between companies, users and agreements. Providers own their specialist functions. This makes the flow easier to test and possible to resume after an interruption.
| Layer | Responsibility | Store internally | Avoid |
|---|
| BolagsAPI | Current company information | Company registration number, selected snapshot and source time | Copying the entire register without need |
| Auth | Identification and secure session | Internal user ID and necessary identity references | Using a personal identity number as a public key |
| Your product | Permissions, onboarding state and business rules | The user–company relationship and state machine | Deriving permissions from sign-in alone |
| Avtalsklart | Documents, recipients and signing evidence | Agreement ID, version, status and timestamps | Activating before the signed webhook is verified |
Build onboarding as a state machine
Use clear states such as company selected, identity verified,
agreement sent, agreement signed and account active. This lets the customer continue where they left off, support see what is missing and webhooks be processed idempotently.
05 · Implementation
Start with the narrowest working customer journey.
- Define the evidence. Decide what must be known about the company, person and agreement before an account can be activated.
- Build one successful main flow. One company, one administrator, one agreement and one permission level are enough for the first version.
- Add recovery. Handle interrupted BankID sessions, duplicates, delayed webhooks and agreements that are not signed.
- Open up to more roles. Only after the main flow works should you add invitations, multiple administrators and advanced approvals.
Measure the flow, not just the errors.
Track time to company selection, successful identification, sent agreement and activated account. You will see exactly where onboarding loses momentum.
06 · Security and control
Four details that determine whether the solution holds up.
- Minimise personal data. Store only what is needed for the account, agreement and legal requirements. Use internal identifiers elsewhere in the system.
- Verify incoming events. Webhooks must be authenticated, timestamped and safe to process repeatedly without duplicate effects.
- Version agreements. Store the exact document version and terms that were approved.
- Log decisions. An audit log should show when a company was selected, identity verified, permissions granted and the account activated.
07 · Checklist
Ready to move from sketch to implementation?
The company registration number is the company's primary key.
Identity and authorisation are two separate decisions.
Onboarding has explicit, resumable states.
All webhooks are verified and idempotent.
The agreement version and signing status are stored.
Support can see where the customer is in the flow.
Personal data is minimised and has retention rules.
Activation happens only after a controlled final event.
By Hugo!