HOALedgerIQ_Website/agents/sales-lead/CRM_INTEGRATION.md

Twenty CRM Integration for HoaLedgerIQ Sales Lead Monitor

API Configuration

• Base URL: https://salesforce.hoaledgeriq.com/rest
• Auth Header: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5M2FmNGFmNS0zZWQ0LTQ1ZDMtOWE5Zi01MDMzZjc3YTY3MjMiLCJ0eXBlIjoiQVBJX0tFWSIsIndvcmtzcGFjZUlkIjoiOTNhZjRhZjUtM2VkNC00NWQzLTlhOWYtNTAzM2Y3N2E2NzIzIiwiaWF0IjoxNzczMzI4NDQzLCJleHAiOjE4MDQ3ODE2NDIsImp0aSI6IjIwZjEyYzkwLTRkMDctNGJmNi1iMzk3LTZjNmU3MzlmMThjOCJ9.zeM5NvwCSGEcz99m2LYtgb0sVD6WUXcCF7SwonFg930
• Owner ID: ecf52aad-4827-40c9-9475-b68f3ca9a924

Lead Sources

1. ROI Calculator Submissions

Endpoint: GET https://hoaledgeriq.com/api/calc-submissions

Headers:

x-admin-key: K9mP2vL8x4qR7nZ

Response Fields:

• email - Lead email address
• homesites - Number of homesites
• annual_income - Estimated annual income
• property_type - Type of property
• payment_freq - Payment frequency
• reserve_funds - Reserve funds amount
• interest_2025 - Interest calculation
• total_potential - Total potential value
• opt_in - Whether user opted in
• ai_recommendation - AI-generated recommendation
• created_at - Submission timestamp

2. Direct Lead Form (localhost:3000)

Endpoint: GET http://localhost:3000/api/leads

Headers:

x-admin-key: K9mP2vL8x4qR7nZ

Note: This endpoint is only available when the dev server is running locally.

CRM Create Flow: Calc Submission → Notes → Sales Review → Opportunity

Updated flow based on your sales process:

1. Leads go to Notes attached to People (not Opportunities)
2. Sales team reviews Notes and decides who to qualify
3. Qualified leads get promoted to Opportunities

Previous Flow (Opportunity-first) - DEPRECATED

The integration previously created Opportunities directly. Now leads are queued in Notes for review.

Step 1: Check if Person Exists

curl -s "https://salesforce.hoaledgeriq.com/rest/people" \
  -H "Authorization: Bearer <token>"

Filter response for matching email.

Step 2: Create Person (if not exists)

curl -s -X POST "https://salesforce.hoaledgeriq.com/rest/people" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {
      "firstName": "<email_local_part>",
      "lastName": "(Lead)"
    },
    "emails": {
      "primaryEmail": "<email>",
      "additionalEmails": []
    }
  }'

Returns person ID (e.g., 2c28136a-2ba1-4234-be50-0130da851d3e)

Step 3: Create Note (Lead Queue)

curl -s -X POST "$TWENTY_BASE/notes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lead: <email> | <homesites> homes | $<annual_income>/y",
    "body": "## 🏘️ ROI Calculator Lead\n\n**Email:** <email>\n**Homesites:** <homesites>\n...",
    "personId": "<person_id>"
  }'

Note goes to your Notes/Lead Review area in Twenty. Sales team promotes to Opportunity when qualified.

curl -s -X POST "https://salesforce.hoaledgeriq.com/rest/opportunities" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ROI Calc - <email>",
    "stage": "NEW",
    "amount": {
      "amountMicros": <annual_income * 1000000>,
      "currencyCode": "USD"
    },
    "closeDate": "<date_90_days_from_now>",
    "pointOfContactId": "<person_id>",
    "ownerId": "ecf52aad-4827-40c9-9475-b68f3ca9a924"
  }'

Field Mappings

Calc Submission → CRM

Source Field	CRM Field	Notes
email	Person.emails.primaryEmail	Primary identifier
email (before @)	Person.name.firstName	Parsed from email
"(Lead)"	Person.name.lastName	Default value
annual_income	Opportunity.amount.amountMicros	Multiplied by 1,000,000
created_at + 90 days	Opportunity.closeDate	Auto-calculated
"NEW"	Opportunity.stage	Default stage
"ROI Calc - {email}"	Opportunity.name	Auto-generated

Calc Details → Opportunity Notes

Additional calc fields saved as notes:

• Homesites count
• Property type
• Payment frequency
• Reserve funds
• 2025 interest
• Total potential
• AI recommendation

State Tracking

File: /Users/claw/.openclaw/workspace/agents/sales-lead/state.json

{
  "processed_leads": ["local_lead_id_1", "local_lead_id_2"],
  "processed_calc_ids": [1, 2, 3, 4],
  "crm_pushed": {
    "calc_ids": [1],
    "lead_ids": []
  },
  "last_check": "2026-03-12T13:00:00Z",
  "status": "active"
}

Testing

Test person created: 2c28136a-2ba1-4234-be50-0130da851d3e Test opportunity created: Validated working