Agent onboarding and mapping

Onboarding an agent is a sequence, not a single form. Skipping a step does not produce an error — it produces an agent who can sign in and sees nothing, which is harder to diagnose.

The steps

Step	What it does	Symptom if it is missing
Agent record	Creates the agent in the tenant	The person has no account to sign in with
App account link	Ties the agent record to the app account they sign in with	Sign-in works, but the account shows member screens instead of agent screens
Producer code	Links the agent to the identifier the source system uses	Income never appears, even though policies do
Licence status	Records whether the agent is licensed	The app hides the commission and promotion entries
Producer confirmation	Confirms who actually produced each policy	Policies sit in the mapping queue, or land on the licence holder

Why producer confirmation exists

In the source data, the producer code attached to a policy is often the licence holder — the licensed agent whose name is on the carrier paperwork — and not the person who actually wrote the business. Some agencies run this way deliberately.

The platform handles it with a tenant-level switch. When it is on:

Newly imported policies do not go straight into the policy table.
They wait in the policy-agent mapping queue until an operator confirms the real producing agent.
Only then is the policy written.

When the switch is off, policies import directly and attribution follows the source.

The trap: turning the switch off does not drain the queue

Items already waiting stay waiting. Nothing is auto-released, because “the agency turned the feature off” is not the same statement as “these particular policies should go through without review”. Work the queue down before changing the switch.

Working the queue

Each waiting item needs a decision, and the decisions are recorded — the platform keeps the operator’s judgement separate from the source data, so a later delivery cannot overwrite it.

Action	Meaning
Confirm	This is the agent who produced the policy
Reject	This attribution is wrong
Apply	Write the confirmed decisions through to the policies

Access to the queue is permission-controlled: reading the page, changing the switch, and each decision type are separate permissions. If a button is missing rather than disabled, you are missing that permission — not looking at a broken page.

The caveat that surprises operators

Policy mapping and commission attribution are not the same path. Commission arrives in the carrier’s commission file, and historically that file’s attribution follows the file’s own producer code — the licence holder — regardless of what the mapping queue decided about the policy.

So confirming a policy’s real producer improves the policy and client picture, but by itself does not move the commission. If the commission attribution is wrong, it has to be corrected on the commission path; ask before assuming one fixes the other.

Preflight

Before a real import you can run the importer in report mode. It lists the actions it would take. If a preflight reports a batch of new policies while the real import creates none because everything was suspended by the mapping switch, the two are not describing the same configuration — that is worth reporting.

“The new agent can’t see income”

Check in this order. Each step is a different fix, and the first three are cheap:

Licence status — an unlicensed broker has no premium-based income, by design.
Account link — is the app account tied to the agent record, or to nothing?
Producer code — does it match the identifier the source system uses for this person? Aliases exist for agents recorded under more than one identifier; confirm the alias is set up rather than assuming the code is wrong.
Source layer — does any layer of the commission chain actually have data for this agent? See Understanding your commission.

If all four are in place and the amount is still zero, check whether the data is fresh before treating it as a commission problem.