People, contacts and companies

Three concepts here look similar and are not. Getting them straight saves a lot of confusion later.

Contact

A contact is a card in one of your address books. It holds a name, emails, phone numbers, an organisation, an address. It syncs over CardDAV, so it is the same card your phone shows — see CalDAV and CardDAV sync.

A contact belongs to you. Two people on the instance who both know the same person each have their own card, with their own notes and their own phone number for them.

Managed in Contacts.

Person

A person is the shared identity behind contacts. When your card and a colleague's card refer to the same human, both point at one person record.

You mostly do not touch it. It shows up when you follow a link to someone whose card you do not have: instead of a dead end you get the shared person, and if you do have your own card for them, Kancil sends you there instead.

A person is created the first time a contact is linked to something, so a contact you have never linked has no person behind it yet.

Company

A company is an organisation as a first-class record: name, industry, website, its own custom fields, its own links, and its own finance panel showing what has been invoiced to and spent with it.

Note what a company is not: it is not the organisation field on a contact card. That field is a string, part of the vCard, and it syncs to your phone. A company is a record in Kancil that other records point at. A contact can carry "Acme BV" as text and have no link to the Acme company record — the two are independent, and linking them is a deliberate act.

Managed in Companies.

Which do I use?

You want to	Use
Store someone's phone number and have it on your phone	a contact
Point a deal, task or activity at a human	a contact — the person follows automatically
Track an organisation you sell to, buy from, or invoice	a company
Record who someone works for, as text	the organisation field on their contact

The everyday rule: contacts are for humans, companies are for organisations, and people are the plumbing that keeps two people's address books talking about the same human.