Overview
Prerequisites
Creating the HubSpot Private App
LeadGenius API Configuration & Bypass
LeadGenius JSON Field Reference
Creating Custom Properties inside HubSpot
Importing Contacts & Data Mapping 6.5. Companies & Primary Associations (required for a complete import)
Creating Saved Views (For SDRs)
Complete Automated Execution
Troubleshooting
Verification Checklist

0. Overview

What This Does

LeadGenius Automation API  →  HubSpot Contacts + Companies + Associations
 Over 120 nested objects       Native Custom CRM Properties (lg_*)
  Full X-Admin-Key Bypass      Property Group + correct PRIMARY company link

⚠️ The one rule that prevents data corruption

HubSpot batch endpoints do NOT return results in input order. Never pair a contact to a company by list index. Always correlate each batch result to its input by a key the API echoes back (email, unique id, company domain), and build associations via map lookups.

Pairing contacts[i] with companies[i] from two separate batch calls previously attached contacts to the wrong company and marked it primary (~10,400 contacts, ~8,000 junk companies on one portal). The company/association script here is built to avoid this; see references/companies-and-associations.md.

Architecture

The LeadGenius API structure is highly complex, often burying core intel like Company Descriptions and direct phone arrays inside concatenated pipe-separated :Mobile: | :Direct: strings or JSON-wrapped string layers ({"subject": "...", "content": "..."}).

This guide bridges the gap structurally by:

Dynamic Authentication: Using X-Admin-Key arrays to completely override LeadGenius standard API throttling bottlenecks.
Schema Standardization: Emitting native HTTP POST requests to create a localized leadgenius_data Property Group on HubSpot immediately upon bootstrap.
Deep Extraction: Natively unpacking AI analysis, recommendation texts, and formatting integer matrices without UI friction.
Massive Deduplication: Launching 100-batch recursive endpoints routing via HubSpot's High-Level Upsert endpoints triggering on standard email objects.

API Strategy Summary

Operation	API Used	Why
HubSpot Authentication	Private App Token (Bearer)	Immediate API routing with no OAuth authorization hassle.
LeadGenius Fast Extraction	`X-Admin-Key` Headers	Overrides the typical API rate limits (HTTP 429) natively.
Create Property Group	`crm/v3/properties/groups`	Ensures all AI parameters don't clutter the global CRM view.
Create Properties	`crm/v3/properties/contacts`	Establishes schema integrity instantly without manual input.
Insert/Update Leads	`crm/v3/objects/contacts/batch/upsert`	Standard CRUD handling utilizing `idProperty: email`.
Create List Views	❌ Manual Process	HubSpot restricts visual dashboard component programmatic builds.

1. Prerequisites

Software Requirements

pip3 install requests python-dotenv

Environment Configuration

Create a local .env file at the root of your execution directory securely:

# LeadGenius
LGP_API_KEY=your_standard_lg_token
LGP_MASTER_KEY=your_admin_bypass_token

# HubSpot — the scripts read HUBSPOT_ACCESS_TOKEN (HUBSPOT_API_KEY and a
# `hubspot-app=` line are also accepted as fallbacks for compatibility).
HUBSPOT_ACCESS_TOKEN=your_private_app_bearer_token

The HubSpot private app also needs company + association scopes to create company objects and links: add crm.objects.companies.read, crm.objects.companies.write, and crm.objects.contacts association permissions (see §2).

2. Creating the HubSpot Private App

In order to seamlessly authorize interactions with your Hubspot infrastructure, you must secure a native Private App token.

Click the ⚙️ Settings icon in your HubSpot main navigation bar.
In the left sidebar, route to Integrations > Private Apps.
Click Create private app.
Basic Info: Name your deployment LeadGenius Sync.
Under the Scopes tab, explicitly inject these functional read/write headers:
- crm.objects.contacts.read
- crm.objects.contacts.write
- crm.schemas.contacts.read
- crm.schemas.contacts.write
- crm.objects.companies.read
- crm.objects.companies.write
- crm.schemas.companies.read
- crm.schemas.companies.write
Click Create app and securely port your new Access Token directly to HUBSPOT_API_KEY in your .env.

3. LeadGenius API Configuration & Bypass

Standard integrations fail aggressively on large environments because LeadGenius throttles basic API tokens recursively. We invoke native administrative clearance bypassing this framework utilizing X-Admin-Key.

When querying the core lead engine, we establish dual headers natively:

LG_HEADERS = {
    'X-API-Key': os.getenv('LGP_API_KEY'),
    'X-Admin-Key': os.getenv('LGP_MASTER_KEY')
}
import requests
r = requests.get("https://api.leadgenius.app/api/automation/leads", headers=LG_HEADERS)

