---
title: "HubSpot Integration"
url: https://docs.aila.fyi/integrations/hubspot
source: https://docs.aila.fyi/llms.txt
---

# HubSpot Integration

Aila sends call recaps and mapped mortgage fields into HubSpot. Aila extracts the fields in this schema from the call. HubSpot receives only the objects below, plus the properties that you map.

Create each HubSpot property in your portal first. Aila does not create HubSpot properties.

---

## Connect

1. Open **Settings → Connections → HubSpot**.
2. Click **Connect**.
3. Sign in to HubSpot and allow Aila.
4. Aila needs a HubSpot owner: the Aila user’s HubSpot user, or the Contact’s owner if the Aila user has no HubSpot owner. If neither exists, Aila writes nothing.
5. Open **Settings → Custom Datasets**. Map Aila fields to HubSpot Contact and Deal properties that already exist in your portal.

Reconnect if Aila asks. New scopes are required for Deal, Task, and Call writes.

---

## What Aila writes

| HubSpot object | When | What |
| --- | --- | --- |
| Contact | Every matched or created destination | Create uses `email`, `firstname`, `lastname`, and `hubspot_owner_id`. Create does not set `phone`. Updates use mapped `contact.*` properties only. |
| Deal | When mapping includes `deal.*` and Aila selects one Deal | Mapped Deal properties. Aila does not create a Deal. |
| Note | Create Summary = In Notes (default) | Call summary, rapport, follow-ups, and fields marked include-in-summary. Reprocess can add a second Note. |
| Call | Log Calls = As Call engagements | Completed call: time, duration in milliseconds when known, body, Aila URL, and owner. Associated to Contact and Deal. Idempotent. |
| Task | Create Action Items = As Tasks | One Task per follow-up line. Associated to Contact and Deal. Idempotent. |

Aila sets Aila contact status from `hs_is_closed` / `hs_is_closed_won` on the selected Deal. Aila does not change Deal stage.

Call, Task, and Note may associate to a Deal. That is HubSpot-specific. Salesforce Tasks attach to the person only.

The call summary Note can include a Social Security number if the model put it in the summary text. Mapped `ssn` properties are still blocked.

---

## Match rules

Phone path (match only; does not create):

1. Last 10 digits of HubSpot `phone` or `mobilephone`.

Email/name path (creates if missing):

2. Exact Contact `email`.
3. Name search, then create Contact (`email` / `firstname` / `lastname` / `hubspot_owner_id`).

Owner:

4. Prefer the Aila user’s HubSpot owner. Else use the Contact owner. If neither exists, Aila writes nothing.

Deal selection: page all associated Deals. Exactly one Deal → use it (even if closed). Else pick one open Deal (`hs_is_closed` is not true), newest `hs_lastmodifieddate`. If two or more open Deals remain, Aila skips Deal property writes and still writes Contact, Note, Call, and Task. The call shows that skip. Aila does not use an LLM to pick among Deals.

---

## Mapping rules

- **Overwrite**: replace the HubSpot value.
- **Skip if exists**: write only when the HubSpot property is empty.
- **Append**: add a timestamped line to text properties.

Empty Aila values do not clear HubSpot properties.

Map Aila paths to `contact.{internalName}` or `deal.{internalName}` (for example `contact.firstname`, `deal.amount`). The HubSpot internal name must already exist.

Standard Contact fields you may map without a custom property: `firstname`, `lastname`, `email`, `phone`, `mobilephone`, `address`, `city`, `state`, `zip`.

---

## Fields Aila will not map

These Aila paths never write to HubSpot, even if a mapping exists:

- `client_details.ssn`
- `co_borrower_details.ssn`
- `demographics.ethnicity`
- `demographics.race`
- `demographics.gender`
- `demographics.co_borrower_ethnicity`
- `demographics.co_borrower_race`
- `demographics.co_borrower_gender`

Keep Social Security numbers and HMDA demographics in Aila / MISMO export.

Money values in this catalog are often `$X,XXX` strings. Aila strips currency punctuation before a HubSpot number property. Enums use Aila labels; HubSpot option internals must match or that one field is skipped.

---

## Source schema (Aila mortgage dataset)

HubSpot gets a property only when you map that path to `contact.{property}` or `deal.{property}`. Optional groups (`call_disposition`, `investor_details`, `pipeline_state`, `base.send_application`) appear only on the matching prompt variant.

### `base` (Info)

| Path | Type |
| --- | --- |
| `base.summary` | text |
| `base.contact_name` | text |
| `base.rapport_building` | array (text property only) |
| `base.follow_ups` | array (text property only) |
| `base.is_voicemail` | boolean |
| `base.counterparty_type` | text |
| `base.send_application` | boolean (optional prompt flag) |

There is no `base.disposition`. Disposition is `call_disposition.call_disposition`.

### `client_details`

