Record Visit (v1)

Method + Path

POST /v1/public/tracking/visit

Actual backend path: /v1/public/tracking/visit

Description

Record a visit to a vCard or storefront. This endpoint is used for analytics and tracking purposes.

Authentication

Not required - This is a public endpoint

Headers

Header	Type	Required	Description
Content-Type	string	Yes	application/json

Request Body

{
  "type": "vcard",
  "destinationSlug": "john-doe",
  "sessionId": "session-123",
  "utmName": "email-campaign",
  "userAgent": "Mozilla/5.0...",
  "referer": "https://example.com",
  "ipAddress": "192.168.1.1",
  "country": "United States",
  "city": "New York",
  "deviceType": "mobile",
  "browser": "Chrome",
  "os": "iOS"
}

Body Parameters

Parameter	Type	Required	Description
type	string	Yes	Visit type. Valid values: vcard, storefront
destinationSlug	string	Yes	Slug of the vCard or storefront
sessionId	string	Yes	Unique session identifier
utmName	string	No	UTM campaign name
userAgent	string	No	User agent string (max 500 characters)
referer	string	No	Referrer URL (max 1000 characters)
ipAddress	string	No	IP address (max 45 characters)
country	string	No	Country name (max 100 characters)
city	string	No	City name (max 100 characters)
deviceType	string	No	Device type. Valid values: desktop, mobile, tablet, unknown
browser	string	No	Browser name (max 100 characters)
os	string	No	Operating system (max 100 characters)

Response (200)

{
  "visit": {
    "id": "507f1f77bcf86cd799439011",
    "sessionId": "session-123",
    "type": "vcard",
    "destinationSlug": "john-doe",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Common Errors

• 400 Bad Request: Invalid request body
• 404 Not Found: Destination not found
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error