Skip to main content

​
Recommended events (paged results)

Request paged event recommendations for the authenticated caller. Use this endpoint when you want recommendation results plus the filtering and status metadata returned by the current profile-matching flow.

​
Endpoint

POST /external/profile-matching/recommendations/events/paged

​
Authentication

See Authentication

​
Success status code

201 Created

​
Request body

NameRequiredTypeNotes
company_urlConditionallystringPublic http(s) URL. Provide at least one of company_url or target_audience.
target_audienceConditionallystringAudience description. Provide at least one of company_url or target_audience.
timeout_msNointegerOptional sync processing timeout in milliseconds.
pageNointegerDefaults to 1.
pageSizeNointegerDefaults to 20; maximum 100.
cityNostringCity filter.
regionNostringRegion filter.
countryNostringCountry filter.
categoryNostring[]Category filter; arrays and comma-separated inputs are normalized by the DTO.
eventTypeIdsNointeger[]Event type ID filter.
dateStartFromNoISO date stringLower date bound.
dateStartToNoISO date stringUpper date bound.
futureNointegerFuture-event flag.
attendeeCountMinNointegerMinimum attendee count.
attendeeCountMaxNointegerMaximum attendee count.

​
Response example

{
  "status": "completed",
  "items": [
    {
      "id": 123,
      "eventId": "139574",
      "name": "NRF 2026",
      "nickname": null,
      "description": "Retail industry 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": 40000,
      "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": "database",
      "exhibitorCount": 950,
      "personnelCount": 6200,
      "eventTypes": [],
      "createTime": 1711000000000,
      "updateTime": 1711000000000,
      "matched_exhibitor_count": 19,
      "match_score": 0.84,
      "unlocked": false
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3,
  "hasMore": true,
  "condition_tags": {},
  "profile_version": 12,
  "active_result_version": 12,
  "is_stale": false
}

​
Error responses

  • 400 Bad Request
  • 401 Unauthorized
  • 409 Conflict

​
Notes

  • This route runs synchronous apply-onboarding first, then returns the current paged recommendation snapshot.
  • Paging is applied after duplicate recommendation rows are merged by event.
  • match_score is the raw recommendation score; POST /external/events/fit-score separately normalizes a score onto a 0-10 style scale.
  • Top-level metadata includes status, condition_tags, profile_version, active_result_version, and is_stale.
  • Empty-result responses may also include empty_reason, failed_filters, candidate_count, and suggestions.