Add and invite a carrier

When you need a new carrier in your Truckscanner network, you always start from the same door: the «Add carrier» dialog. You just type the VAT number and the system does the rest — checks the official registries, recognises whether the carrier is already on the platform or in your network, and automatically proposes the right path: add them with one click, send an email invitation, or warn you about a duplicate.

Forwarder

What you'll find on this page

The «Add carrier» dialog step by step: where it lives, how it behaves depending on the VAT number you type (carrier already in network, carrier already on Truckscanner, carrier to invite), what the guaranteed reference that skips document onboarding means, what the NC-A03 invitation email contains, and which actions you can perform on the «Invited» row in the carriers table after sending.

Where the dialog lives

From the left menu, «Operational & Transport» group, «Carriers» entry. In the top right of the page header, next to «⤴ IMPORT CSV», you'll find the lime button «+ ADD CARRIER». The direct URL is /company/{companyId}/network.

Clicking the button opens the «Add carrier» dialog with the subtitle «Manage the carriers in your network». It welcomes you with just two fields: «Country» (default IT — Italy) and «VAT number» (placeholder 12345678901).

The «Add carrier» dialog just opened: header with network icon and title, subtitle «Manage the carriers in your network», Country select set to «IT — Italy» and VAT number field with placeholder «12345678901», «CANCEL» button at the bottom

VAT verification: VIES + public registries

As soon as the VAT number you're typing reaches 5 characters, the dialog kicks off the search: 1 second debounce to avoid a request per keystroke, then it queries in parallel:

The carrier database on Truckscanner — searches that VAT among the carrier companies registered on the platform.
The European Union VIES system — checks the validity of the VAT number against the official EU register.
Italian public registries (OpenAPI XX-start) — retrieves company name, registered office address, tax code, ATECO code, incorporation data.

Depending on what it finds, the dialog displays one of three paths: carrier already in your network (error), carrier already registered on the platform (direct add), or carrier to invite by email (invitation form + enriched data).

Path 1: the carrier is already in your list

If the VAT number you typed matches a carrier already in your network (with any status: Active, Invited, or Suspended), the dialog tells you immediately with a red message under the fields: «This carrier is already in your list». The only available button is «CANCEL» — you can't add the same carrier twice.

The «Add carrier» dialog with VAT «00488410010» of a carrier already in the network: Country and VAT number fields filled in, below the red message «This carrier is already in your list» and «CANCEL» button at the bottom

If that looks strange (e.g. you remember removing it) close the dialog and search that VAT from the page «Search» bar, or activate the «Suspended» tab to check whether it has been suspended after a report.

Path 2: the carrier is already on Truckscanner but not in your network

This happens often: the carrier exists on the platform — maybe they collaborate with another forwarder in the network — but they're not yet in yours. The dialog notices and offers to add them directly, without going through the email invitation.

You see a green card with:

check icon + title «This carrier is already registered on the platform»,
hint line «You can add them directly to your network»,
carrier company name (with company icon),
email of the carrier admin (with envelope icon) so you can recognise them.

Below the card you'll find the «We vouch, skip verification onboarding» checkbox and a «Note...» textarea, and at the bottom the buttons «CANCEL» + «ADD TO NETWORK» (lime).

The «Add carrier» dialog with VAT «03031930351»: green card «This carrier is already registered on the platform» with subtitle «You can add them directly to your network», carrier name «DL Trasporti S.r.l.» with company icon, admin email «superadmin@truckscanner.ai», below the «We vouch, skip verification onboarding» checkbox and «Note...» textarea, «CANCEL» and «ADD TO NETWORK» buttons

By clicking «ADD TO NETWORK» the carrier joins your network in «Active» status immediately — there's no invitation to accept, they already exist with their own account. Green confirmation toast and the page refreshes. The carrier will appear in the table right away and you can assign mandates to them.

Path 3: the carrier is not on Truckscanner yet — email invitation

If the VAT is not in either database, the dialog switches to invitation mode. Below the VAT field one of two VIES lookup outcomes can appear:

Green banner «VAT number verified on VIES + public registries — COMPANY NAME» (with check icon) — VIES has confirmed that the VAT exists and the Italian registries have returned the basic data. Company name and legal address are pre-filled in the form.
Grey info banner «VAT number not found on public registries. Fill in the details manually to send the invitation.» — VIES or the registries didn't find a match (non-EU VAT, or terminated, or service temporarily unavailable). You fill in the details manually.

In either case the full invitation form appears: Company name, Legal address (Google autocomplete field), Contact (Name, Email, Phone with +39 prefix), Note.

The «Add carrier» dialog with full invitation form: VAT «78080201067», grey banner «VAT number not found on public registries. Fill in the details manually to send the invitation.», Company name «Acme Logistics Ltd.», Legal address with placeholder «Search an address or type it manually...», Contact «Mario Rossi», email «docs+en@acme.example», Phone with +39 prefix, Note textarea, lime checkbox «We vouch, skip verification onboarding» checked, amber warning «The carrier will be activated immediately without the obligation to enter all professional documents, drivers, and vehicles. Are you sure you vouch for this company?», «CANCEL» and «SEND INVITATION» buttons

