Airscale for HubSpot

Installation & Setup Guide

Complete step-by-step guide to install and use the Airscale enrichment app on your HubSpot account.

⏱ Estimated setup time: 5 minutes

What you'll find in this guide

What you'll be able to do after setup
Requirements
Step 1 — Install the Airscale app
Step 2 — Add your Airscale API key
Step 3 — Pin the Airscale card to the top
Step 4 — Run your first enrichment
How the data is written in HubSpot
Troubleshooting

What you'll be able to do after setup

Enrich any HubSpot contact with a verified email and phone number in one click
Access the enrichment directly from the contact card sidebar
Automatically update standard HubSpot properties (email, phone)
Keep a history of enrichment results on each contact

Requirements

A HubSpot account (any paid plan — Sales Hub Starter or above)
HubSpot admin rights (to install the app)
An Airscale account with an active API key — sign up here if you don't have one

Step 1 — Install the Airscale app on your HubSpot account

Ready to install?

Click the button below to launch the secure OAuth installation flow.

Install Airscale for HubSpot →

Click the install link

Open the install link above. On the landing page, click Connect HubSpot. If your HubSpot account is hosted in the EU, click the EU link instead.

Airscale x HubSpot landing page — The Airscale install landing page with the "Connect HubSpot" CTA and EU fallback link.

Select your HubSpot account

You'll be redirected to HubSpot. Select the HubSpot account where you want to install Airscale.

HubSpot account selection screen — HubSpot's account selection screen.

Review and approve the permissions

Review the permissions requested (read/write contacts and companies) and click Connect app.

HubSpot permissions approval screen — The permissions review screen — click "Connecter l'application" to confirm.

✓ Installation successful. At this point, Airscale has automatically created a Airscale Enrichment property group on your contact records and added the custom properties needed (airscale_found_email, airscale_found_phone, airscale_enrichment_date, airscale_email_status).

Step 2 — Add your Airscale API key

Open any contact record in HubSpot

Go to Contacts → select a contact.

Locate the Airscale Enrichment card

In the right sidebar, scroll down until you see the Airscale Enrichment card. If you don't see it, go to Step 3 to pin it properly.

Airscale card in the right sidebar — The Airscale Enrichment card as it appears in the right sidebar of a contact record.

Open the Settings modal

Inside the Airscale card, click Actions → Settings.

Actions dropdown expanded — The Actions dropdown showing all four options: Enrich All, Find Email, Find Phone, and Settings.

Paste your Airscale API key

A modal opens. Paste your Airscale API key into the input field. You can find your API key at app.airscale.io/dashboard?page=settings&tab=key.

Settings modal with API key input — The Settings modal where you enter and save your Airscale API key.

Save

Click Save API Key. You'll see a green confirmation: "API key saved successfully." Close the modal. Setup is complete.

To remove or replace your API key later: open the Settings modal again, then click Remove API Key (you'll have to click twice within 5 seconds to confirm).

Step 3 — Pin the Airscale card to the top (recommended)

By default, HubSpot may place the Airscale card at the bottom of the sidebar. For faster access, pin it to the top.

Open any contact record

Navigate to Contacts and open any contact.

Click "Customize" in the top navigation

At the top of the contact record, click Customize (or Personnaliser in French). No need to scroll — the button is in the top nav bar.

Customize button in the top navigation — Click "Customize" / "Personnaliser" in the top navigation of the contact record.

Select the view to customize

You'll be redirected to a page listing the available views. Click on the default view (or the specific view you want to customize).

Drag Airscale to the top

In the sidebar customization panel, locate the Airscale Enrichment card and drag it to the top (or just below "About this contact").

Drag-and-drop sidebar customization panel — The sidebar customization panel — drag the Airscale Enrichment card to the top of the list.

Save and refresh

Click Save at the top right, then refresh the contact page. The Airscale card is now pinned at the top.

Tip: This layout applies to all contacts for your user. If you want to apply it team-wide, ask your HubSpot admin to update the default contact record view.

Step 4 — Run your first enrichment

Open a contact with sufficient data

Make sure the contact has at least one of the following:

First name + Last name + Company name (or company domain), OR
A LinkedIn URL in the field "URL LinkedIn"

Click the Actions button

In the Airscale card, click Actions. You have four options:

Action	What it does
Enrich All	Finds both email + phone (recommended default)
Find Email	Finds verified email only
Find Phone	Finds mobile phone only (requires LinkedIn URL)
Settings	Opens the API key configuration modal

The Actions dropdown in the Airscale card with its four options.

Click Enrich All

A modal opens with a spinner: "Enriching contact...".

Enrichment in progress — The enrichment modal with a spinner while the request is being processed.

See the result

After a few seconds, you'll see:

✅ Enrichment complete! meaning the enrichment request was successfully launched
❌ An error message if something went wrong (e.g. missing input, API key not configured)

Enrichment complete confirmation — Success: the enrichment request was launched. Refresh the page to see the new data.

Refresh to see the new data

Close the modal and press Cmd+R (Mac) or Ctrl+R (Windows) to refresh the page. The new data appears:

In the Airscale card: Found email, Found phone, Status, Enrichment date
In the left sidebar: the standard HubSpot Email and Phone fields are automatically filled if they were empty

Enriched contact with data — The contact record after enrichment — Found Email, Found Phone, and Email Status are populated, and the standard HubSpot fields (Email, Phone) are filled too.

How the data is written in HubSpot

When Airscale finds an email or phone, the app writes:

Always, to Airscale custom properties

airscale_found_email
airscale_found_phone
airscale_email_status (Valid / Risky / Invalid)
airscale_enrichment_date

Only if empty, to standard HubSpot properties

email (Email)
phone (Phone number — "Numéro de téléphone")

This means your existing data is never overwritten. To force an update of the standard field, use Actions → Override Email or Override Phone once enrichment has run.

Troubleshooting

The Airscale card doesn't appear on the contact page

On the contact record, click Customize in the top nav → select your view → make sure "Airscale Enrichment" is enabled.
If it's not in the list, the install may have failed. Reinstall via the install link.

"API key not configured" error when enriching

Open the Airscale card → Actions → Settings → paste a valid API key from app.airscale.io/dashboard?page=settings&tab=key.

"Not enough data to find email" error

The contact is missing required input. Make sure one of the following is filled:
- First name + Last name + (Company name OR company domain)
- A LinkedIn URL in hs_linkedin_url or linkedin_url
Tip: associate a company to the contact in HubSpot. Airscale will use the associated company's domain automatically.

"LinkedIn URL is required for phone enrichment"

Airscale's phone enrichment requires a LinkedIn profile URL to work. Add it to the contact in the URL LinkedIn field.

The enriched data doesn't show up

Make sure you refreshed the page (Cmd+R / Ctrl+R) after closing the enrichment modal. HubSpot doesn't auto-refresh the sidebar.

I don't have enough Airscale credits

Check your balance at app.airscale.io. Top up via your account settings or contact us.