Records

Customermates has five record types: Contacts, Organizations, Deals, Services, and Tasks. They all use the same screen layout, so this page documents them together for people and for AI agents that drive the UI.

What is the shared layout of a record type, and what is the add drawer for?

Every record type has the same three surfaces:

• List at /{type} (for example /contacts), locale-prefixed like /en/contacts. Search, filter, sort, saved views, and bulk actions live here.
• Add drawer: the Add button opens a form over the list; the deep link is ?open={entityType}:new (for example /contacts?open=contact:new) and works on any app page. The drawer is for adding only: you cannot edit an existing record in it, and existing records open on their detail page. The sidebar Add button (#nav-add) opens Create new…, which lists the record types your role can manage and opens the same drawer from any page.
• Detail page at /{type}/{id} (for example /contacts/<id>, where the id is the record's UUID) for the full record, custom fields, relations, and delete. It opens with an overview of the fields that matter most; every field carries a pin control (no stable id) that adds it to or removes it from that overview. Customize in the topbar also lets you hide fields or drag them into another order, and Done ends it. These choices are per person, so two colleagues can read the same record through different summaries.

A record page has the panels Overview, Notes and Activities, side by side on wide screens and as tabs on narrow ones. Edit Notes in its panel and press Save; in the add drawer, notes are a field above Save. Activities (headed History) lists the record's changes and linked messages, with a filter and Load older, and only roles with Audit Log read access All see it. Over MCP, update_record_notes appends to or replaces the notes and get_activities reads the history.

Rows never carry a DOM id. Open a record by its detail URL, never by clicking a row you located by id. A workspace can rename the record types under Data model (company settings); routes, ids and entityType values stay the same.

Link: the Contacts page, /contacts (likewise /organizations, /deals, /services, /tasks). Mate: navigate and highlight_element with nav-contacts (or nav-{type}), navigate with an entity and a recordId for a record page, and highlight_element with contacts-add (or {type}-add) for Add; the sidebar Add, the drawer, the panels and the pin controls are not highlight targets, so Mate names them.

Where do I see the list of records and add a contact, a company or a deal?

Open the list page of the record type, Contacts, Organizations, Deals, Services or Tasks, where you see all records of that type, and click Add. The form opens in a drawer over the list, and Save creates the record. The sidebar Add opens Create new… on any page, and ?open=contact:new opens the same drawer. Adding needs Manage Yes on that record type's row of your role.

Link: the link to the Contacts page, /contacts (likewise Organizations /organizations, Deals /deals, Services /services and Tasks /tasks). Mate: navigate and highlight_element with nav-contacts (or nav-{type}), then highlight_element with contacts-add (or {type}-add) for Add; the sidebar Add and the drawer are not highlight targets, so Mate names them.

Which ids does each list have?

Each record type has its own route and its own toolbar ids, prefixed with the type. The toolbar controls behave the same everywhere: Add opens the create drawer, Search live-filters the list, Filters opens the filter palette (filter syntax), Appearance controls layout, grouping, sorting and columns, and the transfer menu exports the list to a spreadsheet or imports records from one.

Inside each Appearance popover, the layout controls are #{type}-layout-table and #{type}-layout-board: #contacts-layout-table, #contacts-layout-board, #organizations-layout-table, #organizations-layout-board, #deals-layout-table, #deals-layout-board, #services-layout-table, #services-layout-board, #tasks-layout-table, #tasks-layout-board. Every id in this section is a target the hosted assistant can navigate to or highlight, the layout ids only while Appearance is open.

Which of these controls a member sees depends on the role's row for that record type; the role editor explains Read access and Manage.

Link: the Contacts page, /contacts (likewise /organizations, /deals, /services, /tasks). Mate: navigate and highlight_element with nav-contacts (or nav-{type}); {type}-add, {type}-search, {type}-filter, {type}-display-options and {type}-transfer are highlight targets, and {type}-layout-table and {type}-layout-board once Appearance is open; the saved-view tabs, the selection bar, Update and Delete selected are not, so Mate names them.

How do I import or export records?

The transfer menu (#{type}-transfer, for example #contacts-transfer) on every list, such as contacts or deals, is labelled Import and export: it imports records from Excel and exports them. Export writes the current list to an Excel workbook, a spreadsheet with the visible columns, the current filters, search and sort applied, or only the selected rows when some are checked; the first 50,000 records are included.

Add from file opens a wizard that reads an Excel workbook (.xlsx, up to 10 MB and 10,000 rows), lets you match spreadsheet columns to fields, custom fields and channels, checks every row, and then adds the records in batches. A column mapped to Record ID updates existing records instead of adding new ones. CSV files are not accepted: save them as .xlsx first. Over MCP, the equivalent of an import is one create_contacts, create_organizations, create_deals, create_services, or create_tasks call with up to 100 records.

The wizard reads the first sheet not named "Schema", and a workbook may hold at most 12 sheets. New contacts need a first and a last name, new services a name and a price (Amount), the other types a name. Link columns are matched by record name, ignoring case, and a name that matches no record or several is flagged; channels are added to new contacts only. Rows with problems can be skipped ("Import the rest and skip N rows"), and a workbook you exported can be edited and read back in, where its Record ID column updates those records. Export needs Read access on the record type, Add from file needs Manage.

Link: the list page of each type, for example the Contacts page, /contacts (likewise /organizations, /deals, /services, /tasks). Mate: navigate and highlight_element with contacts-transfer (or {type}-transfer); Export, Add from file and the wizard steps are not highlight targets, so Mate names them.

How do saved views work, and can I share one with my team?

A saved view is personal: it remembers the whole list (filters, search, sort, page size, layout, grouping, column order, column widths and hidden columns) for the person who created it, and it cannot be shared with teammates. The saved-view tabs sit directly under the header on every list; the tab bar and its controls carry the same ids everywhere, without a record-type prefix. Every change is saved into the active view as you make it; on the All tab it is saved as your personal state for that list. There is nothing to reset or save by hand. Copy link opens the view only for you, and a teammate who opens that link sees their own All tab. To show a teammate the same list, send the address from your browser bar: it carries filters, search, sort, page, layout and grouping, but not column order, widths or hidden columns, and the teammate can save it as their own view with New view. Rename or remove a view with Edit view or Delete view in the View actions menu.

• #global-data-views is the tab bar itself, a navigation landmark.
• #global-data-views-all is the built-in All tab, which clears the active view.
• #global-data-views-new (New view) asks for a Name and saves the current list as a new view.
• #global-data-views-menu opens the action menu for the active tab: edit, duplicate, move, copy link and delete on a saved view, and duplicate plus copy link on the All tab.
• #global-data-views-ai is Ask Mate, the first item of the View actions menu on a saved view and on the All tab, shown while the assistant is available. It opens chat with the exact view attached as a removable context chip and editable starter text; it does not send a message.
• Ask Mate is also available while editing a view and at the top right of the Filters and Appearance headers, including nested filter pages. Pending filter changes are applied before chat opens. Asking from the edit dialog does not save an unfinished rename. The selected view id, surface, and requested create or update action stay attached independently of the translated starter text.
• #view-editor-ai offers Create with AI inside New view and carries its optional name in the canonical create context, chip label, and starter text. Opening chat creates no view and sends no message.
• On list pages, the chat composer's Add context menu (the + button) can attach the current view or the New view action again later, plus the record of an open drawer. On record detail pages it offers the current record instead. On any page, its search can attach another contact, organization, deal, service, or task. The activity timeline Ask Mate action attaches both the record and its timeline target directly, so a linked deal cannot change a Contacts or activity-view target.

A view is addressed by the view query parameter, for example /deals?view=<id>; without it, the page uses your remembered selection. Use view=__all__ to open All explicitly. Saved-view tabs other than All (#global-data-views-all) carry no ids, so switch views by URL rather than by clicking a tab.

Describe the records you want to see, for example "Create a view of my open deals, sorted by value." The assistant uses manage_data_views to discover the page's supported settings, then saves filters, search, sorting, grouping, page size and layout. It preserves settings you did not ask to change. New views are selected automatically, and the page reloads to show a change after the chat turn finishes, unless you are typing, a message is queued, a tour or highlight is showing, or unsaved edits would be lost. Views remain personal, and deleting one requires confirmation in the built-in chat. Column visibility, widths and order stay available in Appearance. External AI clients connected through MCP can use the same tool with the connected user's permissions.

Link: any list page, for example the Deals page, /deals; a saved view opens at /deals?view=<id> only for the person who created it. Mate: navigate and highlight_element with nav-deals (or nav-{type}); the view tabs, New view, View actions and the Ask Mate buttons are not highlight targets, so Mate names them.

Which ids do the drawer and the detail page have?

These ids are shared by every record type. They are DOM ids for external browser clients; the hosted assistant does not press them, it changes data through the record tools instead.

#entity-edit-fields (Edit Field) belongs to detail pages without Customize; none of the five record types has one, so use Customize instead.

Link: a record page, /contacts/<id> (likewise /organizations/<id>, /deals/<id>, /services/<id>, /tasks/<id>). Mate: navigate with the entity and its recordId; the topbar buttons, the drawer, the selection bar, Update and Delete selected are not highlight targets, so Mate names them.

How do I bulk update or delete many records at once?

Ticking rows opens the selection bar, which counts the selected records and those not in the current view, and after a filter change offers Keep only rows in view. Besides Delete selected it has Update, which sets or clears one custom field on all selected records (Apply to selected, Clear field); built-in fields cannot be bulk edited. You can select up to 100 records at a time, and both actions need Manage on that record type.

Link: a list page, /contacts (likewise /organizations, /deals, /services, /tasks). Mate: navigate and highlight_element with nav-contacts or the matching nav-<type>; the row checkboxes, the selection bar, Update and Delete selected (#mass-delete) are not highlight targets, so Mate names them.

What is the difference between the record types, and where does a phone number go?

Contacts are people, with channel identifiers (email address, WhatsApp phone number, LinkedIn, Instagram, Telegram) that connect them to Inbox threads and power the send icons on their detail page; a plain phone number belongs in a Phone custom column. Contacts link to organizations, deals, tasks and assigned users.

Organizations group contacts and link to deals, tasks and assigned users. Deals track opportunities, link to contacts, organizations, tasks and assigned users, and carry linked services with per-deal quantities; the deal's total value and quantity follow from them, and a weighted value follows from the stage column when the workspace defines one (see core concepts).

Services are what you sell: each has a price (Amount) and links to deals (with a quantity per deal), tasks and assigned users. A service cannot link to an organization or a contact; link the organization to the deal instead.

Tasks are to-dos that link to any of the other types and to assignees. Tasks have no built-in due date: add a Date custom column called "Due date" and filter or sort on it. When someone registers through your workspace's invitation link, the system task Approve User appears until a member with Manage Yes and Read access All on Users & Roles (or with the Admin role) approves them or sets them Inactive under My Company › Members (/company/members). It cannot be renamed or deleted, over MCP its name reads "User Pending Authorization" with their email address, and for members with Manage on Users & Roles the sidebar shows the number of such tasks next to Tasks.

All five share the same machinery: the same list views, the same drawer and detail page, the same custom columns, the same filters, and the same relation editing. Anything this page says about one type holds for the others.

Link: the Contacts, Organizations, Deals, Services and Tasks pages, /contacts, /organizations, /deals, /services, /tasks. Mate: navigate and highlight_element with nav-contacts, nav-organizations, nav-deals, nav-services or nav-tasks; the relation fields on a record page are not highlight targets, so Mate names them.

How do I switch between table and board view, for example to show a pipeline as a kanban board, and group the board by a field?

To sort tasks by due date, first add a Date custom column if needed. On Tasks, open Appearance → Sort by, select that date column and use the Ascending/Descending toggle. Tasks have no built-in due date.

Every list offers a table and a board. #{type}-display-options opens the switcher, which shows one labelled card per layout with a small preview of it; the board groups records by a field, and the group-by picker lists every groupable field: singleSelect custom columns, linked records, assigned users, and created or updated dates. A board with no grouping yet asks you to pick one and offers to create a singleSelect field on the spot. Sorting, search, and filters live in the same toolbar (#{type}-search, #{type}-filter). View choices persist per user and survive reloads. When you ask for guidance, the hosted assistant can highlight search, filter, display options, and the table or board targets, and you open and change those controls yourself. Ask Mate in View actions, Filters, or Appearance can instead apply supported saved-view settings through chat.

Appearance has the sections Layout (Table or Board), Group By, Sort by with an Ascending or Descending toggle, and Fields, where you show, hide and drag columns into order (Name always stays); a dot on the button marks an active sort, grouping or hidden column. Group By works in the table too, tasks can also group by their Type, dates group by day, week or month, and at most 50 groups are shown. Lists sort by name, created or updated date and any custom column, deals also by Deal Value, Service Quantity and Weighted Value, services also by Amount (the price). Pages hold 5, 10, 25 or 100 rows; a list shows 100 until you pick another size.

The filter control opens a command palette. #filter-palette-search narrows the list of filterable fields as you type; picking a field opens its value page, and the value applies to the list as soon as you set it, with no separate apply step. #filter-palette-back returns to the field list, Escape steps back one page and closes the palette at the top level, and Clear removes every applied filter at once.

The Filters button shows a dot while filters apply. In the palette, applied filters sit under Active filters: click one to change its value or condition (Change condition), or remove it with Remove filter. Fields sit under Filter by, and typing in Add filter… narrows them. Dates offer Before…, On or before…, After…, On or after… and Between…; created and updated dates add 7, 30, 90 or 365 days and Custom range… for another number of days, and date-range columns add Includes…. Up to 50 filters apply at once (filter syntax).

Link: the list page of each type, for example the Deals page, /deals. Mate: navigate and highlight_element with deals-display-options or deals-filter (or {type}-display-options, {type}-filter), then deals-layout-table or deals-layout-board once Appearance is open; Group By, Sort by, Fields, the palette and the page size are not highlight targets, so Mate names them.

How do I change a deal stage or a task status on the board?

Pipeline stages and task statuses are singleSelect custom columns, not fixed fields. Open Edit Field via Customize → Edit column; this needs Manage on that record type.

To change a deal stage or a task status, drag the card between board columns on a board grouped by that stage or status column, or open the record and set the field. Pipeline stages and task statuses are singleSelect custom columns, not fixed fields, so there is no product-level deal stage or task status: a new workspace starts with a Stage column on deals and a Status column on tasks, and you can edit their options or add your own column.

Any record type can carry user-defined custom columns, and get_record_schema returns whatever columns a workspace has configured for each type with their option values. Over MCP, call update_deals or update_tasks with the column id and the option value from get_record_schema; the option value is the canonical form, not the label.

Dragging a card changes the value only when the board (kanban) groups by a singleSelect column, on any record type; boards grouped by anything else (linked records, users, dates, or a task's Type) are read-only, and dropping a card on No value clears the field. To add or rename stages, open the column's Edit Field dialog: click a column header on a board grouped by it, or press Customize on a record page and then the field's Edit column pencil. Changing a column needs Manage on that record type.

The demo workspace ships example columns to illustrate the pattern, for instance a "Status" column on deals (Open, Won, Lost, Abandoned), "Status" and "Priority" columns on tasks, and a "Sales Pipeline" column on contacts. These are seeded examples, not fixed behavior. Rename them, change their options, add more, or remove them per workspace.

Link: the Deals page, /deals, or the Tasks page, /tasks. Mate: navigate and highlight_element with deals-display-options (or tasks-display-options) for Group By, then deals-layout-board once Appearance is open; the board columns, the cards and Edit Field are not highlight targets, so Mate names them.

Tips for agents

• The hosted assistant navigates by the target ids above (navigate with a target id, or with an entity and record id for a detail page) and highlights toolbar controls; it never opens the drawer for an existing record.
• External browser clients locate controls by the stable ids, for example document.querySelector('#deals-add'). Ids are identical across locales and viewports; visible labels are not.
• To open an existing record, build its page URL yourself: /{type}/{id}. Do not try to click a row.
• Prefer MCP tools over driving the UI when a tool exists. Creating or updating a record, or changing a singleSelect column value, is one tool call instead of a click sequence.

Related

• Core concepts: entities, relationships, custom columns.
• MCP tool catalog: every tool your AI can call.
• App guide, Dashboard