Skip to main content
Qargo

Data import – importing company data

A comprehensive guide to importing company data, which is the foundational step for populating a Qargo tenant with customers, suppliers, and contract carriers.

Table of contents
  1. 📖 Key terminology
  2. ✅ Critical import requirements for companies
  3. 🛠️ Step-by-step data import process
  4. Step 1: Download the template
  5. Step 2: Fill in the Excel template
  6. Step 3: Submit for upload
  7. 📝 Details of the company import template
  8. 🔎 Troubleshooting common company import errors
  9. 📈 Use cases for company import

The import of company data is a foundational step in populating a Qargo tenant. This process supports the bulk creation of customers, suppliers, and contract carriers. It is also a prerequisite for importing contacts and contract carrier resources. This article outlines the specific requirements and best practices for a successful company data import.


📖 Key terminology

The following terms are defined for clarity throughout this guide.

  • Company: An overarching term for any business entity managed in Qargo, including customers, suppliers, and contract carriers.
  • Customer: A company that receives services and is invoiced for them.
  • Contract carrier: A company that provides transportation services to a Qargo user.
  • Accounting code: A unique identifier from an external accounting system. It links a company in Qargo to its corresponding entry in the other system. This is a critical field for data synchronization.
  • Active/inactive: The status of a company in Qargo. An “inactive” company remains in the database but cannot be used in new orders or assignments.

✅ Critical import requirements for companies

Before importing company data, consider the following requirements and warnings to ensure data integrity.

  • Accounting code for updates: Qargo uses the Accounting code as the unique identifier to recognize and update an existing company. If a company is re-imported without an accounting code, or with a different one, a duplicate entry is created. Accounting codes must be consistent across all imports for a given company.
  • Prerequisite for contacts: A company record must exist in Qargo before a contact can be linked to it. The contact import template requires a valid company name and accounting code.
  • Contract carriers: A contract carrier must first be created as a company in Qargo before resources such as drivers or vehicles can be imported for it.

🛠️ Step-by-step data import process

Follow these steps to successfully import company data.

Step 1: Download the template

A specific spreadsheet template is available for uploading company data. To edit and upload the data, a copy of the template must be downloaded:

  1. Click the link: Company data import template
  2. Once the template opens, go to File and select Download
  3. Save the template (in .xlsx or .csv format) to a computer and begin entering the company data.

Step 2: Fill in the Excel template

Open the template and fill it in with the required data. The template contains column headers that correspond to the fields in Qargo.

  • Required fields: Fill out all required fields (a complete list of required fields is in the next section of this article). An import fails if these fields are left blank.
  • Formatting: Pay close attention to the specified data format (e.g., dates, numbers, text).

Step 3: Submit for upload

  1. During onboarding: Work directly with the onboarding manager to upload the initial business data. The onboarding manager provides guidance through the process and ensures a successful import.
  2. After onboarding: For all future data updates and imports, contact the account manager. The account manager assists with the upload process and provides ongoing support.

📝 Details of the company import template

The following table explains the Excel template for company import field by field. It includes data formats, required fields, and best practices for filling in each column.

Column name Required/optional Remarks Example
name Required Customer name to be used in the application Qargo
vat_number Optional Customer’s tax number (no specific format is enforced) BE1234567890
accounting_code Required Unique ID 134
legal_name Required Legal customer name to put on official documents Qargo Tech NV
iban_code Optional
bic_code Optional
is_customer Required If TRUE, will be created as a customer TRUE or null
is_subcontractor Required If TRUE, will be created as a contract carrier TRUE or null
archived Optional To import archived (no longer in use) customers TRUE or null
customer_status Optional
subcontractor_status Optional
note Optional Extra text information about the customer. This usually contains useful information that does not belong to any of the other categories described here.
website Optional Website of the customer www.qargo.io
payment_term Optional To derive from the default customer payment_term
subcontractor_payment_term Optional To derive from the default contract carrier payment_term
currency Optional EUR
tax_type Optional To derive from the default tax_type. By default, tax_type is selected automatically based on vat_number.
locale Optional
address Required Street + number + suite/box number, if any Gaston Crommenlaan 4
address_second_line Optional
city Required Gent
postal_code Required 9050
country Required The Country field requires a two-letter code (e.g., GB, not “UK”). See this list for Alpha-2 codes. BE
state Optional
factoring_code Optional
contacts__name Use contacts import instead Use contacts import instead Use contacts import instead
contacts__email Use contacts import instead Use contacts import instead Use contacts import instead
contacts__phone Use contacts import instead Use contacts import instead Use contacts import instead
extra_fields_billing_frequency Optional
custom_fields__example Optional To import custom field values. Note: the format uses a double underscore (__) to connect the prefix custom_fields to the unique field ID
has_customer_portal_access Optional
has_subcontractor_portal_access Optional
extra_fields__credit_limit_invoiced Optional

