The import of company data is a foundational step in populating a Qargo tenant. This process facilitates the bulk creation of customers, suppliers, and subcontractors, and is a prerequisite for the import of contacts and subcontractor resources. This article outlines the specific requirements and best practices for a successful company data import.
📖 Glossary of Key Terms
For clarity throughout this guide, the following terms are defined.
Company: An overarching term for any business entity managed within Qargo, including customers, suppliers, and subcontractors.
Customer: A company that receives services and is invoiced for them.
Subcontractor: A company that provides transport services to a Qargo user.
Accounting Code: A unique identifier from an external accounting system used to link a company in Qargo to its corresponding entry in the other system. This is a critical field for data synchronisation.
Active/Inactive: The status of a company within Qargo. An 'inactive' company remains in the database but cannot be used in new orders or assignments.
✅ Critical Import Requirements for Companies
Prior to importing company data, the following requirements and warnings must be considered to ensure data integrity.
Accounting Code for Updates: The Accounting Code is the unique identifier used by Qargo to recognise and update an existing company. If a company is re-imported without an Accounting Code, or with a different one, a duplicate entry will be created. It is imperative that accounting codes are 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.
Subcontractors: Before resources such as drivers or vehicles can be imported for a subcontractor, the subcontractor must first be created as a company in Qargo.
🛠️ Step-by-Step Data Import Process
The following steps should be followed to successfully import company data.
Step 1: Download Template
A specific Excel template is available to upload Company data:
📚 Always use a blank template downloaded directly from the Qargo platform or provided by the Qargo team. Re-using an old template may lead to import errors.
Step 2: Fill in the Excel Template
Open the template and populate it with the required data. The template contains column headers that correspond to the fields in Qargo.
Required Fields: Make sure to fill out all the required fields (a comprehensive list of required fields can be found in the next section of this article). An import will fail if these fields are left blank.
Formatting: Close attention should be paid to the specified data format (e.g., dates, numbers, text).
Step 3: Submit for Upload
During Onboarding: Work directly with your onboarding manager to upload your initial business data. They will guide you through the process and ensure a successful import.
After Onboarding: For all future data updates and imports, contact your account manager. They will assist you with the upload process and provide ongoing support.
📝 Details of the Company Import Template
The following table provides a detailed, field-by-field explanation of the Excel template for company import, including data formats, required fields, and best practices for populating each column.
Column name | Required/optional | Remarks | Example |
name | Required | Customer name to be used in the application | Qargo |
vat_number | Optional | customer's VAT 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 subcontractor | TRUE or null |
archived | Optional | To import archived (not longer in use) customers | TRUE or null |
customer_status | Optional |
|
|
subcontractor_status | Optional |
|
|
note | Optional | Extra textual information regarding the customer. Usually this contains interesting information that is not part of one of the other categories described here. |
|
website | Optional | Website of the customers | |
payment_term | Optional | To derive from the default customer payment_term |
|
subcontractor_payment_term | Optional | To derive from the default subcontractor payment_term |
|
currency | Optional |
| EUR |
tax_type | Optional | To derive from the default tax_type. Tax_type is by default auto selected using vat_number. |
|
locale | Optional |
|
|
address | Required | street + number + eventual bus number | Gaston Crommenlaan 4 |
address_second_line | Optional |
|
|
city | Required |
| Gent |
postal_code | Required |
| 9050 |
country | Required |
| Belgium |
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. Remark: 2 underscores are used in the column name. |
|
has_customer_portal_access | Optional |
|
|
has_subcontractor_portal_access | Optional |
|
|
extra_fields__credit_limit_invoiced | Optional |
|
|
🔎 Troubleshooting Common Company Import Errors
This section addresses specific errors that may arise during the import of company data.
Missing or Incorrect Accounting Codes: This is the most common cause of duplicate companies. The system relies solely on the Accounting Code for updates. A missing or changed code will result in a new record being created.
Invalid Data Format: Ensure that all fields adhere to the required format. For example, country codes must be valid and accurately entered. A descriptive list of the errors and their locations will be added to the first column of the Excel sheet.
Unusual Characters: Unrecognised special characters in a company name or address can cause an import to fail. It is important to review the data for any such characters.
Customer/Subcontractor Classification: Company must be classified as either a customer or a subcontractor by setting the corresponding column to ‘True’. A company can be both only if the Enforce separate subco/customer organisation 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 organisation’s currency settings.
Address Fields: The Country field requires a two-letter code (e.g., GB, not “UK”). You can see this list for Alpha-2 code.
Sheet name: The sheet name in the Excel template file must be named exactly 'Import'. Any other name will cause an error when uploading the file.
Custom Fields: The column name must follow the convention custom_field__[ID] (don't forget to keep the 2 underscores), with the specific ID retrieved from the Qargo organisation settings. Click the copy button next to the custom field to copy its ID:
✨ Best Practices for Importing Companies
To ensure a smooth and accurate import, consider the following best practices.
Clean Your Data: Before beginning the import process, it is important to review the source data for accuracy and consistency. This includes checking for duplicate records or inconsistencies in company names.
Start with a Small Batch: It is recommended to test the import process with a small sample of 5-10 companies first. This allows for verification 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 successfully imported, the foundation for further data population has been established. The next logical steps include:
Importing Contacts: Contacts can now be imported and correctly linked to the corresponding companies.
Importing Subcontractor Resources: If required, the drivers and vehicles for subcontractors can now be imported and associated with the company records that have been created.
📈 Use Cases for Company Import
Company import is an invaluable tool for several key business processes:
Initial Tenant Setup: The primary use case involves importing an organisation's entire customer and subcontractor database during the initial setup of a Qargo tenant, thereby ensuring 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 new data.