Skip to main content
Tasks capture work. Records capture the things the work is about — a supplier, a piece of equipment, an onboarding questionnaire, a site visit report. A Space holds both, and the two are joined: a task can point at a record, and a Space can be told that every task in it belongs to one contact.

​
What a record is

A record is one entry of structured data. Every record carries:
Records are found by the Space, the contact and the record set they belong to. The values inside a record are not indexed, so there is no account-wide “find every record where the renewal month is March”. The search box above the record table filters the rows already loaded, not the whole set.

​
Record sets

A Record Set is the definition every record of one kind conforms to: what fields exist, which are required, how they are laid out on a form, and how they appear as a table column.
One thing, two names. The product calls this a Record Set — that is the wording on the sidebar, the picker and the empty state, and it is what this documentation uses. The API and the assistant tools call the same object a record config (record_config_*, and record_configs on a Space). They are the same object.
A record set carries:

An id

Letters, numbers, underscores and hyphens. Chosen once when the set is created and permanent — only the name, label and description can be changed afterwards.

A schema

The fields, their types, and which of them are required. Every record is checked against it.

Form layouts

One or more named forms. A set with several forms lets each Space pin the one it uses.

A table layout

Which columns show in the record table, and how each value is formatted.

​
The schema is enforced

A record is validated against its record set’s schema when it is created and every time it is updated. A record that fails validation is rejected outright — nothing is coerced, and nothing is partially saved.
Field formats are not checked. Marking a field as an email or a date changes how it is labelled and rendered, not what is accepted — not-an-email will save into a field marked as an email. If a value genuinely has to follow a shape, give the field a pattern. Patterns are enforced, both in the browser and on save.
A field the form hid is not required. A record set’s form can hide a question with a rule, and a question nobody could see must not block the save. The form therefore tells the server which fields its rules hid, as a hidden_fields array of dotted refs on the create, update and upsert bodies, and required is relaxed for exactly those refs. Nothing else is relaxed: types, patterns, choices and additional-property rules all still apply, and a ref naming nothing in the schema relaxes nothing. A caller writing to a record set directly gets the ordinary behaviour unless it sends the array itself.

​
Changing a schema

Widen, don’t tighten. Changing a schema never rewrites, re-validates or flags the records that already exist. But the next save of an old record is validated against the new schema — so a field you just made required breaks every future edit of every record that predates it, and the breakage lands on whoever opens one next.
Always safe. Existing records simply have nothing in it.
Nothing breaks today. It breaks the next time anyone edits a record created before the change, because that record has no value for it. Count the existing records first and decide whether that is acceptable.
The data is not deleted. It stops being shown and stops being validated, but it is still stored and still comes back on a read.
Breaking in the same way as making a field required — every stored value outside the new rule blocks the next edit of the record holding it.
Deleting a record set purges every record under it, and there is no undo. If a set is no longer wanted, rename it or detach it from the Spaces that use it instead.

​
Giving a Space its record sets

A record set exists at the account level. A Space uses the ones attached to it, and only those.
1

Open the Space's Records tab

A Space has four tabs — Files, Tasks, Records and Chats. Records lists the attached record sets down the left and their records on the right.
2

Open the Record Sets menu

Select Record Sets opens a picker of everything that exists in the account; tick the ones this Space should use. Manage Record Sets opens the account-wide record set area, where sets are created and their forms edited.
3

Or create one from the empty state

A Space with no record sets attached shows Select Record Set and Create Record Set side by side. Creating one there attaches it to the Space in the same step.
Attaching and detaching record sets, and the per-set actions on the table, are limited to Space admins.
Pinning a form. When at least one attached record set offers more than one form, Edit Space → Records → Form views appears, listing every attached set with a dropdown of its forms. Pick which form records of that set use in this Space. A set with a single form has nothing to choose. Folder-scoped records. Opening a folder inside a Space gives that folder its own Records tab, showing only the records filed there. It is the same record table, scoped down.
For API users: a Space’s attached set list is whole-value replace, not a merge. Sending one set makes it the only one — read the Space, add to the list it already has, and send the complete list back.

​
The base record

