Creating Touchpoints
How to track user activities and events using touchpoints
Touchpoints record user activities and events from integrated platforms, providing a comprehensive view of member engagement across your ecosystem.
Overview
A touchpoint tracks a meaningful interaction a person has within an association's integrated ecosystem. An association's integrated ecosystem in this case refers to any system connected to Wicket and set up to create touchpoints within Wicket.
A touchpoint captures a specific interaction or event:
- What happened: The action taken (e.g., "Event Attended")
- Who did it: The person involved
- When it occurred: Timestamp of the activity
- Context: Additional details about the event
Touchpoint Structure
Each touchpoint contains:
| Field | Description | Example |
|---|---|---|
person_id | Wicket person UUID | "abc123-..." |
service_id | Integration service UUID | "def456-..." |
action | Human-readable description | "Order Completed" |
code | Machine-readable identifier | "order_completed" |
details | Additional context | "Product: Pro Plan\\n\\nOrder Total: $99.00 USD" |
data | Additional context (JSON) | {"product_name": "..."} |
external_event_id | Unique identifier for the activity | "your_platform:unique_event_id" |
created_at | When the event happened | "2025-01-15T10:30:00Z" |
Creating a Touchpoint
POST /touchpoints
{
"person_id": "wicket-person-uuid",
"service_id": "your-service-uuid",
"action": "Order Completed",
"code": "order_completed",
"details": "Product: Pro Plan\\n\\nOrder Total: $99.00 USD",
"external_event_id": "your_platform:unique_event_id",
"data": {
"order_id": 12345,
"order_total": 99.00,
"currency": "USD",
"product": "Pro Plan"
},
"created_at": "2025-01-01T06:00:00.000Z"
}How touchpoints are built
Action (Human-Readable)
- Use past tense: "Attended event", "Purchased product"
- Be descriptive but concise
- Consistent capitalization
Code (Machine-Readable)
- Use snake_case:
event_attended,product_purchased - Be specific and consistent
Details vs Data
The details and data fields serve different purposes but should be built together:
details(string): Human-readable text displayed in the UI. Build it dynamically to show only relevant information.data(JSON): Structured data for programmatic access. Maintain a consistent structure across all touchpoints of the same type.
Best practices:
- Include all displayable information from
detailsindataas well, so it's not necessary to extract values from thedetailsstring. - Include IDs and other metadata in
datathat may be useful for future development or integrations, even if not displayed indetails. - For optional fields, conditionally include them in
detailsonly when they have values (to keep a clean UI), but always include them indatawithnullto maintain a consistent structure.
Example with optional event price:
{
"details": "Event: Annual Conference 2025\n\nDate: January 15, 2025\n\nPrice: $99.00",
"data": {
"event_id": "evt_123",
"event_name": "Annual Conference 2025",
"event_date": "2025-01-15",
"event_price": 99.00
}
}When there's no price:
{
"details": "Event: Annual Conference 2025\n\nDate: January 15, 2025",
"data": {
"event_id": "evt_123",
"event_name": "Annual Conference 2025",
"event_date": "2025-01-15",
"event_price": null
}
}Common Touchpoint Patterns
E-commerce
| Action | Code |
|---|---|
| Order Created | order_created |
| Order Processing | order_processing |
| Order Pending | order_pending |
| Order On-Hold | order_on_hold |
| Order Marked Completed | order_marked_completed |
| Order Refunded | order_refunded |
| Order Cancelled | order_cancelled |
| Order Deleted | order_deleted |
Event Management
| Action | Code |
|---|---|
| Registered for an event | event_registered |
| Attended an event | event_attended |
Learning Management System
| Action | Code |
|---|---|
| Enrolled in a course | enrolled_in_a_course |
| Completed a course | completed_a_course |
Email Marketing
| Action | Code |
|---|---|
| Email Clicked | email_clicked |
| Email Opened | email_opened |
| Email Subscribed | email_subscribed |
| Email Unsubscribed | email_unsubscribed |
Accreditation Software
| Action | Code |
|---|---|
| Submission Started | submission_started |
| Submission Complete | submission_complete |
Timing Considerations
Use created_at to specify when the actual event happened. Always use the external platform's event timestamp for created_at to maintain accurate timelines.
Historical Data
When importing historical data:
- Set
created_atto the original event time - Process in chronological order when possible
Deduplication
Prevent duplicate touchpoints by using the external_event_id field. This field acts as an idempotency key - if a touchpoint with the same external_event_id already exists, a new one will not be created.
Bulk Touchpoint Creation
For importing multiple touchpoints:
POST /touchpoints/bulk
{
"touchpoints": [
{
"person_id": "...",
"service_id": "...",
"action": "...",
"code": "...",
"created_at": "..."
},
// ... more touchpoints
]
}Best Practices
- Be consistent: Use the same action/code patterns across your integration
- Include context: Add relevant details and data for future analysis
- Use accurate timestamps: Always use the event's actual time
- Avoid duplicates: Check before creating, especially for webhooks
- Document codes: Maintain a reference of all touchpoint codes you create
- Keep details structured: Use consistent field names in details JSON