[!CAUTION] When X-Admin-Key is utilized natively, the LeadGenius API structurally shifts the standard JSON payload directly inside an isolated data dictionary layer. Any scripts targeting .get('id') will fatally fail unless structurally targeting .get('data', {}).get('id').

4. LeadGenius JSON Field Reference

LeadGenius exports deep multi-layered JSON metadata. We meticulously map these dynamically into HubSpot.

Standard Field Mapping (Base Infrastructure)

LeadGenius Object Column	HubSpot Internal ID	Execution Action
`firstName`	`firstname`
`lastName`	`lastname`	Maps to "Unknown" if natively null.
`title`	`jobtitle`
`companyName`	`company`
`email`	`email`	Serves as the primary ID key for Batch Upsert arrays.

Complex AI Extraction Fields (Custom Framework)

LeadGenius Nested Object	HubSpot Internal Structure	Python Filter Strategy
`aiLeadScore.ai_score`	`lg_ai_score`	Parsed securely via `int(float(val))` removing decimal vectors natively.
`capture_all > :Company Description:`	`lg_company_description`	Regex mapped natively overriding limited `companyValueProp` matrices.
`phoneNumber` / `sanitizedPhoneNumber`	`mobilephone`	Resolves uniquely against HQ endpoints strictly using standard direct routes.
`ai1` / `aiColdEmail`	`lg_cold_email`	Structurally stringified clearing heavily fragmented `{"subject"}` objects and `<br>` elements natively.
`aiScoreJustification`	`lg_justification`	Safely encoded utilizing multi-line parameters stripping `\n` carriage limits.
`aiScoreRecommendation`	`lg_recommendation`	Text-area extraction.

Enrichment Target References

Target Endpoint	HubSpot Structural Map	Type Format
`linkedinUrl`	`lg_linkedin_url`	URL Block
`companyLinkedinUrl`	`lg_company_linkedin`	URL Block
`seniority`	`lg_seniority`	Text Format

5. Creating Custom Properties inside HubSpot

All integrated properties must systematically map to lg_ prefixed tables under a master leadgenius_data component.

Example Schema Execution Array

The following snippet natively configures standard extraction components automatically:

import requests, os
from dotenv import load_dotenv

load_dotenv()
HS_HEADERS = {
    'Authorization': f"Bearer {os.getenv('HUBSPOT_API_KEY')}",
    'Content-Type': 'application/json'
}

def setup_properties():
    # 1. Establish Property Group
    group_req = requests.post(
        'https://api.hubapi.com/crm/v3/properties/contacts/groups',
        headers=HS_HEADERS,
        json={"name": "leadgenius_data", "displayOrder": -1, "label": "LeadGenius AI Data"}
    )
    
    # 2. Extract and Post Objects
    properties = [
        {"name": "lg_ai_score", "label": "LG AI Score", "type": "number", "fieldType": "number", "groupName": "leadgenius_data"},
        {"name": "lg_company_description", "label": "LG Company Description", "type": "string", "fieldType": "textarea", "groupName": "leadgenius_data"},
        # Added extra...
    ]
    
    for prop in properties:
        requests.post('https://api.hubapi.com/crm/v3/properties/contacts', headers=HS_HEADERS, json=prop)

6. Importing Contacts & Data Mapping

Once schema arrays are structurally localized on HubSpot, you bypass the standard REST API limits using High-Volume Endpoints (batch/upsert).

def build_hs_contact(lead):
    # Parses unique JSON strings
    def parse_email_json(text):
        if not text: return ""
        try:
            import json
            parsed = json.loads(text)
            return f"Subject: {parsed.get('subject', '')}\n\n{parsed.get('content', '')}".replace('<br>', '\n')
        except: return str(text).replace('<br>', '\n')

    props = {
        "email": lead.get('email'),
        "firstname": lead.get('firstName'),
        "lg_ai_score": str(int(float(lead.get('aiLeadScore', {}).get('ai_score', 0)))),
        "lg_company_description": lead.get('capture_all_parsed', {}).get('Company Description')
    }
    return {k: v for k, v in props.items() if v}

# Batch Upsert Loop
chunk = leads[0:100]
inputs = [{"idProperty": "email", "id": c['email'], "properties": c} for c in chunk if c.get('email')]

response = requests.post(
    'https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert', 
    headers=HS_HEADERS, 
    json={"inputs": inputs}
)

6.5. Companies & Primary Associations

Upserting contacts alone leaves each contact with a company text field but no company object and no link — so company-level views, scoring, and ownership don't work. Run the company step to create companies and set the correct primary association.

# after contacts are imported (lg_to_hs.py)
python3 scripts/lg_companies_associations.py <file.csv>

What it guarantees:

