Working with contacts

Contacts are the people your business deals with. Companies are the organisations they belong to. Deals are the opportunities or pieces of work in progress. These three things connect: a contact can belong to a company, and a deal can link to both a contact and a company.

You manage all three from the Contacts section of the sidebar. You can also create, look up, and update them from inside an automation — so enquiries get logged, deals get opened, and notes get added without anyone having to do it by hand.

The model at a glance

Thing	What it is	Key fields
Contact	A person	Name, email, phone, title, company
Company	An organisation	Name, domain, website
Deal	An opportunity or piece of work	Name, stage, value, owner, linked contact and company

A contact can belong to a company. A deal can link to a contact, a company, or both. Notes can be added to any of the three.

Finding a contact in a flow

Use Find contact when you have an email address or a name and need the contact’s ID before doing anything else.

The step returns a found field — always branch on it immediately so you handle the case where the contact does not exist yet.

Find contact  →  Branch on {{ lookup.found }}
                    Yes → Add note, open deal, etc.
                    No  → Create contact → continue

List contacts does the same thing in bulk: it returns a contacts array you can feed into a For each loop to process a whole group at once — for example, emailing every contact at a given company.

Creating or updating a contact

Create contact is idempotent on email: if a contact with that address already exists, the step returns the existing record (with created: false) instead of adding a duplicate. This means you can call it at the top of every enquiry flow without worrying about double entries.

If you also supply a company_name, the step resolves or creates the parent company in the same call — you do not need a separate Create company step unless you want more control over company fields like domain or website.

Prefer Create contact over Find contact when the record may not exist

If you are not sure whether the contact exists, go straight to Create contact. It handles both cases (new and returning) in one step, so you always get a contact_id without writing a Branch.

Adding a note

Add note attaches a freetext note to a contact, company, or deal. You tell it which kind of record you are attaching to (entity_type: contact, company, or deal) and pass the entity_id from a previous step.

The note field accepts template variables, so you can include live values from the run — for example, the enquiry text that came in from a webhook, or a summary produced by an earlier AI step.

Moving a deal through the pipeline

Create deal opens a fresh deal linked to a company. Pass the company_id from a Find company or Create company step, set a stage_name, and optionally supply a primary_contact_id to link the deal to a specific person.

Once a deal exists, Move deal stage advances it through your pipeline. Pass the deal_id and the target stage_name. When the stage kind is Won or Lost, the step automatically stamps closed_at — useful for downstream reporting or notification steps.

Using contact fields inside a loop

When you loop over a list of contacts with For each, each item in the loop is available as {{ loop.item }}. Use dot notation to reach individual fields:

• {{ loop.item.email }} — the contact’s email address
• {{ loop.item.firstName }} — their first name, for personalised greetings
• {{ loop.item.name }} — their full name
• {{ loop.item.company_id }} — the ID of their parent company

These work in any step field — email body, note text, deal name, wherever you need them.

Worked example: handle an incoming enquiry end to end

Here is a complete flow that runs when an enquiry arrives via a webhook (a contact form, a Typeform, an external integration — anything that can POST JSON).

What it does: creates or retrieves the contact, adds the enquiry text as a note, opens a deal at the “New enquiry” stage, then notifies the owner.

1. Webhook trigger. The external form POSTs the enquiry payload. Fields like email, name, and message arrive in the trigger output.

2. Create contact. Add a Create contact step. Set email to {{ trigger.email }} and name to {{ trigger.name }}. If the contact already exists you get them back; if not, a fresh record is created. Either way you now have a contact_id. Label this step enquirer.

3. Add a note. Add an Add note step. Set entity_type to contact, entity_id to {{ enquirer.contact_id }}, and write the note as something like:

   Enquiry received {{ now.date }}: {{ trigger.message }}

4. Create deal. Add a Create deal step. Set name to Enquiry from {{ enquirer.name }}, primary_contact_id to {{ enquirer.contact_id }}, and stage_name to New enquiry. Label this step new_deal.

5. Notify the owner. Add a Send notification step (or a Send email if you prefer email delivery). The body can read:

   New enquiry from {{ enquirer.name }} ({{ enquirer.email }}).
   Deal opened: {{ new_deal.deal_id }}.

You can extend this

Add a Branch after step 2 to handle existing versus new contacts differently — for example, sending a different notification if the person is already in your system. Add a Wait and an Ask a person step to have an owner qualify the lead before the deal is opened.

Where to go next

• Building an automation — triggers, steps, and data flow from the start.
• Find contact — full field reference for contact lookup.
• Template variables — every {{ … }} reference available in a run.