Sync members from your CRM

Most partners already run a CRM (HubSpot, RD Station, Pipedrive, ActiveCampaign, Salesforce) as the source of truth for contacts. This guide shows how to keep the Cativa community in sync with that CRM using the admin API (email lookup, user creation, external-id binding, badge assignment) and the design decisions (natural key, conflicts, idempotency) you need to make.

Scenario

Your marketing team uses HubSpot. Every time a lead is qualified and tagged Pago Anual there, you want that person to show up in your Cativa community with the Premium badge (which unlocks the VIP group, the paid course, etc.). When the tag is removed (or the customer churns), the badge needs to come off. Cativa is the source of truth for the community (who’s in the group, who completed which lesson, who posted what). The CRM is the source of truth for the commercial relationship (lead, opportunity, customer, churn). The integration bridges the two.

Prerequisites

Cativa API Key — generated in the Console (Developers > API Keys). See Quick Start: API Key. Every call below uses Authorization: Bearer cativa_live_....
API access to your CRM — HubSpot token, RD Station token, etc. Cativa does not ship a CRM SDK; use the official ones (@hubspot/api-client, pipedrive-node-sdk, etc.).
An integration server running on your side — could be a Node worker, a Cloud Function/Lambda, an Airflow job, anything that runs code with access to both sides.

Conceptual mapping

The central question: how do you recognize that contact 1234 in HubSpot is the same user 01HQ7Z3X4Y... on Cativa?

HubSpot	Cativa
Contact ID	User ID (ULID)
Email	Email (natural key)
Tag `Pago Anual`	Badge `Premium`

The recommended natural key is email (it exists on both sides from sign-up). After the first match, cache the binding on both sides: store the CRM Contact ID on the Cativa user via PATCH /admin/users/{userId}/external-id, and optionally store the Cativa User ID in a CRM custom property (e.g. cativa_user_id). That way you stop relying on email lookups on every run.

Cativa exposes an external-ID field on User, writable via PATCH /admin/users/{userId}/external-id. Use it as the canonical way to bind your CRM’s key to the Cativa user. With the binding persisted on the user itself, the local mapping table (described below) becomes optional — just a cache optimization on your side.

Two possible flows

Pull-based (periodic worker)
Webhook-based (event-driven)

When to use: you don’t have a CRM webhook, the volume is small (a few thousand contacts), or a delay of minutes/hours is acceptable.A worker on your side runs on a cadence (e.g. every 15 minutes), reads the CRM state, reads the Cativa state, computes the diff, applies it.

cron 15 min ─→ pull HubSpot ─→ pull Cativa ─→ diff ─→ apply

Pros: simple to implement, easy to debug, easy to backfill. Cons: delay (not real-time), wastes API calls when nothing changed.

When to use: the CRM offers webhooks when a property changes (HubSpot Workflow, RD Station Automation), and you want second-level sync.The CRM fires a webhook to your server when a tag changes → your server calls the Cativa API to assign/remove the badge.

HubSpot tag changes ─→ webhook to your server ─→ Cativa API

Pros: low latency, efficient. Cons: more code (HMAC verification of the CRM webhook, retry/backoff, dedupe), and you still want a weekly pull-based reconcile worker to cover lost webhooks.You can also subscribe to Cativa webhooks (user_received_badge, user_created) to mirror community-side changes back into the CRM. The page Subscribing and verifying webhooks shows how to verify the HMAC signature on Cativa deliveries.

Look up and bind an existing user

Matching by email is the heart of the sync. Do it once per contact and persist the binding on the Cativa user itself.

Resolve the email to the Cativa user

GET /admin/users/email/{email} returns the user with that email in your key’s tenant. This is the canonical path for CRM sync.

curl "https://apis.cativalab.digital/tenant/api/v2/admin/users/email/joao%40empresa.com" \
  -H "Authorization: Bearer cativa_live_..."

import requests, urllib.parse

email = urllib.parse.quote("joao@empresa.com")
res = requests.get(
    f"https://apis.cativalab.digital/tenant/api/v2/admin/users/email/{email}",
    headers={"Authorization": f"Bearer {api_key}"},
)
user = res.json() if res.status_code == 200 else None

200 OK response (illustrative; full schema in the API Reference, Users tag):

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "joao@empresa.com",
  "firstName": "João",
  "lastName": "Silva",
  "externalId": null,
  "createdAt": "2026-07-01T14:22:03Z"
}

If the email doesn’t exist in the tenant, the endpoint returns 404 Not Found — treat that as “create the user” (section below):

{ "error": "User.NotFound", "message": "No user with that email in this tenant" }

Store the CRM Contact ID on the Cativa user

Capture the id from the response and immediately store your CRM Contact ID on the user via PATCH /admin/users/{userId}/external-id:

curl -X PATCH https://apis.cativalab.digital/tenant/api/v2/admin/users/01HQ7Z3X4Y.../external-id \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "1234" }'

