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 on this page

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 consignor receives by email on their side, what the three little 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 (VIEWER 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 consignor — 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 «+ NUOVO» button at the top right of the header.

The «Business Partners» page with the lime «+ NUOVO» button highlighted at the top right (1), next to the «IMPORTA CSV» button. Two clients already registered on Truckscanner are shown in the table.

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.).

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 green confirmation row tells you in real time what was found. Truckscanner automatically pre-fills the Company name and Registered office address fields below, so you don't need to click anything to apply the data.

The «New client» dialog after entering a VAT: at the top the green row «VIES verified — ACME Logistics S.p.A.» (1) confirms the lookup result; below, the «Company name» field has been auto-filled with the official company name (2). On the right, the Contact section is still 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. These are address-book details useful for loads, they're not used for the Truckscanner invitation. You can also add them later from the detail drawer.
Automatic notifications — the two toggles «Email Notifications» and «SMS / WhatsApp Notifications» decide whether the client will receive operational communications (pickup confirmed, in transit, delivered, problem) when you link them as sender or recipient of a load. They're on by default. Turning them off here or turning them off later in the Commercial drawer has the same effect: operational notifications won't fire for that client. The dialog and drawer toggles modify the same field on the client, so they're always in sync.

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 notifications for loads: pickup confirmed, delivery completed, any shipment problems.

When you're done click the lime «SALVA» button at the bottom right. Truckscanner creates the client, closes the dialog, and shows a confirmation toast «Client "{name}" created». 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 just-created client, in the Truckscanner column, you see the lime «COLLABORA SU 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 show «Tutti 3, Registrato 2, Invitato 0, Non invitato 1». On the new client's row, in the Truckscanner column, the lime «COLLABORA SU TRUCKSCANNER» button is highlighted (1). The DL Committente and Industrie Bianchi rows show the green «Registrato» badge instead.

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

The fields you see:

Summary card at the top with company name and VAT with country prefix — confirmation only, not editable.
Recipient email — mandatory. It's the address the invitation email is sent to; it's also saved on the client as contact email if not already present.
Phone — optional with a small helper below: «Address-book detail for loads — not used for the invitation». Leave it empty if you want: the invitation fires only via email anyway.
Optional message — free text that will be included in the body of the invitation email (e.g. «Hi Mark, we've moved to Truckscanner: here's the link to access your shipments»).

When you click «INVIA INVITO» the email is sent and the dialog changes: the form fields disappear and a green confirmation banner shows up with the recipient email, a hint for manual link sharing, and the input with the registration link pre-filled with your inviting VAT. There's also a copy icon to put it in the clipboard.

The «Invite to Truckscanner» dialog after sending: the green banner shows «Email di invito inviata a acquisti@acmelogistics.example» followed by «Puoi anche copiare il link qui sotto e mandarlo manualmente» (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 through other channels

The email fires automatically, but if you prefer to send the link to the client over WhatsApp, Telegram, Slack or even print it on a sheet, you can do that. The link is 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

Closing the dialog with «OK», the client's Truckscanner column changes in real time:

The «COLLABORA SU TRUCKSCANNER» button disappears, replaced by the orange «Invitato» badge.
Next to the badge, three little icons appear letting you manage the invitation while it's still pending.

The table after sending the invitation: the counters at the top show «Tutti 3, Registrato 2, Invitato 1, Non invitato 0». On the ACME Logistics row, in the Truckscanner column, the block with the orange «Invitato» badge followed by three little icons is highlighted (1): copy invite link, paper-plane reinvite, X cancel.

The three icons do this:

Copy invite link (clipboard icon) — copies the same link you saw in the confirmation banner to the clipboard. Toast «Link copiato».
Resend invite (paper plane icon) — resends the same NC-A04 email to the same address, useful if the client didn't receive the first one or if it landed in spam. Toast «Invito reinviato con successo».
Cancel invite (X icon) — removes the pending invite. The client record stays in the address book as «Non invitato», you can send a new invitation whenever you want. Toast «Invito rimosso».

The «Invitato» tab counter updates in real time as soon as you click one of these actions — it's the same fix we applied for client creation.

When the client accepts the invitation and completes registration, the status automatically moves to «Registrato» (green badge) and the record is linked to their Truckscanner account: from then on you share with them the shipments they're involved in as sender or recipient.

What happens behind the scenes on Truckscanner

Sending the invitation triggers several things behind the scenes:

A row is created in client_relationships with INVITED status, a unique token for the registration link and invited_at timestamp.
The NC-A04 — Client invitation notification fires towards the recipient email via SMTP. It's a direct notification (it doesn't go through the general 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 you later use this client as sender or recipient of a load and the load events progress (pickup confirmed, delivered, problem), operational notifications fire by email to the client's address — provided the client's «Email Notifications» toggle is on. WhatsApp and SMS notifications are wired but in rollout: 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 consignor receives

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

What the other side sees

Shipper

The consignor receives an email with subject «Sei stato invitato su Truckscanner da {forwarder name}». In the body they find a personalized greeting with their company name, the line «{forwarder} ti ha invitato a unirti alla piattaforma Truckscanner come committente», a list of the three main benefits (monitor shipments in real time, manage contracts and documents, see warehouse and site status) and the lime «REGISTRATI COME COMMITTENTE» button.

The email button opens the client registration flow with your forwarder name and VAT already pre-filled in the form: the consignor doesn't have to look you up, they find you already linked. When they complete registration, your row's status in the table becomes «Registrato» and the client sees their consignor dashboard with the shipments they're involved in.

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

Client «in address book» vs client «collaborator»

An important distinction that often confuses people at first: a client in the address book is not automatically an active collaborator on Truckscanner.

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

The two coexist: every client is first «in the address book» and then optionally becomes «collaborator». The «Collabora su Truckscanner» button is the transition between the two states. You can suspend or remove the platform relationship at any time from the detail drawer without losing the client in the address book.