Create an event

post

https://api.suresend.ai/api/partner/events

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:

Use existing person ID: Provide personId to attach to an existing contact
Match existing person: Provide person object with email/phone - system will find matching contact
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:

Use existing company ID: Provide company.id to link to an existing company
Match by name: Provide company.name - system will find matching company (case-insensitive)
Create new company: If no match found, a new company is created
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"
  }
}

Note: The type field accepts property_view and other variants (propertyView, viewed_property) — these are automatically normalized to "Viewed Property" in the API response.

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

personId

uuid

ID of existing person (use this OR person object, not both)

person

object

Person data to create or match. System will search for existing person by email/phone and create if not found. Use this OR personId, not both.

company

object

Company data to create or match. System will search for existing company by name (case-insensitive) and create if not found. When a company is associated, the person is automatically linked to the company. Matching Behavior: 1) If id provided: Lookup by exact ID, 2) If name provided: Case-insensitive search within your team, 3) If no match found: New company is created, 4) Person is automatically associated with the company, 5) New companies are set as the person's primary company.

eventType

string

⚠️ DEPRECATED: Use "type" instead

type

string

required

Required. Event type - see common types in GET endpoint documentation. Custom types are also supported.

occurredAt

date-time

When the event occurred (ISO 8601 format). Defaults to current time if not provided.

message

string

Short summary (1-2 sentences)

description

string

Longer detailed description of the event

source

string

Event source/origin (website, mobile_app, email, etc.)

system

string

Tracking system that generated the event

pageUrl

string

Page URL (for page_view events)

pageTitle

string

Page title (for page_view events)

pageDuration

integer

Time spent on page in seconds (for page_view events)

pageReferrer

string

HTTP referrer (for page_view events)

referrer

string

General referrer information

ipAddress

string

IP address for tracking/analytics

userAgent

string

Browser user agent string

metadata

object

Flexible key-value pairs for any additional data.

Validation Limits:

Maximum size: 256 KB (262,144 bytes)
Maximum keys: 100 at root level
Maximum depth: 10 levels of nesting

These limits ensure system performance while providing flexibility for comprehensive event tracking.

property

object

Property details for property-related events (property_view, inquiry, etc.).

Image URL (imageUrl): You can optionally include an imageUrl field with a direct URL
to the property image. If provided, this image URL will be used instead of automatically
fetching the Open Graph image from the property url. If imageUrl is not provided and
the property includes a url or listingUrl field, the system will automatically attempt
to fetch the OG image in the background.

propertySearch

object

Search criteria for property search events. Contains structured fields describing what a person was searching for. The code field accepts a single string or array of strings for zipcodes — it is always normalized to an array. Optionally include an imageUrl to display a search-related image (e.g., a neighborhood photo or map thumbnail).

campaign

object

Marketing campaign tracking (UTM parameters, campaign IDs, etc.)

Responses

200

event created with existing company (matched by name)

201

event created with both new person and new company

400company name required when no id provided

401unauthorized

404person not found