A Space can be told that its tasks are about someone. That is the base record: the record set a Space anchors its contacts on, so everything about one person sits in one place. It is configured at Edit Space → Records → Base record.

​
How a contact is matched

The identifying fields are tried in order. The first one holding a usable value identifies the contact — which is what stops the same person being added twice. Before a value is used it is normalised, so two spellings of one person land on one contact:
  • A field named email, or ending in _email, is trimmed and lower-cased, and must look like an address.
  • A field named phone, or ending in _phone, is reduced to its digits, and must have at least six of them.
  • Anything else is lower-cased and its spacing collapsed.
A value that fails those checks is skipped rather than used, and the next identifying field gets its turn. If a Space names no identifying fields at all, email and then phone are used.
Phone numbers are matched on their digits alone, so an international and a national spelling of the same number do not converge — they identify two different contacts. Where both forms circulate, put email first.

​
The contact key is derived, never chosen

This is the single most important thing on this page. When a task is filed against a contact, the key it is filed under is computed from the identity you supplied. It is not a name you pick, and it is not a place in a directory tree. Supply the contact and the key follows. If you send a value for it yourself alongside an identity, the derived one replaces what you sent.
In the task form, the control that carries this is labelled Folder, and it lists the Space’s contacts by name and email, with New contact at the bottom of the list. Choosing someone there is choosing a contact.
“Folder” means two different things in a Space, and it is worth keeping them apart. On a task, it is this derived contact key. In Files, folders are ordinary storage folders you name and nest yourself. Only the first is derived.
If the contact cannot be resolved or written — no usable identity value, or the Space declares no base record — the task is still created, and the answer says why it was not linked. Losing an inbound enquiry because a record write failed is worse than losing the link, so an unlinked task is a deliberate outcome rather than a failure.

​
Which record set holds contacts

The canonical base record set is contact. There is an older id, Client, that is still read so contacts stored under it before the rename are still found — nothing writes to it any more, and it should not be chosen for a new Space. You do not have to manage that by hand. When a Space is pointed at a different record set, the one it is leaving is folded into its legacy list automatically, so contacts already stored under the old set keep being found.

​
A worked example: the Leads Space

The built-in Leads Space is a base record set up end to end:
  • Base record — the contact record set
  • Identifying fields — email, then phone
  • What this space calls one — Contact
  • Grouped under — the organisation record set, called Organisation
  • Create a sign-in — off
So an enquiry arriving with an email address is filed against the contact that address identifies, creating that contact if it is new; a second enquiry from the same address lands on the same contact.

​
Parent records

Grouped under names a record that contacts belong to — an organisation, a household, a portfolio. Leave it as None and contacts stand alone.
  • A record stores a link to its parent record’s key, and that link is indexed. It is what makes “everything under this organisation” answerable, in a system where the fields inside a record are not searchable.
  • Sending an empty parent detaches a record from its parent. Omitting the parent leaves whatever is there alone — silence never detaches.
  • When someone is added through the contact form, the only record sets that can be written are the Space’s base record and the parent it declares. It is not a back door into an arbitrary record set.

​
How records relate to tasks

Tasks are filed against a contact

In a Space with a base record, every task belongs to the contact its identity resolves to — which is what puts one person’s whole history on one screen.

Task actions can point at a record

A checklist item on a task can reference a specific record of a specific record set. A form action carries an ordered list of forms the person fills in, one step at a time.

Task templates seed record work

A template action of kind form names a record set. It has to be one attached to the Space you apply the template in.

Completing a record can start a flow

Marking a record complete fires a flow trigger — but only on the transition into complete. Marking an already-complete record complete again does nothing, so automation is not re-run.
Deleting a contact’s tasks. Every task filed against one contact can be removed in a single operation, naming either the contact key or the identity that derives it. Resolving an identity for a delete writes nothing — erasing someone must never create them.
Task actions move the task. Completing, adding or removing a task action recomputes the parent task’s status from its checklist. The status it lands on is resolved through the Space’s own To do / In progress / Done roles, and a status the Space does not have is never written. Chat actions are open-ended and are excluded from the count. See Task actions.