# HubSpot The HubSpot integration connects one HubSpot portal to your Lavanda account. - Contacts, companies, leads and bookings in Lavanda are sent to HubSpot. - From HubSpot, Lavanda takes new contacts and edits to a few contact and company fields. See [What comes back from HubSpot](#what-comes-back-from-hubspot). Lavanda runs the integration, so no middleware is needed. You approve Lavanda's HubSpot app once. Lavanda then sends records and matches them to existing HubSpot records. > **Note:** The integration is switched on per Lavanda account. To get started, contact your Lavanda account manager. ## In short | In Lavanda | In HubSpot | Direction | |---|---|---| | **Contact**, for example a resident, guarantor or booker | Contact | Lavanda sends all mapped fields. HubSpot sends back only **name, email and phone**. New HubSpot contacts are also copied into Lavanda. | | **Company** | Company | Lavanda sends all mapped fields. HubSpot sends back only **name and domain**. Companies created in HubSpot are **not** copied to Lavanda. | | **Lead**, an enquiry from someone who hasn't booked | The enquirer's contact, with lifecycle stage **Lead** | Lavanda → HubSpot only | | **Booking** | Deal, linked to the lead guest's contact | Lavanda → HubSpot only | Lavanda is the source of truth, except for a few fields that sync both ways: a contact's first name, last name, email and phone, and a company's name and domain. For those, the latest edit on either side usually wins, but a field that is empty in Lavanda never overwrites a HubSpot edit. The latest edit also doesn't win when two people share an email (see [Matching records](#matching-records)), when Lavanda can't take an edit made in HubSpot (see [What comes back from HubSpot](#what-comes-back-from-hubspot)), or when the edit empties a field (see [Things to know before connecting](#things-to-know-before-connecting)). All other fields sync from Lavanda to HubSpot only. If you edit one of them in HubSpot, Lavanda replaces your edit the next time the record changes in Lavanda, as long as the field is switched on and Lavanda has a value for it. See also [What isn't supported](#what-isnt-supported). ## Key terms | Term | Meaning | |---|---| | **Lavanda account** | Your organisation in Lavanda: one or more workspaces that share one list of contacts and companies. The HubSpot connection belongs to the Lavanda account, not to a single workspace, although Lavanda's settings pages and messages refer to it through your workspace. | | **Workspace** | A part of your Lavanda account that holds a set of buildings and their bookings. Booking sync is switched on per workspace. | | **Portal** | Your HubSpot account, identified by its Hub ID | | **Connection** | The link between one Lavanda account and one HubSpot portal | | **Lead** | In Lavanda, an enquiry from someone who hasn't booked yet. In HubSpot, Lavanda shows it by setting the person's *lifecycle stage* (HubSpot's field for where a contact is in your funnel) to *Lead*. | | **Lead guest** | The main person a booking is for. Other people on a booking can be guests, guarantors or booking agents. | | **Field mapping** | The rule that says which HubSpot property a Lavanda field is written to | | **Building ID** | Lavanda's ID for a building. It can be sent with deals and leads so you can see which building a record belongs to. | Property names in `code` font, like `firstname`, are HubSpot's internal property names. ## Things to know before connecting **Contacts from HubSpot are copied into Lavanda.** A HubSpot contact that isn't linked to Lavanda yet is copied the first time HubSpot reports a change to it. That happens when the contact is created, or when its name, email, phone or original source changes, including changes made by imports, forms, workflows or other apps. You can't filter by lifecycle stage, owner or source. Only the name, email and phone are copied. If a Lavanda contact already has that email and the same first and last name, the two are linked instead of copied. If the names differ, nothing is copied (see [Matching records](#matching-records)). A copied contact goes into your Lavanda account's shared contact list, not into a particular building. If your portal holds contacts you don't want in Lavanda, clean them up before you connect. **Lavanda updates the HubSpot records it matches, and creates new ones when it can't match.** The first time a Lavanda record syncs, Lavanda looks for a HubSpot record to update instead of creating a new one: - a contact or lead with the same email - a company with the same domain If it finds a match, it updates that record, names included. A contact or lead with no email, or a company with no domain, can't be matched, so it's always created as a new HubSpot record. See [Matching records](#matching-records). **Clearing a field doesn't clear it on the other side.** Lavanda never sends empty values, in either direction. If you remove a phone number in Lavanda, HubSpot keeps the old number, and the same applies the other way round. **Deals go into your default sales pipeline, using its standard stages.** Those stages are *Appointment scheduled*, *Contract sent*, *Closed won* and *Closed lost*. If any of them has been deleted from your default pipeline, bookings whose status maps to that stage can't create or update their deal, and they stop syncing until the stage is restored and Lavanda support restarts them. Check this before you turn on booking sync. If someone changes a deal stage in HubSpot, Lavanda resets it the next time the booking changes. See [Deal stages](#deal-stages). **Every default property must exist in your portal.** Lavanda writes to the HubSpot properties listed as *sent by default* below, including `date_of_birth`. If one of them doesn't exist in your portal, HubSpot rejects the **whole** update for every record that has a value for it, not just that field. **Only new and changed records are sent.** Records that already exist in Lavanda reach HubSpot the next time they change, not when you connect. See [Existing records](#existing-records). ## What isn't supported The following aren't available. If you need one, tell your account manager. ### Deals - Custom pipelines, or your own mapping of booking status to deal stage. - Deal amount, currency or owner. Use HubSpot workflows to assign owners. - Linking guarantors, other guests or companies to deals. Only the lead guest is linked. ### Contacts and leads - Showing whether someone is a lead guest, guest, guarantor or booking agent on their HubSpot contact. - A building field on contacts. A lead's Building IDs reach the enquirer's contact only once you map them (see [Leads](#leads)), and a booking's building ID can be sent on its deal once you map it. - HubSpot's Leads object. Leads appear as contacts with lifecycle stage **Lead**. - Choosing which HubSpot contacts are copied into Lavanda. - Writing HubSpot's built-in **Original source**. Map Lavanda's Source field to a custom property instead. ### General - Linking contacts to companies. - Custom objects, activities, notes, emails or tasks. - Changes made in HubSpot reaching Lavanda, other than new contacts and the two-way fields listed in [In short](#in-short). Edit addresses and other details, create companies, and change leads and bookings in Lavanda. - A sync log or status screen for your team. Your account manager can check sync history for you. - Salesforce and other CRMs. ## Requirements - A HubSpot portal that includes contacts, companies and deals. - A HubSpot user who is allowed to install apps in that portal. - A Lavanda **Admin** user. - Your Lavanda account's shared contact list set up. If you see *"HubSpot cannot be connected because this workspace has no CRM namespace yet"*, ask your account manager. Each Lavanda account connects to one HubSpot portal, and each portal connects to one Lavanda account. A person who books at two of your buildings is still one HubSpot contact. > **Warning:** Use a portal that isn't connected to any other Lavanda account. If you connect one that is, the > connection moves to your account without a warning. Then: > > - the other account's contacts, companies and leads stop syncing to the portal > - the other account's bookings keep arriving in the portal as deals > - the other account's field mappings carry over to your connection ## Connecting HubSpot 1. In Lavanda, go to **Settings → Integrations** and open **HubSpot**. 2. Click **Connect HubSpot**. HubSpot opens. Choose your portal and approve Lavanda's access. 3. You come back to Lavanda and see *"HubSpot connected. Your HubSpot account has been successfully connected."* Always start from **Connect HubSpot** in Lavanda, not from HubSpot, and finish approving within 15 minutes. If you start from HubSpot, cancel there, or take longer than 15 minutes, you end on a plain error page instead of back in Lavanda. Go back to Lavanda and click **Connect HubSpot** again. If you approve in time but Lavanda can't finish the connection, you come back to Lavanda and see *"HubSpot connection failed. Could not complete the HubSpot connection. Please try again."* Click **Connect HubSpot** again to start over. The HubSpot page now shows: - the connection status - the portal ID - the permissions granted - when the portal was connected ### Permissions Lavanda asks for read and write access to **contacts, companies and deals**. It uses them to: - create and update those records - read edits made in HubSpot - look for existing records to match HubSpot may also list *Leads* as an optional permission, which Lavanda doesn't currently use. Lavanda doesn't access your emails, files, tickets or marketing data. ### Turning on booking sync Contacts, companies and leads start syncing when you connect. Bookings are switched on **per workspace**: tell your account manager which workspaces should send bookings. You can start with one workspace and add others later. Once a workspace is switched on, every booking **created or changed** in it becomes a deal, whatever its status. That includes bookings with the status *Inquiry* (a booking status, not a lead) or *Requested*, and bookings from other sales channels. Bookings that already existed, and bookings imported in bulk whenever they're imported, get a deal the next time they change. A deal you delete in HubSpot isn't created again. In a group booking, each booking is a separate deal. ### Disconnecting Click **Disconnect** on the HubSpot settings page and confirm. Syncing stops straight away in both directions. Anything already in HubSpot stays there. > **Warning:** Disconnecting deletes the connection's settings in Lavanda. That means: > > - which HubSpot record belongs to which Lavanda record > - your field mappings > - which workspaces send bookings > - any changes still waiting to be sent > - HubSpot changes that arrived but haven't been applied in Lavanda yet > > **If you reconnect later:** > > - Lavanda matches contacts and leads again by email and companies by domain. It matches deals by name, but only deals > still called *Booking \*, so a renamed deal is created again as a new one. > - Matching happens the next time each record changes, not when you reconnect. > - You'll need to set up field mappings again and ask for booking sync to be switched back on. > - Records with no email or domain are created again as new records. > - Deals you deleted in HubSpot are created again when their booking next changes. > > **To remove Lavanda's access completely**, also uninstall the app in HubSpot (**Settings → Integrations → Connected > apps**). Disconnect in Lavanda first. If you only uninstall in HubSpot, or Lavanda's access is revoked there, Lavanda > still shows HubSpot as connected and its updates fail. Changes to contacts, companies and leads made while the > connection is broken aren't sent later: each record is sent the next time it changes after the connection is fixed. ## What Lavanda sends to HubSpot For each type of record, some fields are **sent by default** and others are **available to map**. A field that's available to map is only sent once you choose a HubSpot property for it (see [Choosing what's sent](#choosing-whats-sent)). ### Contacts Every contact in your Lavanda account is sent once it's created or changed, not only people with bookings. #### Sent by default | Lavanda field | HubSpot property | |---|---| | Primary email | `email` | | First name | `firstname` | | Last name | `lastname` | | Primary phone | `phone` | | Address lines 1 and 2, joined with a comma | `address` | | City | `city` | | Region | `state` | | Postcode | `zip` | | Country code | `country` | | Date of birth, as YYYY-MM-DD | `date_of_birth` | #### Available to map - **Identity:** - Lavanda reference (the contact's unique reference) - external CRM ID - secondary emails and secondary phone numbers (each joined with `;` and a space) - preferred name, title, pronoun - **Profile:** - gender, nationality, language, notes - source (how the person came to you) - tax identifiers, sent as `scheme:value`, for example a national tax number with its country scheme. If a person has several, they are joined with `;` and a space. - **Consents:** marketing by email, marketing by phone, privacy policy, terms accepted, and PIPL (China's personal information law). Each is sent as the date consent was given. - **Student details:** institution, subject, level of study, length of course, course start date. ### Companies **Sent by default:** name, domain, address, city, region (`state`), postcode (`zip`), country code (`country`) and notes (`description`). A company whose domain HubSpot doesn't accept isn't created or updated in HubSpot until its domain is corrected or removed in Lavanda. **Available to map:** tax number, Lavanda reference. ### Leads A Lavanda lead doesn't create a separate kind of HubSpot record. Lavanda updates the HubSpot contact of the person who made the enquiry, or creates it if there's no match, and sets their **lifecycle stage to Lead**. - **Every time one of a person's leads is created or changes, Lavanda sends *Lead* as the enquirer's lifecycle stage.** According to HubSpot's documentation, integrations can only move a lifecycle stage forward, so someone who is already further along, such as an *Opportunity* or *Customer*, keeps their later stage. - **Lead details on the contact come from whichever lead changed most recently.** If a person has several leads, each change overwrites the lead fields, and the contact's first name, last name and email too. - **A lead is matched on the enquirer's email.** If that's the same email as their Lavanda contact, the two share one HubSpot contact. A lead with no email always creates a new HubSpot contact. **Sent by default:** the enquirer's email, first name and last name, and `lifecyclestage = lead`. #### Available to map | Lavanda field | What it is | |---|---| | Source | Where the enquiry came from | | Origin | The channel the lead was created through, for example a website form | | Status | The lead's current stage in Lavanda | | Estimated check-in and check-out | Expected move-in and move-out dates | | Total adults, children, beds and units | Party size and space needed | | Building IDs | The buildings the lead is interested in, joined with `;` to fit a HubSpot multi-select property | > **Note:** HubSpot doesn't let other systems write its built-in **Original source** property. To see lead source in > HubSpot, map **Source** to a custom contact property, for example a text property called "Lavanda source". ### Bookings In a workspace with booking sync on, each Lavanda booking becomes **one HubSpot deal**. #### Sent by default | Lavanda field | HubSpot property | |---|---| | *Booking \* | `dealname` | | Booking status | `dealstage` (see below) | | Contract start date (move-in), as YYYY-MM-DD | `closedate` | **Available to map:** contract end date, building ID, the lead guest's Lavanda reference. #### How the deal is updated - The deal is sent again whenever the booking is **saved with a change**. Edits you make in HubSpot to the properties Lavanda sends are overwritten each time, but only when Lavanda has a value for that property. - **Linking:** each time the booking changes, Lavanda links the deal to the lead guest's HubSpot contact, found by its link or by email. If the contact isn't in HubSpot yet, Lavanda tries again at the next change. Links are only ever added, so if the lead guest changes, the deal ends up linked to both people. - **Deleted bookings:** when a booking is deleted in Lavanda, its deal isn't deleted, and its stage may not be updated (it can stay at *Closed won*). In HubSpot, you can update the deal's stage, delete the deal, or keep it as it is for reference. #### Deal stages | Lavanda booking status | HubSpot deal stage | |---|---| | Confirmed, including after check-in and check-out | Closed won | | Tentative (being signed or paid) | Contract sent | | Cancelled or declined | Closed lost | | Any other status: *Inquiry*, *Requested*, *Reserved*, *Awaiting payment*, *Expired*, *Tentative expired*, *Closed*, *Terminated* | Appointment scheduled | > **Warning:** These two cases affect pipeline reports: > > - An **expired** booking moves to *Appointment scheduled*, not *Closed lost*. > - A **terminated** booking moves back from *Closed won* to *Appointment scheduled*. ## What comes back from HubSpot | Change in HubSpot | What happens in Lavanda | |---|---| | A contact's first name, last name, email or phone is edited | The matching Lavanda contact is updated | | A company's name or domain is edited | The matching Lavanda company is updated | | A contact is created, or an unlinked contact's name, email, phone or original source changes | A Lavanda contact is created or linked (see [Matching records](#matching-records)) | | A company is created | Nothing | | Any other property, or any deal | Nothing. The change stays in HubSpot only. | - **Leads:** editing the person's name, email or phone in HubSpot updates their Lavanda contact once that contact has been sent to HubSpot. A contact is sent when it's created or changed in Lavanda. Nothing you change in HubSpot updates the lead itself. - **Blank values are ignored.** Emptying a field in HubSpot leaves Lavanda's value as it is. - **Phone numbers Lavanda can't accept are skipped**, and the rest of the change is still saved. Correct the number in HubSpot, using international format such as `+44 20 7946 0000`, and it's sent again. - **HubSpot may reformat values and send them back.** For example, HubSpot stores emails in lower case, so a Lavanda email with capitals is saved back in lower case. - **Retries:** if HubSpot or Lavanda is briefly unavailable, edits are retried for a limited time. Edits Lavanda refuses, for example invalid data, aren't retried. Fix the name, email or phone in HubSpot (for a company, its name or domain) and it's sent again. ## Matching records Lavanda remembers which HubSpot record belongs to each Lavanda record, so later changes update the same record. When a record isn't linked yet, Lavanda looks for a match first. ### From Lavanda to HubSpot | Lavanda record | Matched to HubSpot on | If there's no match, or no value to match on | |---|---|---| | Contact | Email | A new contact is created | | Lead | The enquirer's email | A new contact is created | | Company | Domain | A new company is created | | Booking | Deal name *Booking \* | A new deal is created | When Lavanda finds a match, it updates that HubSpot record with Lavanda's values, names included. ### From HubSpot to Lavanda A HubSpot contact can have an email that's already in Lavanda. In that case Lavanda links the two only if the first and last names also match, ignoring upper and lower case and spaces at either end. A Lavanda contact with no name is also linked. When the two are linked, HubSpot's name and phone are saved to Lavanda. If the names differ, nothing is linked and no new contact is created. This stops, for example, a parent and child who share an email being merged in Lavanda. > **Warning:** This name check only applies to contacts coming from HubSpot. > > When Lavanda sends a contact or lead that isn't linked to HubSpot yet, it matches on email alone. So if two people in > Lavanda share an email, they share one HubSpot contact. Every time either of them, or a lead for either of them, > changes in Lavanda, their details are sent to that shared contact. HubSpot then reports the change back, and Lavanda > saves it to the contact that was linked to HubSpot first. That person's name and phone number can be replaced by the > other person's. > > Use a different email for each person. ## Choosing what's sent Go to **Settings → Integrations → HubSpot → Configure field mapping**. There's a tab for each type of record: **Contact**, **Company**, **Lead** and **Booking**. For each field that's available to map, you can: - choose the HubSpot property it's written to, from the properties in your portal - switch it on or off HubSpot properties that are read-only or calculated are greyed out. Click **Save changes** on each tab you edit: saving applies only to the tab that's open. New mappings take effect shortly after you save, and apply only to records that change after that. Fields that are sent by default, such as email and deal stage, are dimmed and can't be changed. To change or switch off one of them, ask your account manager. > **Note:** > > - **Create custom properties in HubSpot first**, so they appear in the list. > - **Map each HubSpot property to only one Lavanda field.** If two fields share a property, one overwrites the other. > Don't map extra fields to `email`, `firstname`, `lastname`, `phone`, `name` or `domain`. If you do, that property > stops syncing back to Lavanda. > - **Dropdown and multi-select properties must already have, as an option, every value Lavanda sends.** If an option is > missing, HubSpot rejects the **whole** update for that record. > - For Building IDs, use a multi-select property whose option values are your Lavanda building IDs. Your account > manager can give you the list. > - For language, use a single-line text property. Lavanda stores language with a region, such as `es-es`, but > HubSpot's built-in language property only accepts codes like `es`. > - Lead status, title and pronoun are sent as Lavanda's codes, not the labels you see in Lavanda. Ask your account > manager for the list of codes, or use a single-line text property. Field mappings decide **what** is sent and **where** it goes. They don't change which direction each type of record syncs in (see [In short](#in-short)). The only way to stop Lavanda overwriting a HubSpot property is to switch off the field that writes to it. You can also use HubSpot's field permissions to make one-way properties read-only for your sales team. ## Timing and reliability - **Lavanda → HubSpot:** changes are sent shortly after they're made. - **HubSpot → Lavanda:** edits usually arrive shortly after they're made. - **Bookings** are sent in order. If HubSpot is unavailable or busy, Lavanda tries again for a limited time. After that, the deal catches up the next time the booking changes. - **Contacts, companies and leads** aren't retried automatically. If sending one fails, for example during a large burst of changes, it's sent again the next time it changes in Lavanda. > **Warning:** > > - **If HubSpot rejects a booking's data**, for example a value that isn't a dropdown option, that deal stops updating > until Lavanda support fixes it. If a deal's stage no longer matches its booking, tell your account manager. > - **If HubSpot rejects a booking the first time it's sent**, no deal is created for it. Tell your account manager. > - **If you delete a deal in HubSpot**, Lavanda stops updating that deal. To bring it back, ask Lavanda support. > - **If you delete a contact or company in HubSpot**, Lavanda stops updating it. A new lead for the same person creates > a new HubSpot contact. ## Existing records Lavanda only sends a record when it's created or changed **after** you connect. For bookings, that means after its workspace is switched on. Records that already existed, including bookings imported in bulk, are sent the next time they change. If you need existing records in HubSpot before you go live, raise it with your account manager when you plan the rollout. Before a large number of records arrives, check whether any of your HubSpot workflows react to new contacts or deals, for example by sending automatic emails or creating tasks. ## Personal data - **Name, email, phone, home address and date of birth are sent by default.** Other personal details, such as gender, nationality and tax identifiers, are only sent if you map them. Map only what your sales team needs. - **Consents are only sent if you map them**, as the date each consent was given. If someone withdraws consent in Lavanda, the date already in HubSpot isn't cleared. An unsubscribe in HubSpot doesn't reach Lavanda either. Manage consent changes in both systems. - **Erasing a person in Lavanda doesn't delete their HubSpot contact.** It replaces their name, email, phone, date of birth and street address in HubSpot with placeholders. City, postcode, state and country aren't replaced, and neither is any other field you mapped, such as secondary emails, secondary phone numbers, tax identifiers or nationality. Because the real email is replaced too, you can no longer find the contact by it. For an erasure request, find and delete the contact in HubSpot first, then ask Lavanda support to erase the person in Lavanda. - **Deleting a person in HubSpot doesn't remove them from Lavanda.** ## FAQ **Can HubSpot create bookings in Lavanda?** No. Bookings and leads are managed in Lavanda, and HubSpot only receives them. **Can our sales reps update deal stages?** They can, but Lavanda resets the stage the next time the booking changes. Treat Lavanda deals as read-only in HubSpot. **Can we test before going live?** Start with booking sync on a single workspace and check the results. Talk to your account manager about connecting a HubSpot test portal first. Use a test portal that isn't connected to any other Lavanda account (see [Requirements](#requirements)). **Do you support Salesforce?** Not today. ## Troubleshooting **An edit in HubSpot was overwritten.** That field only goes from Lavanda to HubSpot. Make the change in Lavanda. See [In short](#in-short). For a name or phone number, it can also mean another Lavanda contact with the same email was saved. For a name, a change to a lead with that email does the same. See [Matching records](#matching-records). **A contact in Lavanda has no phone number, but HubSpot has one.** Possible causes: Lavanda couldn't accept the number's format (correct it in HubSpot, using international format, and it's sent again), or the number was removed in Lavanda (removals aren't sent to HubSpot). **Bookings aren't showing as deals.** Check with your account manager that booking sync is on for that workspace. Bookings that haven't changed since it was switched on won't have a deal yet. **A deal is in the wrong stage.** Compare the booking's status with the [Deal stages](#deal-stages) table. Expired and terminated bookings move to *Appointment scheduled*. A deleted booking's deal may keep its last stage. **A contact or company stopped updating.** The usual cause is that HubSpot refused a value Lavanda sent, for example a company domain HubSpot doesn't accept, or a dropdown value that isn't one of the property's options. Correct the value in Lavanda, or add the option in HubSpot or map the field to a text property instead. The record updates the next time it changes in Lavanda. **A deal stopped updating.** Tell your account manager. A deal whose data HubSpot rejected needs Lavanda support to restart it. **Lavanda has contacts we didn't expect.** New HubSpot contacts are copied into Lavanda, and so are unlinked contacts whose name, email, phone or original source changes. See [Things to know before connecting](#things-to-know-before-connecting). **Something else looks wrong.** Send your account manager the contact, company or deal, roughly when it changed and what you expected to see. Lavanda support can check the sync logs.