The pattern is exactly the same as the «New client» dialog in the Clients section: same live lookup, same Google Maps autocomplete, same pre-population behaviour. All fields stay editable — if the registries returned a slightly wrong value, you fix it by hand.

The guaranteed reference: what changes if you activate it at invitation time

Below the form you'll find the «We vouch, skip verification onboarding» checkbox. When you activate it, an amber warning appears below:

⚠️ The carrier will be activated immediately without the obligation to enter all professional documents, drivers, and vehicles. Are you sure you vouch for this company?

In practice, when the carrier completes registration by clicking the link in the NC-A03 email, the backend will skip the «PENDING» phase (uploading company extracts, transport licences, third-party liability insurance, drivers, vehicles) and bring them straight to verification_status = ACTIVE — operational from minute zero. This is what registration_service.py calls the recommended flag, saved on the CompanyNetwork relationship at join time (recommended = true → verification_status = ACTIVE).

When to activate the guaranteed reference

Only if you know the company personally and would vouch for them. The platform trusts your declaration: you are saying «no need to verify the company extract, transport authorisation, civil liability insurance, or CMR — I vouch». The carrier arrives directly operational and can receive mandates immediately. If you have even the slightest doubt about the carrier's qualifications, leave the flag off: they will upload their documents, the Truckscanner team will verify and enable them through the standard pipeline.

The invitation email (NC-A03)

When you click «SEND INVITATION» the backend generates a single-use token, saves it on the CompanyNetwork relationship, and sends a transactional email to the recipient via SES/SMTP.

The email subject is «{forwarder_name} has invited you to Truckscanner». The body includes:

personalised greeting Hi {invite_name},,
highlighted line «{forwarder_name} has invited you to join Truckscanner as a carrier in their network» (the sender forwarder name appears in bold),
three-bullet benefits list (receive load offers directly, manage your fleet and drivers, communicate in real time with forwarders),
lime CTA button «JOIN TRUCKSCANNER» that points to /register/carrier?ref={token} with the VAT / company name / address fields already pre-filled,
info-panel 📞 «Save our number» with Leo's phone number (+39 0522 1770399) to save in the address book to recognise the call coming from our AI dispatcher,
footer note about the link validity.

What happens after sending

Right after clicking «SEND INVITATION», the dialog changes state and shows:

green banner with the toast «Invitation sent to {email}»,
the invitation link URL in a read-only input with a copy icon next to it, useful if you want to send the link via WhatsApp / Telegram / chat to the carrier contact (in addition to the email that has already been dispatched),
«OK» lime button that closes the dialog.

The «Add carrier» dialog after sending the invitation: green card «Invitation sent to docs+en@acme.example», below a read-only input with the registration link `http://localhost:3000/register/carrier?ref=...` and a copy icon on the right, lime «OK» button at the bottom

The freshly invited carrier appears immediately in the «Carriers» table, «Invited» filter, with status Invited and — if you activated the guaranteed reference — a check icon in the Recommended column.

The three icons on the «Invited» row

Until the invited carrier completes registration (status Invited), three icons appear next to the status badge to let you manage the invitation without reopening the dialog:

📋 Copy invitation link — copies the URL /register/carrier?ref={token} to the clipboard so you can paste it anywhere.
✈ Resend invitation — resends the NC-A03 email to the contact (useful if they didn't receive it or lost it).
✕ Remove carrier — cancels the invitation: the row disappears from the table and the token becomes invalid.

The «Carrier network» page with the «Invited» tab active and one row in «Invited» status: next to the amber «Invited» badge, three icons in sequence — copy icon (Copy invitation link), paper plane icon (Resend invitation), and X icon (Remove carrier); the row also shows the green tick in the Recommended column

The same three actions are also available inside the carrier's detail drawer (click the row to open it): you'll find three labelled buttons COPY INVITATION LINK, RESEND INVITATION, REMOVE.

What the other side does — the recipient carrier

When the contact clicks «JOIN TRUCKSCANNER» in the email, they land on the public landing /register/carrier?ref={token} with a 5-step registration wizard: Company → Goods → Vehicles → Zones → Account. The first step has VAT, company name, and address already pre-filled thanks to the data you entered in the dialog (and the VIES + registries enrichment).

If you activated the guaranteed reference, at the end of registration the carrier lands directly on the operational dashboard home (vehicles/drivers KPI, calendar, recent activity). If not, they land on the pending onboarding home with a checklist of documents to upload and the 4 network benefits.

What the other side sees

Carrier

For the full detail of what the carrier sees when opening the link — 5-step wizard, pre-filled fields, and the difference between PendingCarrierHome (reference disabled) and ActiveHome (reference enabled) — see the carrier-side guide Accept a forwarder invitation.