`name`, `phone`, `email`, `ssn` (blocked), `dob`, `citizenship_status`, `working_with_realtor`.

### `client_address`

`street_address`, `address_line_2`, `unit_type`, `unit_identifier`, `city`, `state`, `zip_code`, `county`, `months_at_address`, `residency_basis`.

### `property_address`

`street_address`, `address_line_2`, `unit_type`, `unit_identifier`, `city`, `state`, `zip_code`, `county`.

### `purchase_details`

`property_use_type`, `property_type`, `property_price`, `min_purchase`, `max_purchase`, `annual_property_tax`, `annual_insurance`, `monthly_hoa`, `year_built`, `fha_section_of_act`, `financed_unit_count`, `property_mixed_use`, `property_existing_clean_energy_lien`, `property_estate_type`, `move_in_timeline`.

### `proposed_loan_details`

`purpose`, `type`, `down_payment`, `amount`, `rate`, `term_years`, `desired_term`, `desired_monthly_payment`, `interest_in_impound`, `cashout_amount`, `cashout_percent`, `has_balloon_payment`, `is_interest_only`, `has_prepayment_penalty`, `has_temporary_buydown`, `has_below_market_subordinate`, `is_energy_related`, `is_renovation_loan`, `lender_credit_amount`, `seller_credit_amount`, `gift_amount`, `employer_assistance_amount`, `estimated_closing_date`, `va_first_time_use`, `va_funding_fee_exempt`, `va_case_number`, `closing_cost_points_discount`, `cash_out_purpose_primary`, `rate_watch_set`, `rate_watch_trigger_rate`, `competing_offer_rate`.

### `qualification_details`

`credit_score`, `credit_consent_received`, `monthly_rent`, `employer`, `employment_status`, `employment_reporting`, `employment_start_date`, `is_first_time_home_buyer`, `is_veteran`, `had_bankruptcy`, `had_foreclosure`, `marital_status`, `dependent_count`, `dependent_ages`, `currently_owned_financed_properties_count`, `has_collection_or_charge_off`, `collection_amount`, `collection_creditor_name`, `collection_status_description`, `outstanding_judgments`, `party_to_lawsuit`, `presently_delinquent_federal_debt`, `prior_deed_in_lieu`, `prior_short_sale`, `proposed_clean_energy_lien`, `undisclosed_borrowed_funds`, `undisclosed_comaker_of_note`, `undisclosed_credit_application`, `undisclosed_mortgage_application`, `special_borrower_seller_relationship`, `pay_frequency`, `bankruptcy_must_wait_until`, `secondary_employment_status`.

### `employer_details`

`position_description`, `address_line`, `city`, `state`, `zip_code`, `months_at_employer`.

### `previous_employer_details`

`employer`, `employment_status`, `position_description`, `employment_start_date`, `employment_end_date`, `monthly_income`, `address_line`, `city`, `state`, `zip_code`.

### `income_details`

`base`, `commission`, `stock_compensation`, `bonuses`, `overtime`, `social_security`, `pension`, `pension_2`, `disability`, `retirement`, `rental_income`, `other_income`, `other_income_description`, `has_social_security_income`, `has_pension_income`, `has_retirement_distribution_income`, `secondary_gross_monthly_income`.

### `asset_details`

`property_value`, `property_equity`, `business_value`, `business_equity`, `liquid_value`, `checking_balance`, `savings_balance`, `money_market_balance`, `stock_brokerage_balance`, `retirement_account_balance`, `primary_bank_name`, `cash_on_hand_earnest_money`.

### `debt_details`

`total_credit_card_debt`, `monthly_mortgage_payments`, `monthly_car_payments`, `monthly_tax_and_insurance_payments`, `monthly_credit_card_payments`, `monthly_student_loan_payments`, `monthly_personal_loan_payments`, `monthly_other_payments`, `monthly_child_support`, `monthly_alimony`, `monthly_separate_maintenance`, `remaining_mortgage_terms`, `remaining_personal_loan_terms`, `mortgage_creditor_name`, `auto_creditor_name`, `student_loan_servicer_name`, `credit_card_issuer_names`, `personal_loan_creditor_name`, `mortgage_unpaid_balance`, `mortgage_payment_includes_taxes_insurance`, `auto_loan_unpaid_balance`, `student_loan_unpaid_balance`, `personal_loan_unpaid_balance`, `remaining_car_terms`, `remaining_student_loan_terms`, `remaining_other_terms`, `loan_type_original`.

### `demographics` (blocked)

`ethnicity`, `race`, `gender`, `co_borrower_ethnicity`, `co_borrower_race`, `co_borrower_gender`. Never write to HubSpot.

### `co_borrower_details`

Not the same shape as borrower groups. Income is inline (`base_income`). `ssn` is blocked.

