Migration guide

Bringing your data into Pact takes one of two paths: a one-time CSV import through the import wizard, or a native connector that authenticates against your source CRM and syncs records for you. Most teams do both — connect the CRM for the bulk of records, and use CSV for anything the connector doesn't cover.

Which path to choose

CSV import

The import wizard (/v1/admin/imports, surfaced in the app under Settings → Data import) handles the full lifecycle: draft, upload, map, preview, run. Supported entity types are account, contact, deal, activity, product, ticket, contract, journey, and custom_object (core/imports/schema.py); accounts land in companies, contacts in contacts, and deals in the deals table.

Carrying consent in a CSV

A contact import can map one optional column onto Email marketing consent (email_marketing_consent, core/imports/schema.py). The wizard auto-maps headers such as Consent, Email consent, Marketing consent or Subscription status. It never auto-maps an Opted out or Unsubscribed header, because that would invert every row.

Each non-blank cell becomes one event in the consent ledger, written through the consent module's own API (ConsentService.record) under its own validation (core/imports/consent.py):

Every event carries source: "import", the time the import ran (Pact records when it learned the decision and does not claim the date your old system held), and proof text naming the import, row, column and cell. Two rules hold regardless of what the file says:

• An import never overturns a withdrawal. A grant for someone whose current state in Pact is Withdrawn is not recorded, and the import's result says so row by row (kept_existing_withdrawal). A withdrawal always lands.
• A consent cell needs an email address. A row with a consent value but no email is counted as skipped_no_email. Nothing is guessed.

The import's result carries a consent block with the counts (recorded_granted, recorded_withdrawn, kept_existing_withdrawal, skipped_no_email, failed) and up to 25 per-row notes. A ledger write that fails is counted under failed and logged. It never removes the contacts the import already wrote.

Native connectors

Connectors live under /v1/integrations and are provider-agnostic by design. Today the wired providers are Salesforce, HubSpot, and Pipedrive (api/routes/integrations.py).

Salesforce

Salesforce is the most complete connector — OAuth connect, scheduled + manual sync, and writeback:

• POST /v1/integrations/salesforce/start returns the authorize URL (supports sandbox orgs via a sandbox flag).
• GET /v1/integrations/salesforce/callback handles the OAuth redirect; the state parameter is single-use and tenant-scoped so a leaked link can't be replayed cross-tenant.
• GET /v1/integrations/salesforce/status shows connection state, sync stats, recent runs, and your org's daily-API-call headroom (scraped from Sforce-Limit-Info).
• POST /v1/integrations/salesforce/sync triggers a manual "Sync now".
• DELETE /v1/integrations/salesforce disconnects and clears stored tokens.

# 1. Begin the OAuth handshake
curl -X POST https://api.pact.place/v1/integrations/salesforce/start \
  -H "Authorization: Bearer $PACT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sandbox": false}'
# → { "authorize_url": "https://login.salesforce.com/...", "state": "..." }

# 2. Open authorize_url in a browser, approve, land back on the callback.
# 3. Trigger the first pull:
curl -X POST https://api.pact.place/v1/integrations/salesforce/sync \
  -H "Authorization: Bearer $PACT_TOKEN"

HubSpot & Pipedrive

HubSpot and Pipedrive share the same integration store, status surface, and run history as Salesforce, and their sync clients (core/integrations/hubspot, core/integrations/pipedrive) map source objects onto the same account/contact tables the CSV wizard targets. Their authentication and sync model differs from Salesforce, though:

• Auth is an API token, not three-legged OAuth. HubSpot connects with a Private App access token and Pipedrive with an API token, supplied through the in-app BYOK/settings flow. There is no /start + /callback OAuth handshake for these two — full user-consent OAuth is a follow-up (core/integrations/hubspot/__init__.py notes the three-legged flow as a layered PR).
• Sync is manual. POST /v1/integrations/hubspot/sync and POST /v1/integrations/pipedrive/sync are "Sync now" triggers with run history. The 30-minute background scheduler (core/integrations/salesforce/sync.py run_incremental) is Salesforce-only today.

After the migration

• Consent is carried only where the source actually recorded a decision. A contact with no consent record reads No record on every person surface and is blocked from marketing sends until consent is captured. What sets a record:

  • CSV wizard: the optional consent column described in Carrying consent in a CSV.
  • CRM migration (/v1/admin/migrations, core/migration/importer.py): records a granted or withdrawn event with source crm_import only when the provider returns a decision. Salesforce reads HasOptedOutOfEmail: true is recorded as withdrawn and false as granted. HubSpot reads hs_email_optout: true is withdrawn, false is granted, and an absent flag records nothing. Pipedrive reads marketing_status: subscribed is granted, unsubscribed or no_consent is withdrawn, and anything else records nothing. Zoho has no consent flag on a contact, so it records nothing. The source's own value is always kept verbatim with the migration record.
  • Native sync connectors (/v1/integrations/*) do not write consent.

  If a Salesforce or HubSpot "not opted out" is not consent under the regime you operate in, record the decision yourself through the consent API after the migration.

• Verify record linkage. Spot-check that contacts resolved to the right accounts and deals to the right pipeline stages before you switch off the old system.

• Public IDs, not integer IDs. Pact exposes UUID public_id values in URLs and API responses; the integer primary keys from your old CRM aren't reused. Bookmark and integrate against public_id.