200 OK response (illustrative) with the binding already reflected:

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "joao@empresa.com",
  "externalId": "1234"
}

With the binding persisted on the Cativa user itself, subsequent syncs no longer need to redo the email lookup.

If your key owns a user and you just want to check the credential and tenant, GET /tenant/api/v2/auth/me returns the key’s owning user and the customer (tenant) it belongs to:

curl https://apis.cativalab.digital/tenant/api/v2/auth/me \
  -H "Authorization: Bearer cativa_live_..."

200 OK response (illustrative):

{
  "user": { "id": "01HQOWNER0000000000000000", "email": "integration@company.com" },
  "customer": { "id": "01HQTENANT000000000000000", "name": "makers" }
}

Optional: a local mapping table as cache

The external-id on the Cativa user already resolves the binding. If you still want to avoid every round-trip to the Cativa API (for latency or cost), keep a cache table on your side:

crm_cativa_mapping
─────────────────
hubspot_contact_id  TEXT
cativa_user_id      TEXT   -- ULID
email               TEXT
last_synced_at      TIMESTAMP

And populate it via webhook:

Subscribe a Cativa listener to the user_created event. Every time someone joins the community, the webhook arrives with User.Id and User.Email. Insert/update that row.
Subscribe a listener to user_received_badge. Every badge change updates the row.

After that, your sync worker resolves email to cativa_user_id locally. Treat the table as a cache: the source of truth for the binding is still the external-id stored on the Cativa user.

Create a user from the CRM

When the CRM contact doesn’t exist on Cativa yet (the email lookup returns 404), create the user with POST /admin/users. Set the externalId in the same request:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/users \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@empresa.com",
    "firstName": "João",
    "lastName": "Silva",
    "externalId": "1234"
  }'

201 Created response (illustrative) — store the id (with the externalId already bound) for subsequent syncs:

{
  "id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "email": "joao@empresa.com",
  "firstName": "João",
  "lastName": "Silva",
  "externalId": "1234",
  "createdAt": "2026-07-10T09:00:00Z"
}

The full body schema is in the API Reference tab, under the Users tag. If you’d rather let the user set their own password, send the tenant’s sign-up link from your CRM (HubSpot Email, RD Station Email) instead of creating via API. For large initial backfills (thousands of contacts), the Cativa team can also import a spreadsheet via Console. Coordinate at dev@cativa.digital.

Assign a badge

Badge assignment via an admin API Key is available. There are two forms, under /admin/membership/badges: By email (ideal for CRM, no need to resolve the userId first):

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/PREMIUM_BADGE_ID/users/by-email \
  -H "Authorization: Bearer cativa_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "joao@empresa.com" }'

By id (when you already have the Cativa userId cached):

curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/PREMIUM_BADGE_ID/users/01HQ7Z3X4Y... \
  -H "Authorization: Bearer cativa_live_..."

200 OK response (illustrative; full schema in the API Reference, Badge tag):

{
  "userId": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "badgeId": "01HQBADGEPREMIUM0000000000",
  "assignedAt": "2026-07-10T09:01:12Z"
}

To remove, use DELETE on the same resource by id:

curl -X DELETE https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/PREMIUM_BADGE_ID/users/01HQ7Z3X4Y... \
  -H "Authorization: Bearer cativa_live_..."

In the worker, the assign and remove functions call these endpoints directly:

async function assignBadge(cativaUserId, badgeId) {
  const res = await fetch(
    `https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/${badgeId}/users/${cativaUserId}`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
    }
  );
  if (!res.ok) throw new Error(`Badge assign failed: ${res.status}`);
}

async function removeBadge(cativaUserId, badgeId) {
  const res = await fetch(
    `https://apis.cativalab.digital/tenant/api/v2/admin/membership/badges/${badgeId}/users/${cativaUserId}`,
    {
      method: 'DELETE',
      headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
    }
  );
  if (!res.ok) throw new Error(`Badge remove failed: ${res.status}`);
}

Cativa guarantees that assigning the same badge twice is idempotent — the final state is the same (the second call returns success without duplicating). Same for removing a badge that wasn’t assigned. That simplifies retries in your worker (see Badges as Permissions).

Pull-based worker skeleton

With the write endpoints available, the worker below runs end to end. The assignBadge/removeBadge functions (defined above) already hit the real API.

import { Client as HubSpotClient } from '@hubspot/api-client';

const hubspot = new HubSpotClient({ accessToken: process.env.HUBSPOT_TOKEN });
const PREMIUM_BADGE_ID = process.env.CATIVA_PREMIUM_BADGE_ID;

