How do I configure the Luminous–HubSpot integration, including authorization, where to connect, and how data maps between the two systems?

Overview

The Luminous–HubSpot integration lets your sales team create and manage invoices directly inside HubSpot deals via the Luminous CRM Card, while keeping company, contact, and deal data in sync between both platforms. This article walks through where to set up the connection, how to authorize it via OAuth, what each configuration field does, and exactly which data fields map between the two systems.

Step 1 — Find the HubSpot integration in Luminous

Click your name in the top-right corner and choose Settings / Integrations.
You land on the Settings / Integrations page.
Click + Add Integration to open the integration catalog.
Click the HubSpot tile.
Give the connection a name and click Save and authorize. This saves the account and sends you to HubSpot to authorize.

Step 2 — Authorize with HubSpot (OAuth)

The HubSpot integration uses OAuth — Luminous never asks you to paste in an API key directly.

After creating the integration account (or when editing an existing one), click the Connect HubSpot button inside the form.
- If the account hasn't been saved yet, Luminous will save it automatically before redirecting.
You are taken to HubSpot's OAuth consent screen. Sign in to HubSpot if prompted, then review and approve the requested permissions (these cover reading contacts, companies, and deals, and writing deals and line items).
HubSpot redirects you back to Luminous. Luminous exchanges the authorization code for an access token and a refresh token, both of which are stored securely on the integration account.
After authorization completes, click Test Credentials to confirm the connection is working. Luminous will also automatically record your HubSpot Portal ID on your account at this point.

Tip: If you ever need to re-authorize (e.g., after revoking access in HubSpot), simply click Connect HubSpot again on the same integration account.

Step 3 — Configure the integration settings

Once connected, you will see several configuration fields on the integration account form.

Checkboxes

Setting	What it does
Create Items in HubSpot	When enabled, Luminous will create a matching product record in your HubSpot product library if one does not already exist when syncing a line item.
Sync Line Items	When enabled, each line item on a Luminous invoice is created or updated as a HubSpot line item associated with the corresponding deal.

JSON mapping fields

All four mapping fields accept a JSON object. Default values are pre-filled as placeholder text — copy them in to get started, then customize as needed.

Status Mapping

Maps Luminous invoice/order statuses to your HubSpot deal stage IDs. The key dealStageField lets you specify the HubSpot property name to update (defaults to dealstage).

Default example:

{
  "invoice": {
    "DRAFT": "<your-draft-stage-id>",
    "ACTIVE": "<your-active-stage-id>",
    "Paid": "<your-paid-stage-id>",
    "COMPLETED": "<your-completed-stage-id>",
    "Partially_paid": "<your-partial-paid-stage-id>",
    "inProduction": "<your-in-production-stage-id>"
  }
}

Replace each placeholder with the numeric deal stage ID from your HubSpot pipeline settings.

Deal Field Mapping

Maps Luminous invoice fields to HubSpot deal properties. The format is "luminous_field": "hubspot_property".

Default mapping:

{
  "total_amount": "amount",
  "id": "description",
  "total_units": "total_quantity"
}

Business Account Mappings

Controls how HubSpot company properties map into Luminous Business Accounts during a sync. The format is "hubspot_property": "luminous_field".

Default mapping:

{
  "companyId": "hubspot_company_id",
  "name": "business_name",
  "address": "business_address",
  "address2": "business_address_line_2",
  "city": "business_city",
  "state": "business_state",
  "zip": "business_zip",
  "country": "business_country",
  "billing_address": "business_address",
  "billing_address_2": "business_address_line_2",
  "billing_city": "business_city",
  "billing_state_region": "business_state",
  "billing_postal_code": "business_zip",
  "billing_country_region": "business_country",
  "phone": "phone",
  "ein__c": "fein"
}

Note on address fallback: The mapping includes both HubSpot's standard address properties (address, city, etc.) and dedicated billing-address properties (billing_address, billing_city, etc.). If both are present on a company, the billing-specific value wins. This ensures data syncs correctly for accounts that use only the standard fields.

Shipping Address Mappings

Controls how HubSpot company properties map into the Luminous default shipping address on a Business Account.

Default mapping:

{
  "address": "address",
  "address2": "address_line_2",
  "city": "city",
  "state": "state",
  "zip": "postal_code",
  "country": "country",
  "shipping_address": "address",
  "shipping_address_2": "address_line_2",
  "shipping_city": "city",
  "shipping_state_region": "state",
  "shipping_postal_code": "postal_code",
  "shipping_country_region": "country",
  "name": "company_name"
}

How data flows between HubSpot and Luminous

HubSpot → Luminous (inbound sync)

HubSpot object	Luminous record	Key fields synced
Company	Business Account	Name, billing address, shipping address, phone, FEIN — per your Business Account Mappings
Contact	User Account (contact)	First name, last name, email, phone; the HubSpot contact ID is also stored for future syncs
Contact ↔ Company association	Business Account Contact link	The contact is linked to the Business Account; the first contact linked becomes the default billable contact

You can trigger a manual sync from the integration account's manage page, or syncs occur automatically via HubSpot webhooks when companies or contacts change.

Luminous → HubSpot (outbound sync)

Luminous event	What is pushed to HubSpot
Invoice created or updated (linked to a HubSpot deal)	Deal amount and other mapped deal fields are updated; deal stage is updated to match invoice/order status
Line item created or updated (with Sync Line Items enabled)	Deal line items in HubSpot are created or updated with product name, SKU, quantity, and unit price

Assigned Sales Rep — important limitation

Luminous stores Assigned Sales Rep as a custom dropdown field (a curated text list on the Business Account or invoice). HubSpot stores deal and contact ownership as a HubSpot owner (a user account in HubSpot).

There is currently no automatic mapping between the HubSpot deal owner / contact owner and the Luminous Assigned Sales Rep field. The sync does not read or write owner information. If you need to populate Assigned Sales Rep in Luminous, you must update it manually on the invoice or business account in Luminous.

If this is a workflow your team depends on, contact Luminous support to discuss a custom field mapping configuration.

Troubleshooting tips

"Credentials not found" error on Test Credentials — You need to complete the OAuth authorization step first. Click Connect HubSpot and approve access in HubSpot.
Companies not appearing in Luminous after sync — Verify the Business Account Mappings JSON is valid. The companyId → hubspot_company_id mapping is required for Luminous to match records.
Deal stage not updating — Check that your Status Mapping JSON contains the correct numeric HubSpot deal stage IDs for your pipeline. Stage IDs can be found in HubSpot under Settings → CRM → Pipelines.
Country field showing 'US' unexpectedly — Luminous defaults country to US when HubSpot returns a country value longer than 2 characters (i.e., the full country name instead of an ISO code). Update your HubSpot company records to use 2-letter ISO country codes to pass through the correct value.