ShiftScale Integration Platform

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│  CDK / CRM  │ ──────▶ │  ShiftScale  │ ──────▶ │     GHL     │
│ (Fortellis) │ ◀────── │   Sync Engine│ ◀────── │   (CRM)     │
└─────────────┘         └──────────────┘         └─────────────┘
                              │
                        ┌─────┴─────┐
                        │  Postgres │  RecordLinks, SyncRuns,
                        │    DB     │  FieldMappings, AuditLogs
                        └───────────┘

// Only sync contacts that have an email OR phone
{
  "requireEither": true,
  "requireEmail": false,
  "requirePhone": false
}

emails[0].address        → First email address
phones[0].number         → First phone number
address.addressLine1     → Street address
address.city             → City
address.state            → State
address.zip              → ZIP code

{
  "entityType": "VEHICLE",
  "cdkField": "vin",
  "ghlField": "vin",
  "ghlTargetType": "custom_object",
  "ghlCustomObjectKey": "custom_objects.vehicles",
  "direction": "CDK_TO_GHL"
}

{
  "connectionId": "cmml1tsuh00000ajscv63aliu",
  "entityType": "CONTACT",
  "cdkRecordId": "12345",
  "ghlRecordId": "abc-def-ghi",
  "ghlObjectKey": null,         // null for contacts
  "cdkHash": "sha256...",       // detect changes
  "ghlHash": "sha256...",
  "syncStatus": "COMPLETED"
}

vehicle_id, vin, licensePlateNum, makeCode, make,
modelCode, model, modelYear, exteriorColor, mileage,
status, delivered, inService, warrantyExpiration,
ownerHref, primaryDriverHref, href

POST /api/sync/{connectionId}/webhook/register

Response:
{
  "webhookUrl": "https://integration.shiftscaledigital.ai/api/webhooks/connections/{id}/ghl",
  "secretKey": "a1b2c3d4...",
  "instructions": {
    "step1": "Go to GHL → Settings → Webhooks (or Automations → Workflows)",
    "step2": "Add webhook URL",
    "step3": "Select events: Contact Create, Contact Update",
    "step4": "Set x-webhook-secret header with the secret key",
    "step5": "Changes will auto-sync to CDK"
  }
}

Header: x-webhook-secret
Value:  HMAC-SHA256(secret_key, raw_request_body)

GHL webhook fires (contact created/updated)
  │
  ├─ RecordLink exists for this GHL contact?
  │   └─ YES → Update linked CDK record → done ✅
  │
  └─ NO → Search CDK by email, then phone
       ├─ CDK match found → Create RecordLink + Update CDK → done ✅
       └─ No match → Create new CDK contact + RecordLink → done ✅

Every path ends with a locked two-way link.

{
  "type": "ContactCreate",       // or "ContactUpdate"
  "id": "ghl_contact_id",
  "locationId": "...",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+15551234567"
}

{
  "action": "create",
  "contactId": "ghl_contact_id",
  "type": "Phone Call",
  "subject": "Follow-up call",
  "description": "Discuss trade-in options",
  "scheduledDate": "2025-03-20T10:00:00Z",
  "opportunityId": "opp_123",
  "userId": "salesperson_456"
}

{
  "action": "list",
  "contactId": "ghl_contact_id",
  "dateFrom": "2025-01-01",
  "dateTo": "2025-03-31"
}

{
  "action": "update",
  "activityId": "cdk_activity_id",
  "subject": "Updated subject",
  "scheduledDate": "2025-03-25T14:00:00Z"
}

{
  "action": "complete",
  "activityId": "cdk_activity_id",
  "completedDate": "2025-03-18T15:30:00Z",
  "notes": "Customer confirmed appointment"
}

// Success
{
  "ok": true,
  "action": "CREATE",         // CREATE | LIST | UPDATE | COMPLETE
  "ghlContactId": "...",      // for create/list
  "cdkContactId": "...",      // for create/list
  "cdkActivityId": "...",     // for create
  "activityId": "...",        // for update/complete
  "activity": { ... },        // CDK activity object
  "activities": [ ... ]       // for list action
}

// Error
{
  "ok": false,
  "error": "Contact not synced to CDK. Sync the contact first."
}

{
  "type": "ContactCreate",   // or "ContactUpdate"
  "id": "ghl_contact_id",
  "locationId": "...",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+15551234567"
}

{
  "ok": true,
  "action": "CREATE",    // CREATE | UPDATE | SKIP | FAIL
  "ghlContactId": "...",
  "cdkRecordId": "...",
  "error": null
}

CDK rate limit:     100 requests / 60 seconds
Page size:          100 contacts / page
Page delay:         500ms between pages
Timeout:            240s (auto-save as PARTIAL)
Fresh sync speedup: Skips GHL dedup when no existing links

1. Fetch batch of 20 CDK contacts
2. For each contact, fetch their vehicles
3. Map vehicle fields → GHL custom_objects.vehicles
4. Create/update vehicle records in GHL
5. Create RecordLink with ghlObjectKey = "custom_objects.vehicles"
6. Tag each vehicle record with ownerContactId