HubSpot

Keep a HubSpot contact for each partner and a deal for each referred customer, using your own HubSpot private app.

Embed
Preview of the card
<a href="https://referalli.com/docs/hubspot"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/9d5d99c3-e042-4501-a1f5-fe3f43a6e4b2/social-card.svg?v=3e7ae33eec8b" alt="HubSpot" width="600" height="315"></a>

Connect HubSpot with your own private-app token and Referalli keeps your CRM current:

  • A contact per partner, matched by email and updated as they earn. It carries their name plus these properties:

    Property

    Value

    referally_partner_id

    The partner's Referalli id

    referally_partner_status

    active, suspended, …

    referally_lifetime_commission

    Pending + approved + paid, in their main currency, e.g. 120.00

    referally_commission_currency

    e.g. USD

    referally_referrals

    Referrals not voided

  • A deal per referred customer, named Referral: <customer id>, created in your pipeline and new-referral stage, and associated with the partner's contact. When the customer's first payment earns a commission, the deal moves to your paid stage. It only moves once.

Connect

  1. In HubSpot, create a private app (Settings → Integrations → Private apps) with these scopes: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.deals.read, crm.objects.deals.write and crm.schemas.contacts.write. Copy its access token.

  2. In Referalli, open Settings → Integrations → HubSpot, paste the token, and optionally set the pipeline and the two stages (internal ids; defaults default, appointmentscheduled, closedwon).

  3. Click Test connection. It checks the token and creates the referally_* contact properties if they don't exist yet.

The token is stored encrypted and never shown again; leave the field empty when you edit other settings to keep it.

API

Call

Body

Notes

PUT /v1/integrations/hubspot

{ "token"?: "pat-…", "pipeline"?, "newDealStage"?, "paidDealStage"?, "status"?: "active" | "paused" }

token is required the first time. null resets a setting to its default. Owner or admin.

POST /v1/integrations/hubspot/test

{ "setupProperties"?: true }

{ ok, portalId, createdProperties, error }

DELETE /v1/integrations/hubspot

none

Disconnects; queued updates are dropped.

GET /v1/integrations

none

Both connections, without credentials, with status, lastError, lastSuccessAt, pausedUntil.

GET /v1/integrations/deliveries?kind=hubspot

none

Recent updates and their status. POST /v1/integrations/deliveries/{id}/retry queues a failed one again.

Delivery

Updates follow the events referral.created, commission.earned, commission.reversed and partner.applied/enrolled/approved. They're queued and sent in order:

What happens

Effect

A send fails

Retried with exponential backoff for 3 days.

HubSpot rate-limits (429)

The connection waits exactly as long as Retry-After asks, then continues.

The token is rejected (401/403)

The connection is marked error with the message, and the update fails. Fix the token, then retry the update from Settings → Integrations.

Updated