Learn Mokapen

Import / Export

The Import / Export section lets you bring your data into Mokapen from an Excel or CSV file (import) and download your organization's data as an Excel file (export). It is the fastest way to populate the CRM when you start from existing address books, price lists, or master data, or when you need backups and analysis outside the platform.

You find it from the organization menu → Import/Export. The guided import is step-based (choose what to import, upload the file, map columns, start) and runs in the background: you can follow progress and review the import history.

Overview

Two distinct functions, often used together:

• Import — upload a file (Excel or CSV) and Mokapen creates (or updates) the corresponding records. You can import Projects, Tasks, Contacts, Companies, Products, and Services.
• Export — download your data as an Excel (.xlsx) file. Export covers more record types than import: in addition to those above, also Deals, Quotes, Orders, Tickets, Appointments, and Bookings.

Import is a guided flow in four screens: (1) choose the record type, (2) upload the file, (3) map file columns to CRM fields while setting privacy and duplicates, (4) follow progress and results. There is no separate "preview and confirm" screen: you already see sample values on the column mapping screen.

Access and permissions

The two functions have different permissions:

• Importing — allowed for organization Members. You also find import shortcuts in the Actions menu on Contacts, Companies, Tasks, and Projects lists.
• Exporting — reserved for the organization Owner. The export button on lists and the export page appear only for that role.

Two features depend on the plan:

• Custom fields on import — mapping file columns to your custom fields requires a Premium plan. Without it, you only see standard fields during mapping.
• Advanced duplicate handling — the Insert if empty and Replace options require a Premium plan. On the Free plan, only Skip remains available (duplicates are left unchanged).

Export always respects permissions and privacy: each user exports only the records they can access based on their role and the organization's visibility rules.

How to import (the guided flow)

Import takes four steps:

1. Choose what to import — on the Import page, select the record type: Projects, Tasks, Contacts, Companies, Products, or Services. From here you can also open Import History.
2. Upload the file — drag (or select) a .xlsx, .xls, or .csv file, up to 4 MB maximum. Mokapen reads the columns and moves to mapping.
3. Map columns — for each file column, choose the matching CRM field (or ignore it). On the same screen you set privacy for imported data and, where available, duplicate handling. The import button unlocks only after required fields are mapped.
4. Start and wait for results — import runs in the background: the results screen refreshes every few seconds and shows counters for Processed, Imported, Updated, Skipped, Errors.

Because work runs in a queue, large files may take a few minutes: keep the page open or check Import History again later.

Prepare the file (Excel and CSV)

Import quality depends almost entirely on file quality. Excel is convenient but tricky: dates turning into numbers, leading zeros disappearing, merged cells, formulas carrying errors. Before uploading, prepare the file like this:

• First row = headers — the first row must contain column names (e.g. First Name, Last Name, Email, Phone). These are what you will see in the mapping step.
• One column = one value — do not put "John Smith" in a single column if you want separate First Name and Last Name; keep phone, email, and address in distinct columns.
• No merged cells — merged cells break grid reading. Always use single cells.
• No formulas — formulas slow things down and can cause errors. If you have calculated columns, copy and paste as values before saving.
• Clean empty cells — rows and columns that look empty but contain spaces or leftover formatting confuse reading. Actually delete rows/columns you do not need.
• UTF-8 encoding — to keep accents and special characters (à, è, ç, ü…), save as UTF-8. In Excel: "Save As" → CSV UTF-8, or stay on .xlsx which handles characters well.
• Large files → split them — the limit is 4 MB. With lots of data, split into multiple files and import in batches: it is also easier to spot errors.
• Avoid non-standard formatted characters — decorative symbols, unusual fonts, or exotic formatting may not be read or may be transformed.

On CSV, one extra note: it is plain text with separated values. Mokapen reads UTF-8 and auto-detects the separator; if you open and re-save a CSV with Excel in some locales, the separator often becomes a semicolon — usually fine, but if everything appears in one column after upload, that is almost always the cause: re-save explicitly as "CSV UTF-8" or use a .xlsx file directly.

Map columns

This is the heart of import. For each file column, Mokapen shows the header name and up to six sample values from the first rows, so you quickly understand what it contains. Next to it, choose the matching CRM field from the "Belongs to" menu:

• Map the column to a field (e.g. column "Mail" → Email field).
• Skip column — leave the mapping empty for columns you do not need: they will not be imported.
• Each CRM field can be used only once: once mapped, it disappears from other columns' choices.

You must map at least the required fields, otherwise the import button stays disabled:

• Contacts — at least one of First Name, Last Name, or an email. Rows without any of these are ignored.
• Companies — Company Name.
• Tasks, Projects, Products, Services — Title (or name).

Some fields automatically resolve relations by name: on Contact import, the column mapped to Company links (or creates, if missing) the company with that name; on Task import, the Project column links or creates the project with that title. Matching is case-insensitive.

Custom fields — with a Premium plan, your custom fields also appear in the menu (numbers, text, dates, lists). Dates and currencies are interpreted and normalized; for user/team fields, values are resolved to the correct user or team.

Special field formats

Some fields accept multiple values in one cell or look up a link: when you map them, a yellow notice appears below the column with the expected format. The separator for multiple values is always the semicolon (;).

• Tags — names separated by ";". If a tag does not exist, it is created automatically. E.g. Customer;VIP;Follow up.
• Stakeholders — for each entry use the user's email or the team code with "t" (e.g. t123), separated by ";". E.g. john@email.com;t45.
• Owner — a single value: user email or team code "t{id}".
• Supplier (Products/Services) — the supplier company name; if missing, it is created.
• Images (Products/Services) — full image URLs separated by ";".
• Groups (Products/Services) — names separated by ";"; missing groups are created.

Always read the yellow notice: following that format is what makes the difference between a clean import and one full of missing values.

Manage duplicates

For Contacts, Companies, Products, and Services you can decide what to do when a row matches an existing record. The "Manage duplicates" option is enabled by default. The key Mokapen uses to recognize a duplicate varies by type:

• Contacts — same email (if present in the row).
• Companies — same company name (case-insensitive). Note: companies with the same name are never duplicated when linked from contacts, even if duplicate handling is off.
• Products — same product code.
• Services — same service code.

When a duplicate is found, you can choose three behaviors:

• Skip (default) — ignore new values and continue without saving or updating. The row is counted as Skipped.
• Insert if empty — update a field only if it is currently blank (does not overwrite existing data). Requires Premium.
• Replace — update every mapped field with the new value, regardless of the current value. Requires Premium.

Tasks and Projects have no duplicate handling: every row always creates a new record. Re-importing the same file creates duplicates: think carefully before repeating the operation.

Clean data tips

A few precautions make import reliable and save you painful cleanup afterward:

• Normalize emails — they are the anti-duplicate key for contacts: one email per cell, no spaces, all lowercase. Different emails = different contacts.
• Unique codes for products/services — if you want to update instead of duplicate, make sure product code and service code are present and consistent between the file and what is already in Mokapen.
• Consistent formats per column — do not mix "03/10/2026" and "2026-03-10" in the same date column; use one format. Same for amounts (avoid mixing "1,000.50" and "1000.5").
• Phones with international prefix — e.g. +1…: useful for messaging and integrations, and prevents Excel from treating the number as a digit and eating the leading zero. If needed, set the column as Text.
• Watch leading zeros — ZIP codes, codes, VAT numbers: Excel tends to remove leading zeros. Format those columns as Text before filling them.
• Remove hidden spaces — spaces before/after text (or double spaces) create false non-duplicates. A "Trim spaces" pass in Excel helps.
• Standardize relation names — if you link contacts to companies by name, write the company name the same way every time (e.g. always "Acme Ltd", not sometimes "ACME" and sometimes "Acme L.L.C."), otherwise you create different companies.
• Run a small test — before importing 5,000 rows, try 10–20 representative rows: you verify mapping, formats, and duplicates without risking a messy CRM.

Progress and Import History

During import, the results screen shows real-time counters: Processed (rows read), Imported (new records), Updated (updated duplicates), Skipped (untouched duplicates), and Errors.

The Import History page lists all imports with their totals. Keep two things in mind: history shows aggregate totals, not a row-by-row list; and rows without minimum identity fields (e.g. a contact with no first name, last name, or email) are silently ignored, so they may not appear under "Errors". If numbers do not add up, that is usually the cause.

Export

