Import CRM data

This guide walks through importing data from HubSpot, Salesforce, or another CRM into Clarify.

Before you start

1. Create an API key in Settings > API Keys
2. Export your CRM data as CSV files (companies, contacts, deals)
3. Snapshot existing records — even "empty" workspaces may have records from email sync or enrichment

# Check what's already in the workspace
curl --globoff -H "Authorization: api-key $KEY" \
  "https://api.clarify.ai/v1/workspaces/$WS/objects/person/resources?page[limit]=1"

If the workspace has existing records, you need to pre-match your import data to avoid duplicates. The bulk create endpoint returns 400 on email/domain collisions.

Import order

Always follow this order — later objects reference earlier ones:

1. Companies — no dependencies
2. People — link to companies via company_id
3. Deals — link to companies via company_id
4. Associations — link people to deals via relationships endpoint

Step 1: Create companies

Use the bulk create endpoint to import companies in batches of up to 25:

curl -X POST \
  -H "Authorization: api-key $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "type": "company",
        "attributes": {
          "name": "Acme Corp",
          "domains": { "items": ["acme.com"] }
        }
      }
    ]
  }' \
  "https://api.clarify.ai/v1/workspaces/$WS/objects/company/records/bulk"

Save the returned id values — you'll need them to link people and deals.

Step 2: Create people

curl -X POST \
  -H "Authorization: api-key $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "type": "person",
        "attributes": {
          "first_name": "Jane",
          "last_name": "Doe",
          "email_addresses": { "items": ["jane@acme.com"] },
          "company_id": "com_01HX..."
        }
      }
    ]
  }' \
  "https://api.clarify.ai/v1/workspaces/$WS/objects/person/records/bulk"

Step 3: Create deals

curl -X POST \
  -H "Authorization: api-key $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "type": "deal",
        "attributes": {
          "name": "Acme Renewal Q1",
          "amount": 50000,
          "stage": "Negotiation",
          "company_id": "com_01HX..."
        }
      }
    ]
  }' \
  "https://api.clarify.ai/v1/workspaces/$WS/objects/deal/records/bulk"

Step 4: Link people to deals

curl -X PATCH \
  -H "Authorization: api-key $KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": [{"id": "rec_person_xyz", "type": "person"}]}' \
  "https://api.clarify.ai/v1/workspaces/$WS/objects/deal/records/rec_deal_456/relationships/people"

Batching

The bulk endpoints accept up to 25 records per request. Batches are atomic — if one record fails, the whole batch is rejected. Start with smaller batches (5–10) for your first import to catch data issues early.

See bulk operations for more details.

Common pitfalls

CRM-specific tips

HubSpot

• Default exports don't include association columns. Add "Associated Company IDs" and "Associated Deal IDs" to the list view before exporting.
• Lifecycle stages map to Clarify's person status field.

Salesforce

• Watch for catch-all accounts ("Website Leads", "Unknown Company") with hundreds of contacts. Import those contacts without a company link.
• Use OpportunityContactRole export for deal-to-person associations.

Pipedrive

• Exports contain comma-separated emails. Use only the first email — Clarify enforces uniqueness across the workspace.
• Domains are exported as full URLs. Strip http://, https://, and www. before importing.