`name`, `phone`, `email`, `ssn` (blocked), `dob`, `credit_consent_received`, `citizenship_status`, `marital_status`, `employer`, `employment_status`, `employment_start_date`, `base_income`, `commission`, `bonuses`, `overtime`, `social_security`, `pension`, `pension_2`, `disability`, `retirement`, `rental_income`, `is_veteran`, `had_bankruptcy`, `had_foreclosure`, `dependent_count`, `dependent_ages`, `outstanding_judgments`, `party_to_lawsuit`, `presently_delinquent_federal_debt`, `prior_deed_in_lieu`, `prior_short_sale`, `proposed_clean_energy_lien`, `undisclosed_borrowed_funds`, `undisclosed_comaker_of_note`, `undisclosed_credit_application`, `undisclosed_mortgage_application`, `special_borrower_seller_relationship`.

### `co_borrower_address`

`street_address`, `address_line_2`, `unit_type`, `unit_identifier`, `city`, `state`, `zip_code`, `county`, `months_at_address`. No `residency_basis`.

### `co_borrower_employer_details` / `co_borrower_previous_employer_details`

Same keys as `employer_details` / `previous_employer_details`.

### `existing_property_details`

`disposition`, `street_address`, `city`, `state`, `zip_code`, `estimated_value`, `unpaid_mortgage_balance`, `monthly_rental_income`, `estimated_net_proceeds`.

### `owned_properties` / `additional_employers`

Arrays of objects: `owned_properties.properties`, `additional_employers.employers`. Map the whole array to a HubSpot text property. Indexed first-record paths: `owned_properties.properties.0.disposition` and `additional_employers.employers.0.employer`. There is no `owned_properties.street_address`.

Owned-property object keys: `disposition`, `street_address`, `unit_designator_type`, `unit_identifier`, `city`, `state`, `zip_code`, `property_current_usage_type`, `estimated_value`, `unpaid_mortgage_balance`, `monthly_mortgage_payment`, `monthly_hoa_expense`, `monthly_tax_insurance_expense`, `monthly_maintenance_expense`, `monthly_rental_income`, `monthly_net_rental_income`, `estimated_net_proceeds`.

Additional-employer object keys: `borrower_role`, `status_type`, `employer`, `employment_status`, `position_description`, `employment_start_date`, `employment_end_date`, `monthly_income`, `address_line`, `city`, `state`, `zip_code`.

### `pipeline_state` (post-application calls)

`uw_status`, `conditional_approval_date`, `clear_to_close_date`, `condition_count`, `conditions_outstanding` (array), `file_suspended`, `esign_status`, `missing_documents` (array), `doc_chase_urgency`, `appraisal_status`, `appraisal_value`, `appraisal_gap`, `repairs_required`, `reinspection_date`, `title_status`, `title_commitment_received`, `title_objections_resolved`, `title_company_name`, `homeowners_insurance_bound`, `flood_zone_required`, `flood_insurance_bound`, `insurance_premium_confirmed`, `signing_appointment_datetime`, `signing_method`, `closing_location`, `closing_coordinator_name`, `closing_coordinator_phone`, `notary_confirmed`, `borrower_id_requirement_met`, `wire_instructions_sent`, `wire_instructions_verified`, `wire_amount`, `wire_fraud_verification_call_completed`, `cashier_check_alternative`, `rate_lock_status`, `rate_lock_expiration_date`, `rate_lock_extension_needed`, `final_cash_to_close`, `final_apr`, `final_monthly_payment`, `cd_amended_or_original`.

### Optional groups (prompt variants)

- `call_disposition.call_disposition`
- `investor_details.rehab_budget`, `current_rental_income`, `expected_rental_income`, `expected_value`

### Org-specific datasets

CliffCo Past Client Check-In is not part of the default HubSpot schema. That org’s custom prompt adds `past_client_check_in.call_purpose`, `in_market_intent`, `servicing_topic`, `next_step`, `handoff_to_loan_officer`. Those paths map the same way when that prompt is on the call.

---

## Settings

| Setting | Values | Default |
| --- | --- | --- |
| Create Summary (`create_summary`) | Off, In Notes | In Notes |
| Log Calls (`log_calls`) | Off, As Call engagements (`as_calls`) | Off |
| Create Action Items (`create_action_items`) | Off, As Tasks | Off |

---

## Troubleshooting

- **No write**: no HubSpot owner on the Aila user and none on the Contact.
- **Deal fields empty**: no associated Deal, or more than one open Deal (see the skip on the call).
- **Mapped field empty**: the call did not extract that path, the HubSpot property internal name does not match, the property is read-only, or an enum option did not match.
- **Reconnect prompt**: grant the new Deal / Task / Call / schema scopes.
- **Two Notes for one call**: Notes are not idempotent. Calls and Tasks are.

---

## Next Steps

- [Call setup](https://docs.aila.fyi/settings/call-setup) — Map Aila paths to HubSpot properties
- [Settings > Connections](https://docs.aila.fyi/settings/connections) — Connect or reconnect HubSpot