Canonical page: https://docs.teloring.com/docs/product/objects Last modified: 2026-10-15T07:52:20.000Z # Objects **Objects** are the tables your business keeps in Teloring. Four come built in — **Customers**, **Contacts**, **Calls** and **Documents** — and you can add as many of your own as your work needs: Orders, Products, Projects, Branches, Service calls, anything. Every object has fields you define, records you can filter and sort in saved views, links between records, and the same permissions, import, export, automation and reporting as everything else in the platform. Open **Objects** from the sidebar to see them all.  ## Key facts | Fact | Detail | | --- | --- | | An object is a table | Each object has its own fields, records, views, permissions and import/export. | | Four objects come built in | **Customers** and **Contacts** are the CRM; **Calls** and **Documents** are written by the platform (phone calls, e-signature) and can only be read. | | Records link to each other | A **linked record** field points at one or many records of another object. The other side appears automatically as a related tab. | | Lookups copy a value across a link | A **lookup** shows a field of the linked record on this one — live (kept up to date) or frozen (captured once). | | Views are saved filters | Every object has a locked **All** view; save personal or shared views and pin them to the sidebar. A view can **colour rows and cells** by rules. | | Formulas calculate values | Turn a field into a **formula** and Teloring fills it from other fields of the record — *if Level is 1 then "Yes"*, *Start date + 45 days*, *Price × Quantity*. | | Buttons start automations | A **button** field is clicked, not filled: each click is recorded and can start a [Studio](./studio/triggers.md#object-change) flow. | | Everything else sees objects | [Studio](./studio.md), [Analytics](./analytics.md), [Forms](./forms.md), [AI Agents](./agents.md) and the [API](/api/) all work with any object. | ## Who uses Objects | Role | Typical use | | --- | --- | | Agents | Open a customer or an order from a conversation, fill in fields, add a record, find what a customer bought. | | Managers | Save views (open orders, overdue deliveries), export to Excel, review the change history of a record. | | Admins | Design objects and fields in the builder, import data, set who may read or edit each object. | ## The built-in objects | Object | What it holds | Who writes it | | --- | --- | --- | | **Customers** | The business, household or account behind a relationship: name, lifecycle stage (lead, active, inactive, irrelevant), industry, contact details, assigned agent, tags, notes. | Agents, imports, Studio, the AI Agent, the API. A customer is also created automatically when a new contact writes to you. | | **Contacts** | The people who contact you: name, phone, email, company, status, and a link to their customer. | The inbox (a new WhatsApp number, an email sender) and everyone above. | | **Calls** | One record per phone call on a [Voice](./ring/voice.md) inbox: number, direction, status, duration, agent, recording, the customer and contact. | The platform only. | | **Documents** | One record per [e-signature](./studio/actions.md) document sent: status, sent and completed times, the signed file, the customer and contact. | The platform only. | Customers and Contacts keep their special roles: a conversation always has a contact and usually a customer, and the conversation sidebar opens them directly. Both can be given more fields in the builder like any other object. ### Lifecycle stages | Stage | Typical meaning | | --- | --- | | Lead | A potential customer or new opportunity. | | Active | A current customer. | | Inactive | A customer that is not currently active. | | Irrelevant | A record that should not be treated as an opportunity or customer. | Your team decides the operational meaning of each stage; you can add stages of your own in the builder, and Studio can react when a stage changes. ## Working with an object Click an object to open its table.  | Part | What it does | | --- | --- | | **View tabs** | **All** (every record) and your saved views. The active tab is the view whose filters, sort and columns you see. | | **Search** | Finds records by their primary field (the field that names each record — usually *Name*). | | **Filter** | Opens the filter panel: conditions on any field, grouped with AND / OR, two levels deep. Dates understand *today*, *this month*, *in the last 7 days* and the account's timezone. A condition can also compare two fields of the record. | | **Sort** | Up to three levels. Records with no value in the sort field come last. | | **Columns** | Which fields show, and in what order. | | **View options** | Rename, duplicate, pin or share the view, and **Conditional coloring** — see below. | | **Import / Export** | CSV or XLSX in, XLSX out — see [Import and export](#import-and-export). | | **New record** | Opens the record form. | | **Total** | The exact number of records in an unfiltered view; filtered views count as you scroll. | The table loads twenty records at a time and keeps loading as you scroll. If a filter matches nothing in the first batches you can ask it to **keep searching**. The table is live: records your colleagues, Studio, forms, imports or the API add, change or delete appear, update or disappear on their own, without a refresh — and never under a cell you are editing. ### Saving a view After filtering, sorting or choosing columns, the toolbar offers **Save view** (update the current view) and **Save as view** (a new one). | Scope | Who sees it | Who may create it | | --- | --- | --- | | **Personal** | Only you. | Anyone who can read the object. | | **Shared** | Everyone who can read the object. | Agents with **Views → Create**. | Pin a view (**View options → Pin**) and it appears under **Objects** in the sidebar — up to five per agent. The **All** view's columns and sort are personal preferences; they never change for anyone else. Saved views count against your plan's **Views** limit.  ### Conditional coloring **View options → Conditional coloring** paints a row, or a single cell, when its record meets a condition — overdue deliveries in red, VIP customers in gold, finished projects in green.  Each rule has: | Part | Meaning | | --- | --- | | **Colour** | Pick from the palette or choose any colour (**＋**). The text colour is chosen automatically — dark on light colours, white on dark ones — so it always stays readable. | | **Cell / Row** | **Row** paints the whole row. **Cell** paints only the cell of the field the condition is about (the field must be a column of the view to be seen). | | **When** | A field, a condition and a value — the same conditions as filters: *is*, *is not*, *contains*, *starts with*, *is empty* for text; *greater than*, *between* for numbers; *before*, *after*, *today*, *in the last 7 days* for dates; and *compare to another field*. | Rules apply from top to bottom (use ↑ to reorder): the first matching rule colours the row, the first matching rule for a column colours that cell, and a cell colour wins over the row colour. Up to 30 rules per view. Colouring is part of the view: save the view to keep it, and everyone who sees a shared view sees its colours. On the **All** view the colouring is your personal preference, like its columns and sort. Rows are recoloured as soon as you edit them, and date rules such as *before today* follow the account's timezone. ### Records | Action | How | | --- | --- | | Add a record | **New record** opens a form with the object's sections. Required fields are marked; a linked-record field offers a search of the other object, and can create a missing record on the spot. | | Edit a value | Click a cell in the table or a field in the record's side panel; the change saves on blur or Enter. | | Open a record | Click the green open button at the start of the row, or the record's name: the record opens in a side panel beside the table. The address bar then links to that record — copy it to share, or reload and it opens again. | | Delete | From the record or by selecting rows. A record that other records still link to **cannot be deleted** until those links are removed — the dialog lists them. | | Bulk delete | Select rows and press **Delete selected**; linked records are skipped and reported. |  The side panel shows the fields **kept on top** at the top (they stay visible while you scroll; click one to edit it), the fields by section, one **related** tab per object that links to this record (a customer's orders, a material's closets), and **Activity** — who changed which field, from what to what, and when, including changes made by imports, Studio, forms and the AI Agent. Lookup refreshes are folded away by default; a toggle shows them. A **customer's** panel also has a **Journey** tab (the customer's timeline: conversations opened and resolved, records added, stage changes — click an event to open it), a **Conversations** tab (filter by open, pending or resolved), the **Contacts**, **Calls** and **Documents** tabs, and **Merge** (⇆) to fold a duplicate customer into this one — its contacts, conversations, linked records and journey move over and the duplicate is deleted. By default a customer's **Lifecycle Stage**, industry, phone and email are kept on top. From a conversation, **View** on the customer card opens the Customers table with that customer's panel. ## Building an object Admins with **Objects builder** permission open an object's builder (⚙ on the object card or page). Create a new object from the Objects page with **New object**: a label, a singular label, an icon. The object starts with one required text field, **Name**, as its primary field.  ### Settings | Setting | Meaning | | --- | --- | | Labels and icon | How the object appears in menus (plural) and on a record (singular). | | Primary field | The field that names each record — shown in links, pickers and search. Text, email, phone, URL, number, auto number or date. | | API ID | The stable technical name used by the API and Studio variables. | | Hide from menu | Keeps the object and its records but removes it from the Objects page and the sidebar. | | Keep a change history for reports | Also stores every change as an event, so [Analytics](./analytics.md#objects) can chart changes over time — for example deals moved to *Won* per week. | | Record panel | Which fields are kept on top of the record's side panel (up to six — also **Keep on top** in each field's settings), and which related tabs appear. | | Delete | Type the object's name to confirm. The object is restorable for seven days from **Recently deleted**; links pointing at it are removed at once; its records are purged after the grace period. | ### Fields Drag a field type from the toolbox into a section. Each field has a label, an API ID, a description, and can be **required**, **unique** (text, email, phone, URL and number — no two records may share a value), **hidden**, or **kept on top** — shown at the top of every record's side panel (up to six fields; ⬆ marks them in the builder). | Field type | Holds | Notes | | --- | --- | --- | | Text, Long text, Rich text | Short or long text, formatted text. | | | Number, Currency | Numbers; money with a currency code and decimals. | Summable in Analytics. | | Email, Phone, URL | Validated values. | | | Date, Date and time | A calendar day, or an instant. | Dates follow the account's timezone; a date can default to today. | | Checkbox | Yes / no. | | | **Rating** | A score from 1 to the maximum you choose (3–10). | Shown as stars, hearts, flames, thumbs or numbers; click a star to rate, click it again to clear. Averages in Analytics. | | **Progress** | A current value between a start and an end you set (0 → 100 by default, or a countdown such as 10 → 0). | Shown as a bar with a percentage, or the value out of the end. | | **Button** | The time it was last clicked. | A button has no on/off — see [Buttons](#buttons). | | Dropdown, Radio, Multi-select | One or several options you define, with optional colours and a default. | Options drive grouping and colours in Analytics. | | Agent | One of the account's agents. | | | File | Uploaded files, kept in the [files warehouse](./files-warehouse.md). | | | **Linked record** | One or **multiple records** of another object (or a conversation). | Creates the inverse field on the other object automatically — see below. | | **Lookup** | A copy of a field of the linked record. | Live or frozen — see below. | | Related count | How many records link here through one inverse field. | Kept up to date automatically. | | Auto number | A sequential number with a prefix and padding (ORD-0042). | Never reused. | | Caption | A heading inside the form. | Holds no value. | System fields (a customer's name, a call's duration) cannot be removed or renamed away from their meaning; you can hide some of them. ### Linked records, lookups and counts A **linked record** field on *Orders* that points at *Customers* holds one customer (or several, when you choose **multiple records**). Teloring adds the inverse side — an *Orders* tab on every customer — by itself, with no data of its own. A linked record can also point at **conversations**. A **lookup** reads a field across such a link: *Customer industry* on an order copies the industry of the linked customer. Choose the link, the field, and the mode: | Mode | Behaviour | Use it for | | --- | --- | --- | | **Live** | Refreshed in the background whenever the source changes. | The customer's current industry, a product's current price. | | **Frozen** | Captured when the link is set and never changed. | The price at the time of sale. | Lookups can chain (a lookup of a lookup) up to three levels; a cycle is refused. Lookups through a conversation are always frozen. A **related count** counts the records on the other side of an inverse field — *number of orders* on a customer — and a lookup can copy that count further up the chain.  When you add a field, change a lookup, or delete a field, existing records are updated **in the background**; the table shows *updating…* on rows that are being written. **Refresh lookups** on an object recomputes every lookup and count and fills anything a lost background job missed. ### Formulas Text, number, currency, date, date and time, checkbox, dropdown, radio, rating and progress fields can be **calculated** instead of typed. In the field's settings switch **Value** from **Typed by people** to **ƒx Formula** and build the formula from choices — no code:  - **If … then** rules — a condition on any field of the record (the same conditions as filters, with AND / OR groups) and the value to use when it is met. Rules are checked from top to bottom; the first one that matches wins. - **Otherwise** (or **Value**, when there are no rules) — the value when no rule matches. Each value can be: | Value | Available for | Example | | --- | --- | --- | | **A fixed value** | Every type | *"Yes"*, *5*, *2026-12-31*, an option of the dropdown. | | **Copy a field** | Every type | Copy *Due date* into *Follow-up date*; copy any field into a text. | | **Calculate** | Numbers, currency, rating, progress | *Price* × *Quantity* − *Discount*. Steps apply in order, top to bottom: plus, minus, times, divided by, the smaller of, the larger of. An empty number counts as 0; dividing by 0 leaves the field empty. | | **Time between two dates** | Numbers | Days (or minutes, hours, weeks, months, years) from *Start date* to *Delivery date*. | | **Date plus / minus time** | Date, date and time | *Start date* + 45 days; *Created* − 2 hours. | | **Combine text** | Text | *First name* + " " + *Last name*; "ORD-" + *Order number*. | Examples: | Field | Formula | | --- | --- | | *Approved* (text) | If *Level* is *1* → "Yes"; if *Level* is *2* → "No"; otherwise empty. | | *Due date* (date) | *Start date* + 45 days. | | *Total* (currency) | *Price* × *Quantity*. | | *Days to deliver* (number) | Time between *Order date* and *Delivery date*, in days. | | *Priority* (dropdown) | If *Total* is greater than 10,000 → *High*; otherwise *Normal*. | | *VIP* (checkbox) | If *Orders* (a related count) is at least 10 → Yes; otherwise No. | How formulas behave: - A formula field is **read-only** — in the table, on the record, in imports, the API, Studio and the AI Agent. Change the fields it reads and it updates by itself, at once; when it reads a lookup or a count, it updates when they do. It shows **ƒx** in the column header and on the record. - A formula reads the fields of **its own record**: plain fields, lookups (to use a linked record's value), related counts, auto numbers, other formulas, and the record's creation time and creator. - **Relative dates** (*today*, *in the last 7 days*) cannot be used in a formula, because its value is stored on the record and would silently go stale. Use them in filters and conditional colouring instead. - Turning an existing field into a formula **replaces its values** on every record, in the background; switching back to **Typed by people** keeps the last calculated values. - Formulas can read other formulas, but never in a loop. A formula field cannot be required, unique or the object's primary field. - Other objects can copy a formula's result with a lookup, and Analytics, views, filters, sorting, export and Studio variables use it like any other value. ### Buttons A **button** field puts a button on every record — *Approve*, *Send quote*, *Mark as called*. It has no on/off state: every click is a new event.  | Setting | Meaning | | --- | --- | | Button text and colour | What the button says and its colour (the text colour adapts). | | Ask before each click | Shows "Are you sure?" first. | - Clicking needs **Update** permission on the object. Each click is written to the record's **Activity** (who and when), and the field keeps the time of the last click — so you can filter *clicked in the last 7 days* or sort by it. - **Automate it:** in [Studio](./studio/triggers.md#object-change), use **Object change** → **Edited** → *Edits only to these fields* → the button. The flow runs on **every** click, with the record's fields as variables. - A button cannot be imported, typed, cleared, or set by Studio and the AI Agent. Through the [API](/api/), send `true` to click it. ### Changing and deleting fields A field's type can change only within its family (text to email, dropdown to radio). Deleting a field that others depend on — lookups that copy it, counts over it, formulas that read it, the inverse side of a link — lists those dependents and deletes them together once you confirm. ## Import and export  **Import** takes a CSV (UTF-8 or Windows-1255) or XLSX file of up to 50,000 rows: 1. **Upload** — Teloring reads the headers and shows a preview. 2. **Map** columns to fields. Linked-record columns match the other object by its primary field, by a unique field, or by id; you can ask Teloring to **create missing** linked records (custom objects with a text primary field). Choose a **unique field** to update existing records instead of creating duplicates, and the date order of the file (D/M/Y). 3. **Dry run** — every row is validated without writing; you see how many records would be created or updated and the first row errors. 4. **Import** — runs in the background with a progress banner; a CSV of skipped rows is downloadable at the end. Lookups, counts, auto numbers, formulas, buttons and platform-written fields are never imported (formulas are calculated for every imported record). Customers and the records of your own objects count against your plan. **Export** writes XLSX: **what is on screen** at once, or the **whole view** as a background job you download when it finishes. Linked records export their names, lookups their stored values. Needs the object's **Import / Export** permission, and **Create** (or **Update**, for a unique-field import) on it. ## Permissions Each object is one row in **Roles & Permissions → Objects** with **Read**, **Create**, **Update**, **Delete** and **Import / Export**. The **All objects** row is the default every object without a row of its own follows — including objects created later — and a single object can be allowed or denied on top of it. **Objects builder** governs the builder itself; **Views → Create** governs shared views. See [System permissions](./roles/system-permissions.md#objects). Linked-record pickers only search objects the agent may read; an agent who may not read an object sees its records' names where they are linked, nothing more. ## Objects across the platform | Feature | What it does with objects | | --- | --- | | [Studio](./studio/triggers.md#object-change) | The **Object change** trigger starts a flow when a record is created, edited or deleted — or when a **button** is clicked; **Add / Update / Delete a record** actions write any object. | | [Analytics](./analytics.md#objects) | Any object is a data source: count, sum, average and group by any field, with linked records shown by name; **Changes** charts the history of objects that keep one. | | [Forms](./forms.md#record-picker) | A **record picker** field lets a visitor choose one of your records; a form can **create a record** from each submission. | | [AI Agents and Copilot](./agents.md#objects-the-records-an-ai-agent-may-use) | An AI Agent can look up, create and update records you allow — only the customer's own; Copilot answers from the records linked to the conversation. | | [API](/api/) | Read, query, write, import and export records; manage the schema with the `objects_admin` scope. | ## A worked example A kitchen maker tracks what it sells: 1. **Materials** — name, supplier, *price* (currency). 2. **Closets** — name, *material* (linked record → Materials), *material price* (live lookup of the material's price). 3. **Orders** — *order number* (auto number ORD-0001…), *customer* (linked record → Customers), *closet* (linked record → Closets), *price* (live lookup of the closet's material price), *price at sale* (the same lookup, **frozen**), *status* (dropdown: New, Paid, Delivered), *order date*, *delivery due* (formula: *order date* + 45 days), *satisfaction* (rating, 5 stars) and an *Approve* button. A price change on a material updates *material price* on every closet and *price* on every order in the background; *price at sale* keeps what it was. Each customer shows an **Orders** tab; each material shows its **Closets**. A shared view *Unpaid orders* is pinned for the sales team and paints a row red when *delivery due* is before today. A manager's click on **Approve** starts a Studio flow that messages the customer, another flow messages them when *status* becomes *Delivered*, and an Analytics chart shows order totals per month. ## Troubleshooting | Problem | What to check | | --- | --- | | I cannot see an object | Your role needs **Read** on that object (or **All objects**). Hidden objects are still readable by direct link. | | A record will not delete | Other records link to it; the dialog lists them. Remove those links first. | | A lookup is empty on old records | Fields added later are filled in the background. Run **Refresh lookups** on the object if a job was lost. | | A row says *updating…* | A background update of its lookups is running. It clears on its own. | | My import created duplicates | Choose a **unique field** in the mapping so rows update existing records. | | A linked record will not link | You need **Read** on the other object, and the record must exist there. | | *Updating…* banners stay | Background jobs that stop moving are reported as failed after an hour and can be dismissed. | | I cannot type into a field | It is a formula (**ƒx**), a lookup, a count or an auto number — change the fields it is calculated from. | | A formula is empty | An input it needs is empty, a division was by zero, or the result does not fit the field (a dropdown value that is not one of its options). Run **Refresh lookups** if records were changed while the formula was being added. | | A colouring rule paints nothing | For **Cell** rules the field must be a column of the view. Rules apply top to bottom — an earlier row rule may already match. | | A button click did not start my flow | The flow's **Object change** trigger needs **Edited** ticked, and the button chosen in *Edits only to these fields*. | ## Related guides - [Conversations](../getting-started/conversations.md) — the contact and customer in the right sidebar. - [Conversation Attributes](./conversation-attributes.md) — fields that belong to one conversation rather than to a record. - [Studio triggers](./studio/triggers.md#object-change) and [actions](./studio/actions.md#add-update-or-delete-a-record) — automate records, including button clicks. - [Analytics](./analytics.md#objects) — report on records and their changes. - [Forms](./forms.md#record-picker) — collect records from the public. - [Roles and Permissions](./roles/system-permissions.md#objects) — who may do what.