Companies deduped by domain (lg_company_key = "domain:<domain>"), name only as a fallback — no duplicate-company explosion.
Each contact associated to its company and that company set primary (associationTypeId 1) via an idempotent PUT.
Results correlated by echoed key (email / company key), never by list index.
Safe to re-run: a clean second run prints associations set primary: 0 (unchanged=N).

Audit against the company domain, not the email domain. Subsidiaries/local entities legitimately differ (an @schueco.com contact belongs to Schüco France / schuco.fr).

If the portal is already corrupted (contacts show wrong/multiple companies), do not just re-import — follow references/remediation-playbook.md first (flip primary → remove parasite links → fix never-associated → archive orphan companies, all reversible).

Full rationale and endpoints: references/companies-and-associations.md.

7. Creating Saved Views (For SDRs)

UI Saved Layouts cannot be programmatically initiated via Standard Endpoints securely. Administrators must instruct internal teams utilizing the following manual pipeline layout configurations:

Launch HubSpot and access the Contacts Data Table.
Navigate directly to Add View > Create New View and define SDR LeadGenius Outbound.
Select Edit Columns and firmly integrate:
- Lead Status
- LG AI Score
- LG Recommendation
- Mobile Phone
Make sure your SDR operators utilize Settings > Objects > Contacts > Record Customization natively to permanently anchor the leadgenius_data sidebar at the apex of user visual fields on the Contact Card.

8. Complete Automated Execution

The unified deployment matrix script integrating Schema Build, Extraction Arrays, Bypass Authentication, JSON Sanitization string manipulation, and Batch Array POSTing natively is available securely within the executed script pipeline.

Simply run recursively:

python3 scripts/lg_full_to_hs.py

9. Troubleshooting

Error Code/Symptom	Direct Internal Cause	Execution Fix
`PROPERTY_DOESNT_EXIST`	Script failed to setup custom Schema.	Wipe memory cache and rerun step 1 property validation.
`KeyError: 'data'`	The LeadGenius script failed to use `X-Admin-Key` properly.	Verify the `LGP_MASTER_KEY` is fully established in standard `.env`.
Zero Properties Imported	The Batch API failed matching standard fields.	Ensure array targets the CRM Endpoint Native Field Identifier mapping (`email`).
`HTTP 429 (HubSpot)`	Too many calls in the 10s rolling window.	The scripts self-throttle to ~0.15s/call and retry with backoff; lower concurrency if you add parallelism.
`HTTP 429 (LeadGenius)`	Reverted to Standard LeadGenius Limits.	Confirm bypass admin keys are pushed exactly as `X-Admin-Key`.
Contacts linked to the wrong company / marked primary	Batch results paired by list index (order not guaranteed).	Use `lg_companies_associations.py`, which correlates by echoed key. Never pair `contacts[i]`↔`companies[i]`.
Contacts have 2–3 companies after re-running	Association step not idempotent; re-run added links.	The company script checks the current primary and skips if correct; archive extras per `remediation-playbook.md`.
Thousands of domainless duplicate companies	Company keyed by name only.	Dedup by domain (`lg_company_key = "domain:<domain>"`); name only when no domain.
Audit shows "WRONG" but company looks right	Audited against email domain, not company domain.	Compare to the row's Company Domain; subsidiaries/local entities differ legitimately.
`401 Unauthorized` on companies/associations	Private app missing company/association scopes.	Add `crm.objects.companies.*` and association scopes (see §2).

10. Verification Checklist

Always run on a small slice first, verify, then the full import.

python3 scripts/lg_to_hs.py <file.csv>                       # contacts
python3 scripts/lg_companies_associations.py <file.csv>      # companies + primary links
python3 scripts/lg_companies_associations.py <file.csv>      # re-run: must be idempotent
python3 scripts/hs_audit_primary.py <file.csv> --limit 100   # audit

Confirm:

Each contact with a corporate email has exactly one primary company (associationTypeId 1).
The primary company matches the row's Company Domain (not the email domain).
Re-running the company step changes nothing (set primary: 0, unchanged=N).
Companies created ≈ distinct employers, not ≈ one per contact.
hs_audit_primary.py reports WRONG: 0 (ignoring legitimate subsidiary-domain cases).

Bundled scripts & references

File	Purpose
`scripts/lg_to_hs.py`	Upsert contacts + `lg_*` properties (idempotent by email).
`scripts/lg_companies_associations.py`	Create companies, set correct primary association (idempotent, key-correlated).
`scripts/hs_audit_primary.py`	Audit primary company vs. source.
`references/companies-and-associations.md`	Why/how associations are done safely (root cause).
`references/remediation-playbook.md`	Repair an already-corrupted portal (reversible).

hubspot-leadgenius

LeadGenius → HubSpot Import API Pipeline

Table of Contents