Export always produces an Excel (.xlsx) file and, as noted, is reserved for the Owner. You can launch it from two places:

• From the Export page (Import/Export menu) — download all records of a type with one click.
• From lists (List, Kanban, card views) — from Actions → Export. In List view, if you select some rows, you export only those; if you select nothing (or you are in Kanban/cards), you export all accessible records.

Some useful details:

• Export includes custom fields and shows tags and stakeholders in readable form (names/emails separated by commas).
• Quotes and Orders are exported on two sheets: one with document headers and one with line items.
• Contact export adds the linked company name and checklist items.
• It always respects permissions and privacy: you export only what you could see on screen.

An exported file is also a great template: export a few records of a type, look at the headers and formats used, and reuse that structure to build your import file.

Use cases

• Initial go-live — import contacts and companies from the old system, then Products/Services price list, and the CRM is immediately operational.
• Price list update — import Products with "Replace" using product code as the key: prices and descriptions update without creating duplicates.
• Contact enrichment — you already have contacts and add missing phones/fields with "Insert if empty": you complete records without overwriting good data.
• Periodic backup — the Owner exports contacts, deals, and orders to Excel for archive or external analysis.
• Custom reporting — export filtered data from a list and process it in Excel with pivot tables for analysis not readily available in the platform.

Common issues

• Import button stays disabled — you have not mapped the required fields (first name/last name/email for contacts, title for others). Complete the mapping.
• After upload everything is in one column — CSV with unrecognized separator or wrong encoding. Re-save as "CSV UTF-8" or use .xlsx.
• Missing accents or strange characters — encoding issue: save as UTF-8.
• Fewer rows imported than expected — rows without minimum identity fields are ignored; check that every row has at least the required field.
• I created duplicates — probably "Manage duplicates" was on Skip when you wanted to update, or the key (email/code/name) did not match. Check keys and the option chosen.
• Tags/suppliers/groups not linked — you did not follow the special field format (separator ";", email for users, "t{id}" for teams). Re-read the yellow notice below the column.
• File too large — exceeds 4 MB: split into multiple files and import in batches.
• I do not see custom fields in mapping — they require a Premium plan.

Frequently asked questions

Q: What files can I import?

A: Excel (.xlsx, .xls) and CSV files, up to 4 MB. The first row must contain column headers.

Q: What can I import and export?

A: Import: Projects, Tasks, Contacts, Companies, Products, and Services. Export also includes Deals, Quotes, Orders, Tickets, Appointments, and Bookings. Deals, quotes, orders, and tickets can therefore be exported but not imported.

Q: Who can import and export?

A: Import is open to organization members; export is reserved for the Owner.

Q: How do I avoid creating duplicates?

A: Keep duplicate handling active and make sure the key is filled and consistent: email for contacts, name for companies, code for products and services. Remember that Tasks and Projects have no duplicate check: every row always creates a new record.

Q: What is the difference between "Skip", "Insert if empty", and "Replace"?

A: Skip leaves the duplicate untouched; Insert if empty fills only currently blank fields; Replace updates all mapped fields. The last two require a Premium plan.

Q: How do I put multiple values in one cell (tags, stakeholders…)?

A: Separate values with a semicolon (;). For stakeholders use the user's email or team code "t{id}"; missing tags, groups, and suppliers are created automatically.

Q: Why were fewer rows imported than in the file?

A: Rows without minimum identity fields (for contacts: first name, last name, or email; for companies: name) are ignored without appearing under "Errors". Check that every row has at least the required field.

Q: Excel ruins dates, leading zeros, and long numbers. What should I do?

A: Format critical columns as Text (ZIP codes, codes, VAT numbers, phones), use one date format per column, and if you have calculated columns, paste as values before saving. Save as UTF-8 to keep accents.

Q: Can I import my custom fields?

A: Yes, with a Premium plan: custom fields also appear in the mapping step and values are converted according to their type (dates, currencies, lists, users/teams).

Q: What format do I get when exporting?

A: Always Excel (.xlsx). Quotes and Orders come on two sheets (headers + line items). An exported file is also a great template for preparing a future import.

Q: Is import immediate?

A: It runs in the background: for a few records it takes seconds; for large files it may take a few minutes. Follow the counters on the results screen or check Import History again.