Add and invite a client

Adding a client to your address book is the first step to link them to loads and trigger the operational pickup and delivery notifications. When you also want the client to access Truckscanner directly to monitor their shipments in real time, you invite them to register: the invitation is sent by email and is the actual collaboration channel.

Forwarder

What you'll find here

The complete flow to add a client: how to use the "New client" dialog with the automatic VAT verification on VIES and institutional registries, when fields are pre-filled and when you enter them manually, and how to invite them to collaborate on Truckscanner. You'll also see what the shipper receives by email on their side, what the three small icons next to the "Invited" badge do, and which operational notifications fire automatically when you link the client to a load.

Before you start: the Clients overview gives you the full map of the section (table, filters, detail drawer, row actions). Here we focus on the "add + invite" flow.

Before you begin

To add and invite a client you need:

A forwarder account with ADMIN or OPERATOR role (READONLY users don't see the create and invite buttons).
The VAT number or tax code of the client. It's mandatory because it serves as a unique identifier and enables the automatic verification on VIES and institutional registries. If you don't have a VAT — rare for a real shipper — you can't create the record.
The email address of the client, but only when you decide to invite them to collaborate on Truckscanner. In the address book you can keep the client even without email.

1. Open the "New client" dialog

From the Clients page (URL /company/{companyId}/trading-partners), click the lime "+ NEW" button at the top right of the header.

The «Business partners» page with the lime «+ NEW» button highlighted at the top right (1), next to the «IMPORT CSV» button. Three clients are shown in the table including some already registered and one with the «COLLABORATE ON TRUCKSCANNER» button.

The button opens the modal dialog "New client". The dialog is organized in two columns: on the left everything about the client company (tax identification, company name, registered office address), on the right the optional operational contact and the automatic notification toggles that will fire when you link the client to loads.

2. Enter country and VAT / tax code

The Country and VAT / Tax code fields are mandatory (red asterisk next to the labels). The default country is Italy, but you can change it: the menu lists all EU countries plus the main extra-EU ones (Switzerland, United Kingdom, Norway, United States, etc.).

The page shows a hint right below: "We automatically check the VAT number on VIES and institutional registries: click on the result below to pre-fill name and address."

As soon as you type a VAT of at least 8 characters Truckscanner automatically launches two parallel checks:

VIES — the official European Union system that validates the VAT for EU countries. It returns the official company name and in some cases a raw address.
Institutional registries — the country's business registry (for IT it's the Italian Business Registry, for other EU countries the respective national Chambers of Commerce). It returns company name, registered office address, and commercial data when available.

Below the fields a small status row tells you in real time what was found. While the lookup is running you see "Verifying...". When data is found, clicking the result pre-fills the Company name and Registered office address fields below.

The «New client» dialog with a VAT entered. The status row reads «No results on VIES or institutional registries. Continue by entering the data manually below.» (1) and the «Company name» field is empty waiting for manual input (2). On the right the Contact section is empty and the two toggles «Email notifications» and «SMS / WhatsApp notifications» are both on by default.

When verification finds only the name but no address

This happens for some Italian VAT numbers belonging to aggregated VAT groups (fiscal groups that gather several companies under a single VAT number): VIES and institutional registries confirm the company name but don't have a single registered office to return. In that case you fill the address manually using the Google Maps autocomplete in the "Registered office address" field. The VAT remains valid and the client is saved anyway.

When the VAT is not found in any source

If both VIES and institutional registries return empty, the row shows the message "No results on VIES or institutional registries. Continue by entering the data manually below". In this case Company name and Registered office address become mandatory (red asterisks appear next to the labels) to avoid saving a client identified by VAT only. This is normal for newly incorporated companies (registries take a few days to propagate) or for extra-EU VAT numbers not covered by our partner registries.

3. Fill the contact and notifications, then save

The right column has two blocks, both optional at creation time:

Contact (optional) — name, phone and email of the contact person at the company. They are address-book data useful for loads, not used for the Truckscanner invitation. You can also add them later from the detail drawer if you prefer.
Automatic notifications — the two toggles "Email notifications" (Tracking, pickup/delivery confirmations, documents) and "SMS / WhatsApp notifications" (Real-time alerts) decide whether the client will receive operational notifications (pickup confirmation, in transit, delivered, issue) when you link them as sender or recipient of a load. They're on by default. Switching them off here or later in the Commercial drawer has the same effect: operational notifications won't fire for that client. Dialog and drawer toggles modify the same field on the client, so they're always aligned.

Notifications fire only for loads, not for the invitation

The Truckscanner collaboration invitation travels only by email to the address you'll enter in the next step, regardless of toggle state. The toggles instead control transactional load notifications: pickup confirmed, delivery completed, any issues on the shipment.

When you're done click the lime "SAVE" button at the bottom right. Truckscanner creates the client, closes the dialog and shows a confirmation toast Client "{name}" created successfully. The new row appears immediately in the table and the tab counters at the top ("All", "Registered", "Invited", "Not invited") update live: the new client enters as "Not invited" until you send the invitation.

4. Invite the client to collaborate on Truckscanner

On the row of the client you just created, in the Truckscanner column, you see the lime "COLLABORATE ON TRUCKSCANNER" button. It's the shortcut to send the invitation.

The «Business partners» table after creating «ACME Logistics S.p.A.»: the counters at the top read «All 4, Registered 2, Invited 0, Not invited 2». On the new client row the «COLLABORATE ON TRUCKSCANNER» button (1) is highlighted next to the «Active» badge.

