Import organizations and contacts
This article lists the columns you can use when you import organizations and contacts from a CSV file, and how Kompass decides whether a row updates an existing record or adds a new one. For how the Import dialog works, see Import records from a CSV file. Developers using the API can find the same columns in the API reference.
Where to import
Open Organizations or Contacts, choose Actions, then Import.
How rows are matched
- Organizations: a row with an
idupdates that organization. Otherwise Kompass looks for an organization with exactly the samename, including capital letters. A row that matches nothing adds a new organization. - Contacts: a row with an
idupdates that contact. Otherwise Kompass looks for a contact of the same organization (client_idorclient_name) with exactly the same first name, last name and email address. A row that matches nothing adds a new contact.
Reading the column tables
Required marks a column a new record needs. A row that updates an existing record only changes the columns in your file, so you can leave the others out. Finds the record marks a column Kompass uses to find the existing record a row updates. Column names must match exactly, including underscores. Where a column only takes certain values, the description lists them. A column marked Needs an extra permission is only accepted from users who have that permission; for anyone else the import reports it as an unknown column. The Download template button in the Import dialog gives you the header row for your own permissions.
Clients
| Column | Required | Finds the record | Description |
|---|---|---|---|
id |
No | Yes | Kompass ID of the record to update. When empty, the row adds a new record unless its other columns match an existing one. |
address_country |
No | No | Two-letter country code, such as GB or US, or the country name. Required for new clients. |
address_line1 |
No | No | Street address line 1. Required for new clients. |
address_line2 |
No | No | Street address line 2. |
address_postal_code |
No | No | Postal or ZIP code. |
address_state |
No | No | State, province, or region. |
address_town |
No | No | City or town. |
category_id |
No | No | Kompass ID of the client category. Or use category_name. |
category_name |
No | No | Client category name, as shown in Kompass. |
email |
No | No | Client's primary email address. |
entity_type |
No | No | O for an organization, P for a person. Accepted values: O, P. |
inactive |
No | No | Date the client became inactive, such as 2026-01-31. Leave empty for an active client. |
manager_email |
No | No | Email address of the Kompass user who manages this client. |
merge_client_ids |
No | No | Kompass IDs of other clients to merge into this one, separated by commas (put the cell in quotes). Needs an id on the row and permission to merge clients. Their contacts, projects, invoices, payments, sales orders and comments move to this client, then the merged clients are deleted for good. |
name |
No | Yes | Client name. Without an id, a client with exactly this name is updated. |
notes |
No | No | Internal notes about the client. |
org_id |
No | No | Kompass ID of the Kompass organization the client belongs to. New clients need this or org_name. |
org_name |
No | No | Name of the Kompass organization the client belongs to. New clients need this or org_id. |
person_contact_id |
No | No | Kompass ID of the contact to use as the person when changing a client from organization to person. Needed when the client has more than one contact. |
phone |
No | No | Main phone number, in any format. |
tags |
No | No | Tag names separated by commas, or a list in square brackets such as ["Design, Build"] for a name that contains a comma. The record gets exactly these tags; an empty cell removes them all. |
type_id |
No | No | Kompass ID of the client type. Or use type_name. |
type_name |
No | No | Client type name, exactly as shown in Kompass. |
udf |
No | No | Custom field values for each Kompass organization ID, such as {"1": {"region": "North"}}. Leave the column out to keep the current values. |
website |
No | No | Client's website URL. |
created |
No | No | Date the record was created, such as 2026-01-31. Leave empty to use today's date on a new record; an update keeps the stored date. Needs an extra permission. |
modified |
No | No | Date the record was last changed, such as 2026-01-31. Leave empty to use today's date. Needs an extra permission. |
Contacts
| Column | Required | Finds the record | Description |
|---|---|---|---|
id |
No | Yes | Kompass ID of the record to update. When empty, the row adds a new record unless its other columns match an existing one. |
address_country |
No | No | Two-letter country code, such as GB or US, or the country name. |
address_line1 |
No | No | Street address line 1. |
address_line2 |
No | No | Street address line 2. |
address_postal_code |
No | No | Postal or ZIP code. |
address_state |
No | No | State or province. |
address_town |
No | No | City or town. |
client_id |
No | Yes | Kompass ID of the client the contact belongs to. Or use client_name. |
client_name |
No | Yes | Name of the client the contact belongs to. Or use client_id. |
email |
No | Yes | Email address of the contact. |
first_name |
Yes | Yes | First name of the contact. |
inactive |
No | No | Date the contact became inactive. Leave empty for an active contact. |
last_name |
No | Yes | Last name of the contact. |
notes |
No | No | Additional notes about the contact. |
opt_out |
No | No | Date the contact opted out of emails and mailings. |
phone_mobile |
No | No | Mobile phone number. |
phone_office |
No | No | Office phone number. |
position |
No | No | Job title or position. |
source_details |
No | No | More about the source, such as who referred them. |
source_name |
No | No | How the contact found you, such as Referral or Website. |
tags |
No | No | Tag names separated by commas, or a list in square brackets such as ["Design, Build"] for a name that contains a comma. The record gets exactly these tags; an empty cell removes them all. |
title |
No | No | Title, such as Mr, Mrs or Dr. |
udf |
No | No | Custom field values for each Kompass organization ID, such as {"1": {"region": "North"}}. Leave the column out to keep the current values. |
created |
No | No | Date the record was created, such as 2026-01-31. Leave empty to use today's date on a new record; an update keeps the stored date. Needs an extra permission. |
modified |
No | No | Date the record was last changed, such as 2026-01-31. Leave empty to use today's date. Needs an extra permission. |