> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to HubSpot

> How WeGive integrates with HubSpot: contacts, companies, households, and donation deals

WeGive's HubSpot integration keeps supporters, households, donations, and recurring plans aligned across both platforms. Contacts and Companies sync bidirectionally. Transactions and recurring donations live in dedicated Deal pipelines that WeGive provisions when you first connect.

## Key features

* **OAuth 2.0 connection.** No API keys to manage; authorize from the WeGive dashboard.
* **Bidirectional sync** for Contacts and Companies. WeGive remains the source of truth for transaction amounts and statuses.
* **Three purpose-built Deal pipelines** — Donations (one-time), Recurring Donations, and Soft Credits — created automatically during provisioning.
* **Household modeling** through a custom Household association label between Contact and Company.
* **Lifetime giving rollups** pushed to each Contact/Company: total given, total gifts, first/last gift date and amount, largest gift, average gift, given year-to-date, recurring-donor flag and amount, and donor status. There's no separate "donor lifecycle stage" property — `wegive_donor_status` is the closest analog.
* **Deletion and merge webhooks** from HubSpot. Deleting a Contact/Company/Deal in HubSpot never deletes the corresponding WeGive record (WeGive is the source of truth for those) — it just unlinks the HubSpot ID so the record can relink automatically if restored. A GDPR privacy-deletion request on a Contact is the one exception: that does delete the WeGive donor. Merging two Contacts or two Companies in HubSpot (each independently toggleable) reassigns the losing record's data to the winner in WeGive too.
* **Per-direction toggles** for every push and pull: supporters, households, transactions, recurring donations.

## How it works

WeGive listens for changes on supporters, households, transactions, and recurring plans. Each change queues a push to HubSpot, with deduplication so rapid edits do not generate duplicate API calls. A scheduled pull (default every 15 minutes) brings new and changed HubSpot Contacts and Companies back into WeGive.

Transaction amounts and statuses are pushed from WeGive and never overwritten on pull. Editing a deal's amount or stage in HubSpot does not change the underlying WeGive transaction. WeGive is the system of record for financial data.

<Warning>
  **The scheduled pull also reads Deals, and it can create brand-new WeGive transactions and recurring plans from them — this isn't update-only.** If a deal in WeGive's own Donations or Recurring Donations pipeline has no matching WeGive record yet (matched via `hubspot_id`, then the HubSpot-editable `wegive_id` property), WeGive creates one, provided the deal's contact/company association (or `wegive_donor_id` property) resolves to a WeGive supporter — if it doesn't, the pull fails loudly for that deal rather than skipping it silently. In practice this matters for a customer whose existing HubSpot deals live in a pipeline HubSpot/WeGive didn't provision: the pull never sees those deals at all (it's scoped strictly to WeGive's own pipeline IDs), so moving deals into WeGive's pipeline — or loading historical volume via Batch Gift Import instead — is the real path, not "the pull will pick them up eventually."
</Warning>

## Synced objects

| WeGive object | HubSpot object |
| - | - |
| Supporter (individual) | Contact |
| Company | Company (`wegive_entity_type = company`) |
| Household | Company (`wegive_entity_type = household`) with Household association |
| Transaction | Deal in the Donations pipeline |
| Recurring plan | Deal in the Recurring Donations pipeline |

## Getting started

<CardGroup cols={2}>
  <Card title="Setup Requirements" href="/external/onboarding/hubspot/setup-requirements">
    Prerequisites, required OAuth scopes, and the one-time provisioning step.
  </Card>

  <Card title="Configuration Options" href="/external/onboarding/hubspot/configuration-options">
    Per-direction sync toggles, address sync source, and ACH handling.
  </Card>

  <Card title="Data Mapping" href="/external/onboarding/hubspot/data-mapping/overview">
    Field-by-field mapping for Contacts, Companies, and Deals.
  </Card>

  <Card title="Integration Nuances" href="/external/onboarding/hubspot/integration-nuances">
    Free-tier pipeline limits, rate limiting, deduplication, and edge cases.
  </Card>
</CardGroup>

Questions? Email [support@wegive.com](mailto:support@wegive.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.