---
title: Contact categories
summary: Every card has one category — Clients, Not sorted, Spam, the kit's own like Suppliers, or the business's own. The category decides how Talemo treats the person.
tools: [talemo_list_contact_categories, talemo_create_contact_category, talemo_update_contact_category, talemo_remove_contact_category, talemo_categorize_contacts]
related: [contact-card, contact-history, notes-and-hidden-fields]
search: [segments, tags, suppliers, spam]
---

# Contact categories

Every card has exactly one category, and the category decides what Talemo does
with the person: visits and reminders are for clients. The list of categories
is part of the business's setup, like its price list.

## Three categories every business has

- **Clients** — everyone who books. Booking a visit for a card in Not sorted
  moves it to Clients by itself.
- **Not sorted** — someone new who is not recognised yet. Chats put new people
  here; from here a person moves each one to its category.
- **Spam** — the cards are kept, not deleted, so one that got here by mistake can
  be moved back. Moving a card to Spam closes the online admin's open handoffs
  on that person without a reply. Chats of Spam cards are hidden from people
  whose role does not see a card's category.

These three can be renamed but not removed: the product's behaviour rests on
them.

## Kit categories and the business's own

Installing an industry kit adds the categories that industry needs — for
example Suppliers, Looking for work, Partners. The business can add its own,
rename any category and remove any except the three above.

## Order of the list

Clients come first and open by default, Not sorted second, then the kit's and
the business's own categories in the order the business sets, Spam last.

## Removing a category

A category is never deleted, it is retired: the history of a card still names
it. When removing one, a person chooses where its cards go, and is first shown
how many cards will move. A person who sees only their own cards, or none, is
not given the number: all the cards of the category move, the ones they do not
see too, and they only choose where. Each moved card gets a line in its
history: who moved it and when.

## Moving cards

A person moves one card, or up to 500 at once, to another category; each move is
a line in the card's history.

## Who can do what

Anyone who sees cards sees the list of categories with the number of cards in
each. Creating, renaming, reordering and removing
categories is the business's setup, so only a role that covers the whole
business can do it.

## Tools and refusals

- `talemo_list_contact_categories` lists the categories in order with how many contacts each holds. The system ones — client, unsorted, spam — cannot be removed. `name` is empty for a category that keeps its standard name. A new contact needs its category, so list them before creating one.
- `talemo_create_contact_category` adds one at the end; a name another category uses is refused with `record.duplicate`. `talemo_update_contact_category` renames one or moves it in the list (`position`); a system category can be renamed but keeps its place.
- `talemo_remove_contact_category` moves its contacts to `move_to` in the same step, and each keeps a history line. A system category is refused with status 409, code `party_category.system`. It changes a lot at once, so call it with `dry_run` first: `moved` in the answer says how many contacts would move, but only for a role that sees all contacts. A role that sees only its own contacts, or none, gets no `moved`: the category may hold contacts it cannot see, and all of them move, so `move_to` still has to be named. Show the person, and make the real call only after they say yes.
- `talemo_categorize_contacts` moves several contacts (`parties`) to one `category`, all or nothing, and returns how many changed; contacts already in it do not count. It also changes a lot at once: `dry_run` first.
- Booking a visit for a contact in the unsorted category makes them a client; no separate call is needed.