How to import contractors from a CSV or Excel file into KSeFGPT
Upload a CSV, XLS, or XLSX file with your contractor list, review the automatic column mapping, and confirm the import. The new records then appear in the Contractors list.
- Module
- Contractors
- Reading time
- 5 min
- Difficulty
- You could do this with your eyes closed :)
- Published
- August 21, 2026
- Author
- Rafał Zeidler
- Format
- Written guide and video
Written procedure
What you will do
You will upload one file with a contractor list to KSeFGPT, review how the application matched the file columns to contractor fields, and confirm the import. At the end you will see the imported companies in the Contractors list.
The example in this guide uses a CSV file where five rows have a company name and one row does not. That row is left out of the import, so the preview reports five records and one skipped row.
Requirements
Before you start
The import runs in the context of the selected company. The contractors are saved to the company that is active when you confirm the import.
| Item | Requirement |
|---|---|
| Access | The company owner or an organization member with access to the Contractors module. The module must be included in the plan. |
| Required file | One XLSX, XLS, or CSV file. The application reads the first sheet and treats its first row as the column headers. |
| Required column | The contractor name. A row without a company name is skipped and does not appear in the preview. |
| Recognized fields | name, nip, regon, street, city, postal_code, country, email, phone, bank_account, bank_name, and notes. Any other column becomes a custom field on the contractor record. |
| Starting point | After signing in, select the correct company and open Contractors. |
| Time required | About 2 minutes for a file with a few dozen rows. |
| Important effect | An account can hold only one contractor per NIP number. A row with a number that is already stored is not added again. |
Process recording
The recording shows the file upload, the mapped columns, the import confirmation, and the new records in the contractor list.
Open the Contractors module
Select Contractors in the main menu. Check in the menu footer that the active company is the one you want to load the data into.
You will see the contractor list of that company and the Import contractors and Add Contractor buttons in the top right corner.
Open the import dialog
Select Import contractors. The Import contractors dialog opens with the description Import contractors from XLSX/CSV file.
The dialog shows an upload area labelled Click to select file and the list of supported extensions: XLSX, XLS, CSV.
Select the contractor file
Select the upload area and pick the file from your disk. The application starts processing it immediately and the dialog shows Processing file...
At this stage KSeFGPT reads the headers and data from the first sheet and matches the columns to contractor fields. Empty rows are skipped.
Review the mapped columns and the data preview
Once the file is processed, the dialog shows the Mapped columns section. Every label uses the format file header → contractor field, for example Company name → name or Postal code → postal_code.
A column that does not match a standard field receives its own key, and after the import you will find it in the custom fields of the contractor record. In the example, the Category column becomes the category key.
Below that is a preview of the first ten rows with the name, NIP, city, and email address, and under the table a Found counter with the number of records. If the file contained rows without a name, the counter is followed by a skipped note.
Check that the company name and the NIP landed in the correct columns. If the match is wrong, select Back, fix the headers in the file, and upload it again.
Confirm the import
Select Import. The button shows the number of records to be saved in brackets, for example Import (5). While the records are saved the button shows Importing...
When it finishes, the dialog shows Import complete and an Imported line with the number of saved records. The same number is confirmed by the notification in the top right corner of the screen.
Final state
Check the result
Select Close. The contractor list refreshes automatically and shows the new records with the name, NIP, address, email address, phone number, and the Active status.
Open one of the imported records to confirm the remaining data. Values from columns outside the standard field list are stored in the Custom fields section.
Diagnostics
If something does not work
Compare the visible symptom with the table below.
| Symptom | Likely cause | What to do |
|---|---|---|
| You cannot see the Import contractors button | The plan does not include the Contractors module, or the organization member account has no access to it. | Check the plan or ask the organization owner for access to the Contractors module. |
| An Import error message appears after the upload | The file could not be read, for example it has an unsupported extension, it is damaged, or the first sheet is empty. | Save the data again as XLSX, XLS, or CSV, make sure the first sheet has a header row, and upload the file once more. |
| The preview shows fewer records than the file has rows | Rows without a contractor name are skipped, and so are completely empty rows. | Fill in the company name column in the source file and repeat the import for the missing rows. |
| A column landed in the wrong field | The header was unclear or misleading, so the automatic match picked a different field. | Select Back, rename the header in the file to something unambiguous such as Company name, NIP, or Postal code, and upload the file again. |
| Fewer records were imported than the preview reported | A NIP number from the file was already stored on the account. An account can hold only one contractor per number. | Check the list for the existing contractor and remove the duplicate rows from the file before the next import. |
| The contractors were saved to another company | A different company was active when the import was confirmed. | Check the company name in the menu footer, switch to the correct one, and repeat the import. |
What next
Complete the imported records with data that was not in the file. The guide on adding custom fields to a contractor shows how to store your own name and value pairs.
If you need a single record instead of a full list, use the guide on adding a new contractor in KSeFGPT.
Load your contractor database
Sign in, open Contractors, and import your list from a CSV or Excel file.
Related instructions
How to edit contractor details in KSeFGPT
Open an existing contractor record, correct its address, contact and bank details, then verify the saved values after reopening the form.
How to add custom fields to a contractor in KSeFGPT
Open an existing contractor record, add your own name and value pairs, and verify them after reopening the form. The example uses a BDO number and an internal customer number.
How to add a new contractor in KSeFGPT
Create a contractor record, fetch details from GUS or enter them manually, and check the new entry in the list. When a PDF invoice import is completed by sending the invoice to KSeF, a new buyer can be saved automatically.