Clicking it opens the "Invite to Truckscanner" dialog. The description explains: "The invitation is sent by email to the address below. The client will be able to collaborate on Truckscanner for monitoring and shipment tracking."

Fields you'll see:

Summary card at the top with the company name and VAT prefixed by country code — read-only confirmation, not editable.
Recipient email — required. It's the address the invitation email is sent to; it's also saved on the client as contact email if there wasn't one already.
Phone — optional, with a small helper below: "Address-book detail for loads — not used for the invitation". You can leave it blank: the invitation is sent by email only anyway.
Optional message — free text included in the body of the invitation email (e.g. "Marco, we've decided to switch to Truckscanner: here's the link to access your shipments").

When you click "SEND INVITATION" the email is sent and the dialog changes: the form fields disappear and a green confirmation banner appears with the recipient address, a hint for manual link sharing, and the input with the registration link pre-filled with your forwarder VAT. There's also a copy icon to send it to the clipboard.

The «Invite to Truckscanner» dialog after sending: the green banner reads «Invitation email sent to acquisti@acmelogistics.example» followed by «You can also copy the link below and share it manually.» (1). Below, the readonly input with the pre-filled client registration link (`http://localhost:3000/register/client?ref=...`) and the copy icon button next to it (2). At the bottom the lime «OK» button to close.

The link is the shortcut for invitations via other channels

The email is sent automatically, but if you'd rather send the link to the client via WhatsApp, Telegram, Slack or even printed on paper, you can. The link stays valid until the invitation is accepted or cancelled — it doesn't expire automatically — so the client can register whenever they want.

5. What changes in the table after the invitation

When you close the dialog with "OK", the client's Truckscanner column changes in real time:

The "COLLABORATE ON TRUCKSCANNER" button disappears, replaced by the orange "Invited" badge.
Next to the badge three small icons appear that let you manage the invitation while it's still pending.

The table after sending the invitation: the counters at the top now read «All 4, Registered 2, Invited 1, Not invited 1». On the ACME Logistics row, in the Truckscanner column, the orange «Invited» badge is highlighted followed by three small icons (1): copy link icon, paper-plane icon to resend the email, X icon to cancel the invitation.

The three icons do this:

Copy invitation link (clipboard icon) — copies the same link you saw in the confirmation banner to the clipboard. Toast Link copied.
Resend invitation (paper-plane icon) — re-sends the same NC-A04 email to the same address, useful if the client didn't get the first one or it landed in spam. Toast Invitation resent successfully.
Cancel invitation (X icon) — removes the pending invitation. The client record stays in the directory as "Not invited", you can send a new invitation whenever you want. Toast Invitation removed.

The "Invited" tab counter updates in real time as soon as you click any of these actions.

When the client accepts the invitation and completes registration, the status automatically flips to "Registered" (green badge) and the record gets linked to their Truckscanner account: from then on they share with you the shipments where they are sender or recipient.

What happens behind the scenes

Sending the invitation triggers several things:

A row is created in client_relationships with status INVITED, a unique token for the registration link and an invited_at timestamp.
The NC-A04 — Client invitation notification is sent to the recipient email via SMTP. It's a direct notification (not routed through the dispatcher), so it's immediate.
On the client, the contact_email and contact_phone fields are updated if they were empty, so they become available for future loads.

When in future you use this client as sender or recipient of a load and the load's events progress (pickup confirmed, delivered, issue), operational notifications will fire by email to the client's address — provided the client's "Email notifications" toggle is on. WhatsApp and SMS notifications are wired up but rolling out: they'll arrive in a later release and won't break anything when active because the toggle is already there ready.

Cross-target impact — what the shipper receives

On the client side the invitation arrives as a transactional email. They open Mailpit (in dev) or their inbox in production and find this:

What the other side sees

Shipper

The shipper receives an email with subject "You have been invited to Truckscanner by {forwarder name}". In the body they find a personalised greeting with their company name, the line "{forwarder} has invited you to join the Truckscanner platform as a shipper", a list of the three main benefits (monitor shipments in real time, manage contracts and documents, see warehouses and sites status) and the lime button "REGISTER AS SHIPPER".

The button in the email opens the client registration flow with your forwarder name and VAT already pre-filled in the form: the shipper doesn't have to look you up, they find you already attached. When they complete registration, your row's status in the table flips to "Registered" and the client sees their shipper dashboard with the shipments they are involved in.

For the full client-side detail — registration form screenshots, password handling, terms acceptance — see the mirror page: Accept a forwarder's invitation.

Client "in directory" vs client "collaborator"

An important distinction that often confuses newcomers: a client in the directory is not automatically an active collaborator on Truckscanner.

In directory — the client record only lives in your forwarder company. You attach them to loads, you receive operational notifications on their behalf (or for them), you archive contracts and price lists. The client knows nothing about Truckscanner: they only receive your direct email/SMS/WhatsApp communications when their loads move. It's perfect for small clients or clients who don't want a dedicated tool.
Active collaborator — when the client accepts the invitation, they get direct access to the platform with their dashboard, their shipments in real time, their document management. From your side you still see their row in the directory, but with the "Registered" badge and a two-way relationship.

The two coexist: every client is first "in directory" and then optionally becomes a "collaborator". The "Collaborate on Truckscanner" button is the transition between the two states. You can suspend or remove the platform relationship anytime from the detail drawer without losing the client in the directory.