Overview
The Integrations settings page is where carrier, MGA, and wholesaler administrators connect Turris to the third-party tools their team already uses, so agency, contact, and agent data stays in sync without manual exports. The current release ships a HubSpot integration that keeps HubSpot Companies aligned with Turris Agencies and HubSpot Contacts aligned with Turris Agents, in both directions, with optional auto-invitations for net-new agencies.
What is Integrations Settings?
Integrations Settings is where you authorize a third-party CRM, map your Turris data onto its property model, and keep records reconciled in both directions on an ongoing basis. Instead of running CSV exports or building custom automations, you grant Turris OAuth access once, tell Turris which HubSpot records count as agencies and agents, and let the platform handle the creates, updates, and onboarding invitations.
Who uses it. Carrier, MGA, and wholesaler administrators with the Integrations settings permission. In most organizations this is the operations leader, RevOps owner, or HubSpot admin who already owns the company and contact objects in HubSpot and now needs to wire them to Turris compliance data.
Key capabilities:
See which integrations are connected at a glance through cards that show Connected, Not Connected, or Error status
Authorize HubSpot through its OAuth flow and let Turris discover your company and contact properties automatically
Tell Turris which HubSpot Companies are "agencies" and which HubSpot Contacts are "agents" using an identifier filter you build from any HubSpot property
Map Turris agency fields (Agency Name, NPN, Producer Code, address, phone, and more) and agent fields (name, email, NPN) to specific HubSpot properties
Turn ongoing sync on or off per object type and per direction in a single matrix
Auto-invite net-new synced agencies to onboarding and pick the contract each one receives based on its HubSpot properties
See a per-field Webhook Status that tells you whether inbound sync is live for each mapped property
Inspect a 30-day Recent Activity log of every outbound API call, inbound webhook, and auto-invite outcome so you can debug failed syncs without engineering
Re-establish the OAuth connection without losing your field mapping, or delete the integration entirely when retiring it
Accessing Integrations Settings
Integrations Settings lives inside the global Settings modal, not on a dedicated page. The modal can be opened from any screen in the platform.
To open Integrations Settings:
Click your profile avatar in the navigation sidebar.
In the menu that opens, click Settings.
In the Settings modal sidebar, under the Developer group, click Integrations.
The page header reads "Integrations" with the subtitle "Connect Turris with your favorite tools to streamline your workflow and keep your data in sync."
What's visible on the page. A grid of integration cards, one per supported third party. Today only the HubSpot card is shown.
Element | What it shows |
Logo | The third-party logo (the HubSpot icon for the only available integration). |
Name | The integration name, for example |
Description | One-line summary of what the integration does. For HubSpot: "Sync your agency relationships, agency contacts, and agents between Turris and HubSpot." |
Status pill | One of Connected (green), Not Connected (gray), or Error (red). |
Action button | Connect (primary) when the status is Not Connected, or Manage (secondary) when the status is Connected. While the OAuth handshake is in flight the button reads Connecting... and is disabled. |
Click the action button on an integration card to either start the OAuth flow or, for a connected integration, open its dedicated management view.
Note: Integrations is a premium feature. Organizations that have not yet activated their subscription see a Become a Customer prompt in place of the cards. Members without read access to Integrations do not see the Integrations entry in the Settings sidebar at all.
Connecting HubSpot
When you'd do this. Your HubSpot admin has already imported, or is about to import, your agency relationships into HubSpot, and you want Turris to be the system of record for compliance while HubSpot continues to own the sales and account-management side. Connecting is the first step before any data flows in either direction.
From the Integrations page, locate the HubSpot card. The status pill reads Not Connected.
Click Connect.
The button label switches to Connecting... while Turris fetches an authorization URL.
Your browser is redirected to HubSpot's authorization page. Sign in to your HubSpot account if prompted.
On HubSpot's consent screen, select the HubSpot account you want to connect, review the requested scopes, and approve the connection.
HubSpot redirects you back to the Turris Integrations page. The HubSpot card now shows a green Connected badge and the action button changes to Manage.
Note: Only one HubSpot account can be connected to a Turris organization at a time. To swap to a different HubSpot portal, delete the existing integration first (see Deleting the HubSpot Integration below), then run the connect flow again from the new HubSpot account.
Managing a Connected HubSpot Integration
Clicking Manage on a connected HubSpot card opens the HubSpot Integration management view. A "Back to Integrations" link at the top returns you to the card grid. The header shows the HubSpot logo, the title HubSpot Integration, a green Connected pill, and the subtitle "Manage your HubSpot integration settings and synchronization options."
The page is organized top to bottom into these sections:
HubSpot Field Mapping (this is where every tenant must start)
Bulk Reconciliation (coming soon)
Ongoing Data Synchronization
Agency Invitations
Recent Activity
Connection Settings
Danger Zone
Each section is described below.
Configuring the HubSpot Field Mapping
When you'd do this. Right after connecting HubSpot, and any time you want to sync a new Turris field into a HubSpot property or start syncing a new object type. Until the Agency Identifier is configured, Turris does not know which HubSpot Companies count as agencies, and inbound agency sync stays disabled.
The HubSpot Field Mapping section at the top of the management view shows a summary card. The icon on the left is a green gear icon when the Agency Identifier is configured and an amber warning triangle when it is not. The card lists your current mappings in up to two tables, one for Agency and one for Agent (the Agent table appears only once an agent mapping exists):
Column | What it shows |
Turris Field | The Turris-side field, for example Agency Identifier, Agency Name, NPN. |
HubSpot Property | The HubSpot property each Turris field reads from, or "Not mapped". |
Webhook Status | Appears only when inbound sync is enabled for that section. A Live or Pending badge per mapped property (see Status Indicators below). |
If the Agency Identifier is not yet configured, the card shows the warning "Configure the Agency Identifier to enable HubSpot → Turris sync."
To edit the mapping, click Edit (when the Agency Identifier is configured) or Configure (when it is not). The button opens the HubSpot Field Mapping modal, which is split into an Agency tab and an Agent tab.
Note: Changing a mapping does not rewrite existing records. The modal shows a banner that reads "Changes won't update existing records." When you change which HubSpot property a Turris field reads from, existing Turris records keep the values they were already synced with. New values flow in the next time that property changes in HubSpot. To force a refresh sooner, edit the property in HubSpot for each record you want to update.
Agency tab fields
Section | Field | Required | Description |
Identifier | Agency Identifier | Yes | A filter that tells Turris which HubSpot Companies should be treated as agencies. See "Setting up an identifier filter" below. |
Required | Agency Name | Yes | The HubSpot property that holds each agency's name. Defaults to HubSpot's built-in Name property. |
Standard | Branch Name | No | HubSpot property that stores each association's branch name. |
Standard | NPN | No | HubSpot property that holds the National Producer Number. Used as a high-confidence identifier when matching HubSpot companies to Turris agencies. |
Standard | Producer Code | No | HubSpot property that holds the agency's Producer Code. Used as a secondary identifier when NPN is unavailable. |
Standard | Website | No | HubSpot property that receives the agency's website or primary domain. |
Standard | Phone | No | HubSpot property that receives the agency's primary phone number. |
Standard | Street Address | No | HubSpot property that receives the street line of the agency's legal address. |
Standard | City | No | HubSpot property that receives the city of the agency's legal address. |
Standard | State Code | No | HubSpot property that holds the 2-letter US state code (for example |
Standard | ZIP | No | HubSpot property that receives the ZIP or postal code of the agency's legal address. |
Standard | Country | No | HubSpot property that receives the country of the agency's legal address. |
Agent tab fields
Section | Field | Required | Description |
Identifier | Agent Identifier | Yes | A filter that tells Turris which HubSpot Contacts at synced agencies should be treated as agents. |
Required | First Name | Yes | HubSpot contact property holding the agent's first name. Defaults to HubSpot's built-in First Name property. |
Required | Last Name | Yes | HubSpot contact property holding the agent's last name. Defaults to HubSpot's built-in Last Name property. |
Standard | No | HubSpot contact property holding the agent's primary email. Defaults to HubSpot's built-in Email property. | |
Standard | NPN | No | HubSpot contact property holding the agent's NPN. Recommended: without it, agents are deduplicated on first name, last name, and email. |
Standard | Middle Name | No | HubSpot contact property holding the agent's middle name. |
For every row, picking a HubSpot property from the searchable dropdown starts syncing the corresponding Turris value. Each row carries a Required or Optional badge. Standard (optional) rows include a Not mapped choice at the top of the dropdown; choosing it removes the mapping so that field is skipped on sync.
Click Save at the bottom of the modal to persist your changes, or Cancel to discard them. If an identifier filter is half-configured (mode is Apply filter but the property, operator, or value is still missing), Save surfaces inline errors and switches you to the tab that needs attention rather than failing silently.
Setting up an identifier filter
Both the Agency Identifier and the Agent Identifier use the same editor: a radio group with two modes.
Mode | Meaning |
Sync all | Every HubSpot Company (Agency tab) or Contact (Agent tab) is in scope. Use this when your HubSpot portal contains only the records you want synced. |
Apply filter | Only records that match a property-based filter are in scope. Use this when your portal mixes agencies or agents with prospects, vendors, partners, or other record types. |
When Apply filter is selected, three inputs appear:
Field | Required | Description |
HubSpot Property | Yes | Searchable dropdown of every text, dropdown (enumeration), or true/false HubSpot property for that object type. Example: |
Operator | Yes | One of Equals, Is populated, Is not populated, Is one of, Contains, or Is a number. Disabled until a property is selected. |
Value / Values | Yes (except for Is populated, Is not populated, and Is a number) | The right-hand side of the comparison. For Equals and Contains this is a single text input or value picker. For Is one of it is either a multi-select picker or a tag input where you press Enter or comma to add each value. |
Note: Value comparisons are case- and whitespace-sensitive. "Agency" does not match "agency", and "Insurance Agency" contains "Agency" but not "agency". The blue help popover next to the Value label restates this for each operator.
Bulk Reconciliation
Bulk Reconciliation is coming soon. This section sits below the field mapping and shows three cards, each carrying a Coming soon badge and currently disabled:
Card | Description |
Sync Agencies | Pair existing HubSpot Companies with Turris Agencies in a single pass, and optionally create new records for unmatched entities. |
Sync Agency Contacts | Pair existing HubSpot Contacts with Turris Agency Contacts, and optionally create new records for unmatched contacts. |
Sync Agents | Pair existing HubSpot Contacts with Turris Agents, and optionally create new records for unmatched agents. |
When this feature ships, it will let you reconcile records you already have in both systems before turning on ongoing sync. Until then, use Ongoing Data Synchronization to keep new and updated records aligned going forward.
Managing Ongoing Synchronization
When you'd do this. Once your field mapping is in place, turn on the directional toggles so future creates and edits flow automatically between the two systems.
The Ongoing Data Synchronization section shows a matrix. The columns are object types and the rows are directions:
Agency (HubSpot Companies ↔ Turris Agencies) | Agency Contacts (HubSpot Contacts ↔ Turris Agency Contacts) | Agents (HubSpot Contacts ↔ Turris Agents) | |
HubSpot → Turris | Create Turris records when matching HubSpot records appear | Coming soon | Create Turris records when matching HubSpot records appear |
Turris → HubSpot | Push new Turris records into HubSpot | Coming soon | Push new Turris records into HubSpot |
The Agency Contacts column is marked Coming soon and its toggles are disabled. The Agency and Agents columns are live.
Hovering any toggle shows a tooltip describing what it does. A HubSpot → Turris toggle is disabled until its prerequisites are met, and the tooltip names exactly what is still missing:
Agency, HubSpot → Turris requires the Agency Identifier configured AND Agency Name mapped.
Agents, HubSpot → Turris requires the Agent Identifier configured AND both First Name and Last Name mapped.
The Turris → HubSpot toggles have no prerequisites and can be turned on at any time. You can always turn a toggle OFF, even if a prerequisite is no longer met, so you can pause sync while you fix a mapping.
When any HubSpot → Turris toggle is ON, a blue info banner appears beneath the matrix. It explains that a new matching HubSpot record creates the corresponding Turris record with every mapped field (including custom-mapped properties like NPN), but that edits to an existing HubSpot record only sync standard HubSpot fields. Edits to custom-mapped properties (NPN, Producer Code, or any other custom property you have mapped) do not sync inbound and must be made in Turris.
Auto-Inviting Synced Agencies
When you'd do this. You have inbound agency sync turned on and you want net-new agencies that arrive from HubSpot to be sent the Turris onboarding invitation automatically, with the right contract attached, instead of being added silently.
The Agency Invitations section sits below Ongoing Data Synchronization. It is gated on inbound agency sync: until Agency, HubSpot → Turris is enabled, the whole section is dimmed and a tooltip explains "Enable HubSpot → Turris sync above to configure agency invitations. There are no net-new synced agencies to invite until inbound sync is on."
Once enabled, the Auto-invite synced agencies card lets you choose an invitation mode:
Mode | Meaning |
Do not invite | Net-new synced agencies are created but never invited (the default). |
Invite all | Every net-new synced agency is invited to onboard. |
Apply filter | Only net-new agencies whose HubSpot company matches a condition you set are invited. Agencies that do not match are created without an invitation. |
When the mode is Invite all or Apply filter, a Contract assignment block appears so you can decide which contract each invited agency receives:
Click Add rule to add a contract-selection rule. Each rule pairs a HubSpot property condition (property, operator, value) with a contract template.
Rules are evaluated top to bottom. The first rule that matches the synced HubSpot company decides the contract. Reorder rules with the up and down arrows to change their priority.
Toggle Use a default contract ON to pick a fallback template applied when no rule matches. With the toggle OFF, agencies that match no rule do not receive a contract automatically and are sent to the needs-attention queue to be handled manually.
Click Save to persist the settings.
Tip: Order your most specific contract rules first. Because the first match wins, a broad rule placed at the top can shadow the more specific rules below it.
Reviewing Recent Activity
When you'd do this. When a sync silently failed and you need to know why, when an agency was not auto-invited as expected, or when a support ticket asks for the HubSpot error code and the IDs involved.
The Recent Activity card shows a single row titled "HubSpot integration activity" with the subtitle "Latest sync attempts, OAuth refreshes, and webhook events." Click View all to open the HubSpot Integration · Recent Activity modal.
The modal lists every outbound API call, inbound webhook, and auto-invite outcome for the last 30 days in a table:
Column | Description |
Title | The event kind with a directional icon. Examples: Create company in HubSpot, Update company in HubSpot, Refresh HubSpot access token, HubSpot webhook: company created, HubSpot webhook: company property changed, HubSpot webhook skipped, Auto-invite sent, Auto-invite deferred (awaiting contact), Auto-invite needs attention, Auto-invite skipped. |
Timestamp | Localized event time. Events within the last hour show a relative prefix (for example |
Status | A pill: green Success, red Failure, or yellow Skipped. |
Details | The fields populated for that event: HubSpot HTTP status, HubSpot error code, Message, Skip reason, Turris ID, and HubSpot ID. The Turris and HubSpot IDs are click-to-copy. |
A Refresh button at the bottom-left re-fetches the first page. A Load more button at the bottom-right pages through older entries; when you reach the end the modal shows "End of history." If no events have been recorded yet, the modal reads "No HubSpot integration activity yet. Once you add an agency or HubSpot sends a webhook, events will appear here."
Tip: When filing a support ticket about a failed sync, copy the Timestamp and the Turris and HubSpot IDs from the Details column. Closing the modal clears the cached pages so the next open starts from the freshest data.
Re-establishing the Connection
When you'd do this. You see an Error badge on the HubSpot card, an OAuth refresh has been failing in the Recent Activity log, or your HubSpot admin rotated the app's credentials.
From the HubSpot Integration management view, scroll to Connection Settings.
Click Reconnect on the Re-establish Connection card.
Turris re-runs the OAuth flow with HubSpot. Sign in if prompted and approve the same set of scopes.
On success, you are returned to the management view with a green Connected pill.
Field mapping, sync settings, agency-invitation settings, and synced-record history are all preserved across a reconnect. Only the OAuth tokens are replaced.
Deleting the HubSpot Integration
When you'd do this. You are switching to a different HubSpot portal, decommissioning the integration entirely, or your security team needs you to revoke the OAuth credentials Turris stores.
Scroll to the red Danger Zone section at the bottom of the management view.
Click Delete Integration.
A confirmation dialog titled Delete HubSpot Integration warns "Are you sure you want to delete the HubSpot integration? This action cannot be undone. You will need to re-authorize the connection if you want to use HubSpot again."
Click Delete to confirm, or Cancel to back out.
After deletion, you are returned to the Integrations card grid and the HubSpot card flips back to Not Connected.
Warning: Deleting the integration in Turris does not remove the Turris app from your HubSpot account. To finish the cleanup, open HubSpot and go to HubSpot → Settings → Integrations → Connected Apps and remove the Turris app there.
Status Indicators
The HubSpot integration surfaces several status indicators across the page.
Integration card status pill (on the Integrations card grid):
Color | Label | Meaning | What to do about it |
Green | Connected | OAuth handshake succeeded and Turris holds valid HubSpot tokens. | Click Manage to configure mappings and sync settings. |
Gray | Not Connected | No HubSpot account is connected to this Turris organization. | Click Connect to start the OAuth flow. |
Red | Error | The last OAuth refresh failed or HubSpot revoked the app. Sync is paused. | Open the HubSpot Integration management view and click Reconnect under Connection Settings. |
Field Mapping summary icon (top of the HubSpot Integration management view):
Color | Icon | Meaning | What to do about it |
Green | Gear | The Agency Identifier is configured. | No action required. Click Edit to refine the mapping. |
Amber | Warning triangle | The Agency Identifier has not been configured yet. | Click Configure to open the modal and define the filter. Until this is set, inbound agency sync stays disabled. |
Per-field Webhook Status badge (in the field-mapping summary tables, when inbound sync is on):
Color | Label | Meaning | What to do about it |
Green | Live | The property's inbound webhook is active. Property changes in HubSpot propagate to Turris automatically. | None. |
Yellow | Pending | The webhook subscription is being created or is pending retry. | Wait. It usually clears within 1 to 2 minutes. |
Activity outcome badge (in the Recent Activity modal):
Color | Label | Meaning | What to do about it |
Green | Success | The API call or webhook completed successfully. | None. |
Red | Failure | The call or webhook failed. | Open the row's Details for the HubSpot status code, error code, and message, then fix the underlying issue (often a field mapping pointing at a property that does not exist). |
Yellow | Skipped | The event was intentionally not processed (for example a record that did not match the identifier filter). | Read the Skip reason in Details. No action is usually needed. |
Frequently Asked Questions
Do I have to map every field before sync will work? No. For agencies, only the Agency Identifier is required, plus Agency Name (which defaults to HubSpot's built-in Name property). For agents, only the Agent Identifier, First Name, and Last Name are required. Every other field is optional and can be left "Not mapped."
Why can't I turn on HubSpot → Turris sync? For the Agency column, the toggle stays disabled until the Agency Identifier is configured and Agency Name is mapped. For the Agents column, it stays disabled until the Agent Identifier, First Name, and Last Name are all set. Hover the disabled toggle to see exactly which piece is missing.
Can I edit NPN or another custom property in HubSpot and have it sync to Turris? Inbound edits only cover HubSpot's standard fields. Custom-mapped properties such as NPN and Producer Code are applied when the record is first created, but later edits to them do not sync inbound. After creation, edit those values in Turris.
What's the difference between Live and Pending webhook status? Live means the inbound webhook for that property is active and changes flow to Turris automatically. Pending means the subscription is still being set up, which usually clears within 1 to 2 minutes.
When does an agency get auto-invited? Auto-invitations follow your Agency Invitations settings and only apply when inbound agency sync is on. With Do not invite, agencies sync in silently. With Invite all or Apply filter, net-new synced agencies are sent the onboarding invitation and assigned a contract based on your rules.
Why does a State Code value not sync? Turris stores 2-letter US state codes (for example NY). HubSpot values that are not a recognized 2-letter code are skipped during sync, and you can see the skipped attempts in the Recent Activity log.
How long is activity history kept? The Recent Activity log retains 30 days of events. Older events are pruned automatically.
Is Bulk Reconciliation available yet? Not yet. The Sync Agencies, Sync Agency Contacts, and Sync Agents cards are marked Coming soon. Use Ongoing Data Synchronization to keep records aligned in the meantime.
Best Practices
Configure the Agency Identifier before anything else. Until it is set, you cannot turn on inbound agency sync. Pick a HubSpot property that cleanly distinguishes agencies from every other company type in your portal.
Map NPN wherever you have it. NPN is the highest-confidence identifier Turris uses to match and deduplicate records. For agents without NPN, deduplication falls back to first name, last name, and email.
Map First Name and Last Name before enabling agent inbound sync. The Agents HubSpot → Turris toggle stays disabled until both are mapped alongside the Agent Identifier.
Turn the matrix toggles on deliberately, then watch Recent Activity. The first day after enabling a HubSpot → Turris direction is the most likely time to surface a misconfigured identifier or a missing mapping. Pull up the activity log once a day for the first few days.
Order auto-invite contract rules from most specific to least specific. Because the first matching rule wins, a broad rule at the top can shadow the more specific rules below it. Decide whether to set a default contract or route unmatched agencies to the needs-attention queue.
Treat HubSpot Settings → Connected Apps as the second step of deletion. Deleting the integration from Turris revokes Turris's side, but the Turris app stays installed on your HubSpot portal until you remove it there.
Related Pages
API (Settings): Generate API Clients and Restricted Access Tokens to connect Turris to your own systems.
Settings: Business Rules: Set organization-wide defaults for coverage, onboarding automation, screening, and compliance verdicts.
Agency Onboarding: Custom Questions: Build an extra onboarding step to capture information the standard steps do not collect.
Settings: Email Domain: Register a custom sending domain so platform emails come from your own brand.
Settings: Personal Notifications: Choose which compliance, lifecycle, license, and policy events trigger an email or in-app alert.
Agency Onboarding: Payment Details: Decide whether invited agencies must submit banking information before completing onboarding.
Agency Onboarding: Pre-Contract Review: Pause invited agencies for a manual review before the producer agreement is sent.
Settings: Template Agreements: Keep a library of producer agreement templates ready to use when inviting new agencies.
Agency Onboarding Settings: Product and State Selections: Control whether agencies pick product authority and operating states during onboarding.
Settings: Products & Compliance: Define every distributed product and its state-by-state license and appointment requirements.
Settings: Security: Apply organization-wide authentication controls such as SMS OTP multi-factor authentication.
Agency Onboarding: Upload Documents: Set the compliance-document checklist every invited agency must satisfy during onboarding.
Users (Settings): Add, edit, and remove members and review what each role is allowed to do.
Settings: Webhook: Register HTTPS endpoints to receive automated compliance event notifications.
Need Help?
If you have questions about Integrations Settings or encounter any issues, contact our support team at support@turris.com.