Create an event

Create a new event to track interactions and activities. Events are the core of contact engagement tracking.

Person Matching: You can associate events with people in three ways:

1. Use existing person ID: Provide personId to attach to an existing contact
2. Match existing person: Provide person object with email/phone - system will find matching contact
3. Create new person: Provide person object with details - system will create new contact if no match found

Company Association (Optional): You can also associate a company with the event and person:

1. Use existing company ID: Provide company.id to link to an existing company
2. Match by name: Provide company.name - system will find matching company (case-insensitive)
3. Create new company: If no match found, a new company is created
4. Auto-link person: The person is automatically associated with the company

Response Status Codes:

• 201 Created: A new person OR company was created
• 200 OK: Both person and company already existed (matched existing records)

Common Event Patterns:

Page View Event:

{
  "type": "page_view",
  "personId": "uuid-here",
  "pageUrl": "https://example.com/properties/123",
  "pageTitle": "Beautiful 3BR Home",
  "pageDuration": 45,
  "pageReferrer": "https://google.com"
}

Property View Event:

{
  "type": "property_view",
  "person": { "emails": [{"value": "[email protected]"}] },
  "property": {
    "id": "prop-123",
    "address": "123 Main St, Portland, OR 97201",
    "price": 500000,
    "beds": 3,
    "baths": 2,
    "sqft": 1800
  }
}

Property View Event with Custom Image URL: If you already have an image URL for the property, provide it via imageUrl inside the property object to skip the automatic Open Graph image fetch:

{
  "type": "property_view",
  "person": { "emails": [{"value": "[email protected]"}] },
  "property": {
    "id": "prop-123",
    "address": "123 Main St, Portland, OR 97201",
    "url": "https://listings.example.com/prop-123",
    "price": 500000,
    "imageUrl": "https://cdn.example.com/images/prop-123.jpg"
  }
}

Property Search Event:

{
  "type": "Property Search",
  "personId": "uuid-here",
  "propertySearch": {
    "type": "Residential",
    "neighborhood": "Pearl District",
    "city": "Portland",
    "state": "OR",
    "code": ["97209", "97210"],
    "minPrice": 300000,
    "maxPrice": 500000,
    "minBedrooms": 2,
    "maxBedrooms": 4,
    "minBathrooms": 1.5,
    "maxBathrooms": 3,
    "searchUrl": "https://example.com/search?q=portland-97209"
  }
}

Note: The type field accepts common variants like property_search or propertySearch — these are automatically normalized to "Property Search". The code field in propertySearch accepts either a single string ("97209") or an array (["97209", "97210"]) and is always stored as an array.

Form Submission Event (Object Format):

{
  "type": "form_submission",
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "emails": [{"value": "[email protected]", "isPrimary": true}],
    "phones": [{"value": "+1-555-1234", "isPrimary": true}]
  },
  "message": "Contact form submitted",
  "metadata": {
    "formName": "Contact Us",
    "interests": ["buying", "3-bedroom"]
  }
}

Form Submission Event (Simple String Array Format):

{
  "type": "form_submission",
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "emails": ["[email protected]", "[email protected]"],
    "phones": ["+1-555-1234", "+1-555-5678"]
  },
  "message": "Contact form submitted",
  "metadata": {
    "formName": "Contact Us",
    "interests": ["buying", "3-bedroom"]
  }
}

Note: When using the string array format, the first email and first phone are automatically marked as primary.

Event with Company (B2B Lead):

{
  "type": "form_submission",
  "person": {
    "firstName": "Jane",
    "lastName": "Smith",
    "emails": [{"value": "[email protected]", "isPrimary": true}]
  },
  "company": {
    "name": "Acme Corporation",
    "website": "https://acmecorp.com",
    "industry": "Technology",
    "companySize": "51-200"
  },
  "message": "Demo request submitted"
}

Response with Company: Returns the created event, person, company, and flags indicating what was created:

{
  "event": { "id": "...", "type": "form_submission", ... },
  "person": { "id": "...", "firstName": "Jane", ... },
  "company": { "id": "...", "name": "Acme Corporation", ... },
  "wasPersonCreated": true,
  "wasCompanyCreated": true
}

Response (without company): Returns the created event, associated person, and a flag indicating whether a new person was created.