🔎 Troubleshooting common company import errors

This section covers specific errors that may occur when importing company data.

  • Missing or incorrect accounting codes: This is the most common cause of duplicate companies. The system relies only on the accounting code for updates. A missing or changed code results in a new record being created.
  • Invalid data format: Make sure all fields follow the required format. For example, country codes must be valid and entered accurately. A descriptive list of the errors and their locations is added to the first column of the Excel sheet.
  • Unusual characters: Unrecognized special characters in a company name or address can cause an import to fail. Review the data for any such characters.
  • Customer/contract carrier classification: Each company must be classified as either a customer or a contract carrier by setting the corresponding column to “True”. A company can be both only if the Enforce separate subco/customer organization setting is disabled.
  • Currency: Leave this field empty for tenants with a single currency. For multi-currency tenants, the field must contain a specific code (e.g., GBP, EUR) that matches the organization’s currency settings.
  • Address fields: The Country field requires a two-letter code (e.g., GB, not “UK”). See this list for Alpha-2 codes.
  • Sheet name: The sheet in the Excel template file must be named exactly ‘Import’. Any other name causes an error when the file is uploaded.
  • Case-sensitive column headers: Column headers must be entered with the correct casing (e.g., vat_number, not VAT_number). Incorrect casing causes the data in that column to be silently ignored and not imported, because the system does not recognize the header.
  • Leading apostrophe errors: Data in a cell cannot begin with an apostrophe (’). If an apostrophe is used, the system does not recognize the value, and an error may occur. This rule is waived only if the article explicitly states that an apostrophe should be used for a specific field.
  • Custom fields: The column name must follow the convention custom_field__[ID] (keep the double underscore that connects the prefix custom_field to the unique field ID). Retrieve the specific ID from the Qargo organization settings. Click the copy button next to the custom field to copy its ID:


✨ Best practices for importing companies
Consider the following best practices to ensure a smooth and accurate import.

  • Clean the data: Before starting the import process, review the source data for accuracy and consistency. This includes checking for duplicate records or inconsistencies in company names.
  • Start with a small batch: Test the import process with a small sample of 5–10 companies first. This makes it possible to verify that the data is formatted correctly before uploading a full database.
  • Always use a new template: For each import, always use a blank template downloaded directly from the Qargo platform. Reusing an old template may lead to import errors.

➡️ What to do next
Once companies have been imported successfully, the foundation for further data population is in place. The next logical steps include:

  • Importing contacts: Contacts can now be imported and correctly linked to the corresponding companies.
  • Importing contract carrier resources: If required, the drivers and vehicles for contract carriers can now be imported and associated with the company records that have been created.

📈 Use cases for company import

Company import is a valuable tool for several key business processes:

  • Initial tenant setup: The primary use case is importing an organization’s entire customer and contract carrier database during the initial setup of a Qargo tenant. This ensures a swift transition.
  • Accounting system migration: When migrating from one accounting system to another, a clean, complete database of companies can be imported to ensure consistency and prevent data duplication.
  • Adding a new division: When a new business unit or division is introduced, its associated customers and suppliers can be imported in a single action to populate the Qargo system with the new data.