HubSpot integration

HubSpot is the source of truth for mapped Deal and Company fields. DataFlair imports them for review and refreshes linked records through manual pulls, webhook notifications, and scheduled reconciliation. Tenant edits do not push to HubSpot. Platform super admins retain separate, explicit outbound operations.

1. Connect the private app

A HubSpot account administrator configures the app. In HubSpot, open Development → Legacy apps, then create a private app or edit the existing DataFlair app. On Auth, copy the access token securely. In DataFlair, open Settings → Integrations → HubSpot → Connect / Reconfigure, paste the token, and save. Use Test to verify read access.

Required inbound scopes:

Purpose	Scope
Read Deal records and associations	crm.objects.deals.read
Read Company records and associations	crm.objects.companies.read
Read Deal property definitions	crm.schemas.deals.read
Read Company property definitions	crm.schemas.companies.read
Resolve a Deal's HubSpot owner to a DataFlair user (Commercial manager)	crm.objects.owners.read

No write scope is required for inbound sync. Existing write permissions can remain for platform super-admin operations. Only grant the object/schema write scopes needed for those operations; granting a token a write scope does not enable tenant outbound sync. Contact imports are not included in this inbound workflow.

Official reference: HubSpot private apps.

2. Review smart field mappings

Open HubSpot → Import & mapping → Map fields. Refresh the property schema, then select Suggest mappings. Suggestions consider the source object, property names, labels, synonyms, and compatible types. Review the confidence and explanation. Suggestions fill only empty, high-confidence rows; they do not replace saved or manually changed mappings. Select Save mappings to apply them.

For dropdowns and multiple selections, expand Translate dropdown values. Map HubSpot options to DataFlair values such as licence names, country and state/province names, Product Type names, and CPA, RevShare, or Hybrid. Without an explicit conversion, the importer uses the HubSpot label and checks whether DataFlair recognises it. Unknown values require review.

Client field	HubSpot object	DataFlair destination / decision
Deal record name	Deal	Deal name, normally dealname
IO or T&C – SiGMA Play & Casinobee	Deal	Confirm an example before mapping to IO reference. A URL or IO type is not an invoice number.
Licenses	Company	Brand licences
License Numbers – SIGMA PLAY	Company	Brand licence numbers; ambiguous multi-licence number pairing requires review
USA States + Canada Provinces	Company	Brand coverage, separate from deal-specific targeting

Use the actual internal property names from the portal. Do not create duplicate Company properties on Deal. Required Deal identity fields must be mapped or resolved during review. Unmapped destinations remain unchanged; explicit empty mapped values clear optional values. Clearing a required identity value requires review.

3. Pull and review the initial import

1. Save mappings. In Verify portal & configure webhooks, enter the HubSpot portal ID and save. Webhooks are the recommended path — see Section 4 below to configure them now. If skipping webhooks temporarily, leave notifications disabled and the signing secret empty; the scheduled reconciliation pull (every six hours) is the only fallback and is not real-time. Once the portal is verified, select Pull now. New HubSpot records are staged for review; already linked records are refreshed.
2. Select Refresh status & properties after the queued pull finishes. Large pulls are paginated; completion means every queued page has finished.
3. Review Company records first. Choose the existing DataFlair Brand and select Import reviewed record. Create any missing Brand through the normal Brand workflow first.
4. Review Deals. Inspect source properties and associations. A sole associated Company or a unique primary Company can be selected automatically. Otherwise choose the intended associated Company explicitly.
5. Resolve Brand, Product Type, and Deal Type. To link an existing DataFlair Deal, enter its ID; otherwise the import creates a new Deal after validation.
6. Inspect the imported Deal and Brand. Repeating a pull updates their recorded HubSpot links instead of duplicating them.

Changing Company licences refreshes the Brand used by its Deals. It does not rewrite a Deal's separate targeting rules. Archived HubSpot records remain visible in import history; DataFlair does not delete local business history automatically. Association changes that conflict with an established Brand link require review.

AI-assisted smart pre-selection

When you open a Deal or Company record for review, DataFlair automatically pre-fills the Brand, Product Type(s), and Deal Type fields using a multi-tier resolution chain, so you rarely need to select them manually:

1. Company graph — if the HubSpot Deal has exactly one associated Company that is already linked to a DataFlair Brand, that Brand is selected immediately with no AI call needed.
2. Token matcher — the Deal name is tokenised and matched against all Brand names using word-boundary scoring. A high-confidence token match resolves without an external call.
3. JEV (TypeSafe System One) — if the above steps are inconclusive, the deal metadata and a list of candidate Brand names are sent to the JEV structured-data AI. JEV returns a strongly typed JSON response selecting the Brand, up to two Product Types (e.g. Casino and Sportsbook simultaneously), and the Deal Type.
4. Claude Haiku (fallback) — if JEV is unavailable or returns a low-confidence result, Claude Haiku receives the same prompt and returns a final suggestion.

Product Type is a multi-select field — a single Deal can cover both Casino and Sportsbook verticals. The resolution chain infers all applicable verticals from the Deal name and description. All suggestions are editable before you confirm import; the resolver never auto-imports without your review.

4. Enable webhook-triggered pulls

Webhooks deliver change notifications; DataFlair then reads the latest record and associations from HubSpot. They do not send DataFlair data to HubSpot. Private-app subscriptions must be configured in HubSpot's UI; DataFlair does not create or verify those subscriptions remotely. HubSpot webhook guide

This entire setup is self-service on the tenant side. There is no callback URL to request from or hand to the DataFlair team in advance — DataFlair generates a URL unique to your account only after you complete step 2 below, and only your own account can see it.

1. In DataFlair, open Import & mapping → Verify portal & configure webhooks.
2. Enter the HubSpot portal ID and the app's client secret for webhook signatures. This is distinct from the API access token. Store it through this form rather than email or chat. Enable Accept webhook notifications and save. DataFlair checks that the portal ID matches the connected token. Saving here is also what creates your account's webhook record and its unique Callback URL for the first time — before this save the URL field is blank.
3. Copy the Callback URL now shown on this page. It must be publicly reachable over HTTPS. Use the exact URL; a local .test address cannot receive HubSpot deliveries.
4. In HubSpot, open the private app's Webhooks tab. Set Target URL to the copied callback URL.
5. Add subscriptions for Deal and Company creation, deletion, restoration, merges, and association changes where offered by the app.
6. Add Property changed subscriptions for every property listed in the DataFlair webhook panel. The list comes from saved mappings, so save mappings first.
7. Save/activate the subscriptions in HubSpot. Whenever mappings change, update these subscriptions too. A property-change subscription covers the selected property; it does not cover every field on the object.
8. Change one mapped field on a reviewed test Deal, then one Company field. Check Last accepted notification, refresh import status, and verify the local values. A received notification alone does not prove the queued import succeeded; inspect the record error/status too.

Go-live journey

Settings → Integrations → HubSpot → Connect
  → Import & mapping → Refresh properties → Suggest → Review → Save
  → Verify portal → Pull now → Review Companies → Review Deals → Import
  → Configure receiver → Configure HubSpot subscriptions
  → Change HubSpot Company licence → Verify Brand update
  → Repeat pull → Verify no duplicate records
  → Edit DataFlair → Verify HubSpot is unchanged

Validate a cleared optional value, unknown dropdown option, ambiguous Company association, and archived record as well. Confirm both the queue and scheduler are running before go-live.

Troubleshooting

• Schema or connection error: check the access token and read scopes; refresh properties. Test does not create HubSpot properties.
• Unknown local value: correct the option conversion or resolve the local reference, then retry the reviewed import.
• Webhook received but data unchanged: check the queue, import record error, mapping, and whether the record has been reviewed and linked.
• No notifications: check the exact deployed callback URL, receiver active state, portal ID, app signing secret, and HubSpot subscription activation/property coverage.
• Manual pull works but a Company-only change does not: check Company property subscriptions independently of Deal subscriptions.
• AI pre-selection did not suggest a value: the resolver falls back gracefully — select Brand, Product Type(s), and Deal Type manually. Check that the TYPESAFE_API_KEY environment variable is set on the server if JEV suggestions are missing entirely.

Platform super-admin operations

Platform administrators use Admin → Tenants → tenant → HubSpot operations to preview and execute permitted record or property writes. These operations require the relevant token scopes and a separate explicit confirmation. Tenant users and background import jobs cannot invoke them. The original outbound field definitions remain documented in the field matrix available from the HubSpot integration card for these operations.