async function syncContact(contact) {
  const email = contact.properties.email;
  if (!email) return; // no email, no match

  // 1. Resolve email → Cativa User ID (local table populated via webhook)
  const mapping = await db.crmCativaMapping.findOne({ email });
  if (!mapping) {
    // User isn't on Cativa yet. Send an invite via the CRM.
    await sendInviteEmail(email);
    return;
  }

  // 2. Desired state (HubSpot is the source of truth)
  const shouldHavePremium = (contact.properties.lifecyclestage === 'customer'
    && contact.properties.deal_status === 'paid_annual');

  // 3. Current state (your local table, updated via the user_received_badge webhook)
  const hasPremium = await db.userBadges.exists({
    userId: mapping.cativaUserId,
    badgeId: PREMIUM_BADGE_ID
  });

  // 4. Apply the diff
  if (shouldHavePremium && !hasPremium) {
    await assignBadge(mapping.cativaUserId, PREMIUM_BADGE_ID);
  } else if (!shouldHavePremium && hasPremium) {
    await removeBadge(mapping.cativaUserId, PREMIUM_BADGE_ID);
  }
}

async function runSync() {
  let after;
  do {
    const page = await hubspot.crm.contacts.basicApi.getPage(100, after, [
      'email', 'lifecyclestage', 'deal_status'
    ]);
    for (const contact of page.results) {
      try {
        await syncContact(contact);
      } catch (err) {
        console.error(`Failed to sync ${contact.id}`, err);
        // Don't break the loop — log and continue.
      }
    }
    after = page.paging?.next?.after;
  } while (after);
}

Handling conflicts

Scenario	What to do
Email changed in the CRM, hasn’t changed on Cativa	Cativa is the source of `cativa_user_id`. If the HubSpot contact’s email changed and you can’t match by the new email anymore, keep the cached `cativa_user_id` (in `crm_cativa_mapping`) and update the `email` column when it’s different. The Cativa user still exists — only the CRM-side angle changed.
CRM email never showed up on Cativa	The HubSpot contact has no Cativa user yet. Create the user with `POST /admin/users` (section above), or send an invite and skip until they sign up, per your policy.
Same email appears on two CRM contacts	Your call which contact is canonical (usually the most recent one, or the one with the most advanced `lifecyclestage`). Resolve before calling Cativa.
Customer cancelled in the CRM but still has the badge on Cativa	This is exactly what the removal sync fixes. The `runSync` flow above covers it.
Badge assigned by another source (paywall purchase) and the CRM doesn’t know	Cativa can grant badges via other paths (paywall purchase, course completion). If the CRM is not the source of truth for that specific badge, don’t remove the badge in the diff — add a filter on your side (e.g. only sync badges that came via a CRM tag).

Common errors

The sync removed badges granted by other sources

When your worker is the sole authority on a badge and sees no reason for it in the CRM, it removes it. But if the badge was assigned by another source (paywall purchase, manual import), the sync wipes it out by mistake.Fix: keep a list of “CRM-managed badges” in your worker. Only assign and remove those. Badges outside the list are skipped by the diff.

Rate limit while processing many contacts

On large syncs (thousands of contacts) you can hit rate limits on the CRM or on Cativa. Implement:

Exponential backoff on 429 (Cativa respects Retry-After).
Pagination on the CRM (e.g. getPage(100, after, ...) on HubSpot).
Bounded parallelism (e.g. p-limit(5) in Node).

user_created webhook never arrived — user missed the mapping table

If you only populate crm_cativa_mapping via webhook, every lost delivery becomes a gap. That’s why we recommend:

A weekly reconcile job that pulls every CRM contact with an email and tries to match against known users.
Logging the X-Cativa-Execution-Id on every received webhook — if it’s missing later, you can open an investigation ticket.

Different email between CRM and Cativa for the same user

Happens when the user buys with a personal email and joins the community with a corporate one (or vice-versa). No automatic fix — you need an extra property in the CRM (e.g. community_email) and use that for the lookup instead of the primary email.

Next steps

Subscribe to Cativa webhooks

Set up listeners for user_created and user_received_badge to keep your mapping table fresh.

Grant access via purchase

The specific case of “external purchase → badge” has its own patterns and gotchas.

Get Started

Concepts

Guides

Webhooks

Changelog

Scenario

Prerequisites

Conceptual mapping

Two possible flows

Look up and bind an existing user

Optional: a local mapping table as cache

Create a user from the CRM

Assign a badge

Pull-based worker skeleton

Handling conflicts

Common errors

Next steps

Subscribe to Cativa webhooks

Grant access via purchase

​Scenario

​Prerequisites

​Conceptual mapping

​Two possible flows

​Look up and bind an existing user

​Optional: a local mapping table as cache

​Create a user from the CRM

​Assign a badge

​Pull-based worker skeleton

​Handling conflicts

​Common errors

​Next steps

Subscribe to Cativa webhooks

Grant access via purchase

Scenario

Prerequisites

Conceptual mapping

Two possible flows

Look up and bind an existing user

Optional: a local mapping table as cache

Create a user from the CRM

Assign a badge

Pull-based worker skeleton

Handling conflicts

Common errors

Next steps