Apply recommended events (paged results)

Apply profile-matching input and return paged event recommendations. Use this endpoint when you want to submit company or audience context and receive filtered recommended events in one request.

Endpoint

POST /external/profile-matching/actions/apply-recommended-events/paged

Authentication

See Authentication

Success status code

201 Created

Request body

Field	Required	Type	Notes
`company_url`	Conditionally	string	Optional company URL. At least one of `company_url` or `target_audience` is required.
`target_audience`	Conditionally	string	Optional audience description. At least one of `company_url` or `target_audience` is required.
`timeout_ms`	No	integer	Optional request timeout, min `60000`, max `3600000`.
`page`	No	integer	Defaults to `1`.
`pageSize`	No	integer	Defaults to `20`, max `100`.
`autoRecommendTop3EventsEnabled`	No	boolean	Optional per-request override for immediate top-3 recommendation reasons.
`city`	No	string	Exact city filter.
`region`	No	string	Exact region filter.
`country`	No	string	Exact country filter.
`category`	No	string[]	Category filters; accepts an array or a comma-separated string.
`eventTypeIds`	No	integer[]	Event type filters; accepts an array or a comma-separated string.
`dateStartFrom`	No	`YYYY-MM-DD` string	Lower date bound.
`dateStartTo`	No	`YYYY-MM-DD` string	Upper date bound.
`future`	No	integer	Future-only flag.
`attendeeCountMin`	No	integer	Minimum attendee count.
`attendeeCountMax`	No	integer	Maximum attendee count.

Response body

Top-level fields

Field	Type	Notes
`status`	string	One of `processing`, `failed`, `completed_empty`, or `completed`.
`items`	object[]	Recommended events for the current page.
`total`	integer	Total recommended events after filtering.
`page`	integer	Current page number.
`pageSize`	integer	Page size used for this response.
`totalPages`	integer	`0` when `total` is `0`.
`hasMore`	boolean	`true` when another page exists.
`condition_tags`	object	Structured filter summary for the current result set.
`parsed_filters_snapshot`	object, optional	Normalized filter summary when available.
`relaxed_conditions`	object, optional	Relaxed matching conditions when available.
`profile_version`	integer	Current profile version.
`active_result_version`	integer or `null`	Version identifier for the recommendation set returned in this response.
`is_stale`	boolean	`true` when the response is based on a previous recommendation set while a refreshed set is still being prepared.
`empty_reason`	string, optional	Empty-result reason when status is empty or failed.
`failed_filters`	string[], optional	Filters that did not match.
`candidate_count`	integer, optional	Candidate count before matching.
`suggestions`	string[], optional	Suggested filter adjustments.

`items[]` fields

Field	Type	Notes
`id`	integer	Lensmor event identifier.
`eventId`	string	Source event identifier, when available.
`name`	string or `null`	Event name.
`nickname`	string or `null`	Event short name.
`description`	string or `null`	Event description.
`url`	string or `null`	Event website URL.
`dateStart`	`YYYY-MM-DD` string or `null`	Start date.
`dateEnd`	`YYYY-MM-DD` string or `null`	End date.
`venue`	string or `null`	Venue name.
`city`	string or `null`	City.
`region`	string or `null`	Region or state.
`country`	string or `null`	Country.
`latitude`	string or `null`	Latitude rendered as a string.
`longitude`	string or `null`	Longitude rendered as a string.
`attendeeCount`	integer	Attendance count.
`declaredExpectedAttendees`	integer	Declared attendance expectation.
`estimatedExpectedAttendees`	string or `null`	Estimated attendance expectation rendered as a string.
`priceLower`	string or `null`	Lower ticket price rendered as a string.
`priceUpper`	string or `null`	Upper ticket price rendered as a string.
`eventType`	string or `null`	Primary event-type label.
`categories`	object[]	Category metadata.
`topics`	string[]	Topic list.
`topicsCount`	integer	Topic count.
`verified`	integer	Verification flag.
`future`	integer	Future-event flag.
`historic`	integer	Historic-event flag.
`historicEvent`	string or `null`	Historic event marker.
`image`	string or `null`	Image URL.
`dataSource`	string or `null`	Source label.
`exhibitorCount`	integer	Exhibitor count.
`personnelCount`	integer	Personnel count.
`eventTypes`	object[]	Event-type rows.
`createTime`	integer-like value	Millisecond timestamp from the event row.
`updateTime`	integer-like value	Millisecond timestamp from the event row.
`unlocked`	boolean	User-specific unlock flag.
`matched_exhibitor_count`	integer	Number of matched exhibitors at the event.
`match_score`	number or `null`	Recommendation score for the event.

Response example

{
  "status": "completed",
  "items": [
    {
      "id": 123,
      "eventId": "139574",
      "name": "NRF 2026",
      "nickname": null,
      "description": "Retail technology event",
      "url": "https://example.com/events/nrf-2026",
      "dateStart": "2026-01-12",
      "dateEnd": "2026-01-15",
      "venue": "Javits Center",
      "city": "New York",
      "region": "NY",
      "country": "United States",
      "latitude": null,
      "longitude": null,
      "attendeeCount": 10000,
      "declaredExpectedAttendees": 0,
      "estimatedExpectedAttendees": null,
      "priceLower": null,
      "priceUpper": null,
      "eventType": null,
      "categories": [],
      "topics": [],
      "topicsCount": 0,
      "verified": 1,
      "future": 1,
      "historic": 0,
      "historicEvent": null,
      "image": null,
      "dataSource": "Lensmor",
      "exhibitorCount": 250,
      "personnelCount": 1800,
      "eventTypes": [],
      "createTime": 1711000000000,
      "updateTime": 1711000000000,
      "unlocked": false,
      "matched_exhibitor_count": 12,
      "match_score": 0.82
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20,
  "totalPages": 1,
  "hasMore": false,
  "condition_tags": {},
  "profile_version": 3,
  "active_result_version": 3,
  "is_stale": false
}

Error responses

400 Bad Request when the body fails validation.
401 Unauthorized when the API key is missing, malformed, or invalid.
409 Conflict when a recommendation task is already running for the user.

Notes

This is the preferred endpoint for new profile-matching integrations.
Responses can include status, condition_tags, and empty-result guidance such as empty_reason, failed_filters, and suggestions.
match_score here is the recommendation score; POST /external/events/fit-score separately normalizes it onto a 0-10 style scale.

Documentation Index

​Apply recommended events (paged results)

​Endpoint

​Authentication

​Success status code

​Request body

​Response body

​Top-level fields

​items[] fields

​Response example

​Error responses

​Notes