HubSpot Integration

Overview

HubSpot is used as the CRM for managing student contacts, bills deals, and brand partner companies. The integration uses the official HubSpot PHP SDK.

File: api/utils/hubspotUtils.php

Setup

function instantiateHubSpot()
{
    return \HubSpot\Factory::createWithAccessToken($_ENV['HUBSPOT_API_KEY']);
}

The HUBSPOT_API_KEY is stored in AWS Secrets Manager. Different keys are used for sandbox vs production:

• Sandbox: Used in dev/uat environments
• Production: Used in prod and us-prod environments

Contact Management

Create Contact

createContact($properties)

Creates a new HubSpot contact with the given properties.

Find Contact

findContact($email)  // Returns contact or null

Searches for a contact by email using the HubSpot search API.

Update Contact

updateContact($properties, $contactId)

Updates an existing contact’s properties.

Bulk Upsert

bulkUpsertContacts($contacts, $lookupProperty, $batchSize = 100)

Batch creates or updates contacts. Handles deduplication by the lookup property (typically email). Processes in batches of 100 to stay within API limits.

Contact Properties by Region

US Contacts (created during SSO auth)

[
    'firstname', 'lastname', 'email', 'phone',
    'source' => 'US Database',
    'college_major', 'year_of_study',
    'university' => 'UNL',
    'fcm_token', 'birthday',
    'most_recent_like', 'most_recent_enquiry',
    'account_activation_date'
]

UK Contacts (created during bills flow)

[
    'firstname', 'lastname', 'email', 'phone',
    'city', 'source' => 'Housr Database',
    'address', 'hubspot_owner_id',
    'bills_drop_off_stage', 'bedrooms'
]

Bills Drop-Off Stages

The bills funnel is tracked through these stages:

Deal Management

Create Deal

createDeal($properties, $associations)

Creates a HubSpot deal (used when a bills signup is completed).

Deal properties include:

• dealname (address)
• city, bedrooms
• wifi_speed, price_per_week
• tenancy_start, tenancy_end
• bills_package_pricing (Unlimited, Unlimited Energy Only, etc.)
• pipeline (specific pipeline ID)
• dealstage (specific stage ID)
• hubspot_owner_id (randomly assigned sales team member)

Update Deal

updateDeal($email, $speed, $priceIncrease)

Updates a deal when broadband is upgraded. Finds the latest deal by tenancy start date and updates wifi speed and price.

Associate Contact to Deal

associateContactToDeal($dealId, $contactId)

Links a contact to an existing deal (used when housemates are added to a bills account).

Rental Action Tracking

When a viewing is requested, updateHubSpotRentalData() updates the contact:

// UK
'concierge_stage' => 'Concierge Enquiry Sent',
'customer_journey_stage' => 'rental',
'house_rented' => 'no',
'latest_rental_action' => timestamp,
'most_recent_enquiry' => timestamp
 
// US
'us_concierge_stage' => 'Enquiry Sent',
'latest_rental_action' => timestamp,
'most_recent_enquiry' => timestamp

Sales Team Assignment

getRandomSalesTeamMember($link, $includeTempStaff = true)

Randomly assigns contacts and deals to sales team members from the sales_team table. Can optionally exclude temporary staff.

Email Subscriptions

subscribeContactToEmails($email)
unsubscribeContactFromEmails($email)

Manages HubSpot email subscription status using communication preferences API. Subscription IDs differ by environment:

• US Production: 2091816379
• UK Production: 2025773313
• Sandbox: 2100952003

Brand Partner CRM

Company Management

handleHubSpotBrandPartner($data, $signedUp = false)

Manages brand partner CRM records:

1. Creates/updates contact for the brand partner representative
2. Creates/updates company record with brand partner details
3. On full signup: updates company with renewal date and signed status

Company Properties

[
    'phone', 'name' (business name),
    'package' (subscription tier),
    'hs_lead_status' ('partial_sign_up' or 'Signed'),
    'company_address', 'company_type' => 'Brand Partner',
    'brand_partner_renewal_date', 'signed_date'
]

Owners

getAllOwners()

Fetches all HubSpot owners. Used to match sales team email addresses to HubSpot owner IDs for deal/contact assignment.

Dependencies

"hubspot/api-client": "^13.0"