diff --git a/README.md b/README.md index 4329435..3b83eb9 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ pnpm dlx mintlify dev ## Changelog -See `changelog.mdx` for versioned documentation updates. The current documentation version is `v0.24.1`. +See `changelog.mdx` for versioned documentation updates. The current documentation version is `v0.24.2`. --- diff --git a/api-reference-backup/events/detail.mdx b/api-reference-backup/events/detail.mdx index 3e5ff0f..af63981 100644 --- a/api-reference-backup/events/detail.mdx +++ b/api-reference-backup/events/detail.mdx @@ -87,6 +87,7 @@ curl "https://platform.lensmor.com/external/events/139574" \ "image": "https://example.com/ces-image.png", "dataSource": "Lensmor", "exhibitorCount": 3259, + "hasVisitors": true, "personnelCount": null, "eventTypes": [] } @@ -105,6 +106,7 @@ curl "https://platform.lensmor.com/external/events/139574" \ | `dateStart`, `dateEnd` | Event date range. | | `venue`, `city`, `region`, `country`, `latitude`, `longitude` | Location metadata. Coordinates are string values (e.g. `"36.1313238"`) or `null`. | | `attendeeCount`, `exhibitorCount`, `personnelCount` | Known summary scale and coverage fields when available. These fields can be `null` or differ from current event-scoped list totals. | +| `hasVisitors` | `true` when the event currently has registered Visitor data available. This is separate from the caller's Visitor access state. | | `priceLower`, `priceUpper` | Price range as string values (e.g. `"1295"`) or `null`. | | `eventType`, `eventTypes`, `categories`, `topics`, `topicsCount` | Classification metadata. `categories` is an array of objects with `id`, `code`, `name`, `description`, `confidence` fields. | | `verified`, `future`, `historic`, `historicEvent` | Status flags and historical relationship metadata. | @@ -132,5 +134,6 @@ When you need current coverage numbers, call the event-scoped list endpoint and - Some fields can be `null` when the underlying source does not provide that data. - String-typed numeric fields (`latitude`, `longitude`, `priceLower`, `priceUpper`) require client-side parsing when used for calculations. - `dataSource` is always `"Lensmor"` for public event records. +- `hasVisitors` indicates Visitor data availability only. Use the Visitor or Full Access action precheck to confirm unlock eligibility, expected credits, and current access state. - `categories` is an array of objects. Each object contains `id` (integer), `code` (string), `name` (string), `description` (string or null), and `confidence` (string). - This endpoint does not unlock event-scoped exhibitor or personnel access by itself. diff --git a/api-reference-backup/events/list.mdx b/api-reference-backup/events/list.mdx index d5d12c7..8ad0601 100644 --- a/api-reference-backup/events/list.mdx +++ b/api-reference-backup/events/list.mdx @@ -81,6 +81,7 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "image": "https://example.com/ces-image.png", "dataSource": "Lensmor" @@ -108,6 +109,7 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le | `dateStart`, `dateEnd` | Event date range. | | `venue`, `city`, `region`, `country` | Location metadata. | | `exhibitorCount` | Known exhibitor count when available. | +| `hasVisitors` | `true` when the event currently has registered Visitor data available. This does not mean the caller has unlocked Visitor access. | | `sponsorMatchStarred` | Sponsor Match starred state (`0` or `1`). | | `dataSource` | Always `Lensmor` for public event records. | | `total`, `page`, `pageSize`, `totalPages`, `hasMore` | Pagination metadata. | @@ -121,5 +123,6 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le - Pagination fields follow the shared conventions described in [Pagination conventions](/concepts/pagination). - Results are not guaranteed to be relevance-ranked unless a keyword or filter strongly narrows the result set. - `id` and `eventId` currently return the same value. Use `eventId` when passing to event-scoped endpoints. +- `hasVisitors` is returned as an availability signal, but this endpoint does not expose a public `has_visitors` filter yet. For a known event, use the Visitor or Full Access action precheck before an unlock workflow. - `event_type` and `quality` filters must match actual values in the database (e.g. `In-person`, `conference_led` for event type; `Verified`, `Standard` for quality). Invalid values return an empty result set rather than an error. - Filter values are applied to the event catalog, but summary list items may still omit or return `null` for some classification fields. Fetch event detail when you need the full classification shape. diff --git a/api-reference-backup/openapi.json b/api-reference-backup/openapi.json index 1c2d407..12a1703 100644 --- a/api-reference-backup/openapi.json +++ b/api-reference-backup/openapi.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "Lensmor API", - "version": "0.24.1", + "version": "0.24.2", "description": "Lensmor Event Intelligence API for event discovery, exhibitor research, personnel lookup, credits, and profile matching.", "license": { "name": "Lensmor Terms of Service", @@ -160,7 +160,7 @@ "Events" ], "summary": "List events", - "description": "Search and filter the event catalog by keyword, geography, date, type, and quality with pagination.", + "description": "Search and filter the event catalog by keyword, geography, date, type, and quality with pagination. Event items include hasVisitors when registered Visitor data is available; the public event list does not currently expose a has_visitors query filter.", "operationId": "listEvents", "parameters": [ { @@ -254,6 +254,7 @@ "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "image": "https://example.com/ces-image.png", "dataSource": "Lensmor" @@ -283,7 +284,7 @@ "Events" ], "summary": "Get event detail", - "description": "Return the detailed public event record for one Lensmor event identifier.", + "description": "Return the detailed public event record for one Lensmor event identifier, including hasVisitors when registered Visitor data is available.", "operationId": "getEventDetail", "parameters": [ { @@ -320,6 +321,7 @@ "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "dataSource": "Lensmor" } @@ -1228,7 +1230,7 @@ "Personnel" ], "summary": "List event personnel", - "description": "Return paginated people for an event with event-scoped attendee source labels and preview or full base-event access semantics. The sourceType array can contain exhibitor, social, and visitors; labels are not mutually exclusive. The endpoint does not currently accept a source filter. Visitor is a separate access layer, so semantics.accessMode does not by itself confirm Visitor access.", + "description": "Return paginated people for an event with event-scoped attendee source labels and preview or full base-event access semantics. The sourceType array can contain exhibitor, social, and visitors; labels are not mutually exclusive. Use the sourceType query parameter to filter by one supported attendee source. Visitor is a separate access layer, so semantics.accessMode does not by itself confirm Visitor access.", "operationId": "listPersonnel", "parameters": [ { @@ -1277,6 +1279,20 @@ "type": "string", "maxLength": 200 } + }, + { + "name": "sourceType", + "in": "query", + "description": "Filter personnel by one event-scoped attendee source label. Supported values are exhibitor, social, and visitors.", + "schema": { + "type": "string", + "enum": [ + "exhibitor", + "social", + "visitors" + ], + "maxLength": 50 + } } ], "responses": { @@ -2833,6 +2849,10 @@ "null" ] }, + "hasVisitors": { + "type": "boolean", + "description": "True when the event currently has registered Visitor data available. This is an availability signal, not proof that the caller has unlocked Visitor access." + }, "sponsorMatchStarred": { "type": "integer", "enum": [ diff --git a/api-reference-backup/personnel/list.mdx b/api-reference-backup/personnel/list.mdx index ec8c685..3365316 100644 --- a/api-reference-backup/personnel/list.mdx +++ b/api-reference-backup/personnel/list.mdx @@ -6,7 +6,7 @@ openapi: "openapi.json GET /external/personnel/list" List personnel records for a specific event. -Use this endpoint when you want a paginated people directory for one event, with optional exhibitor, department, level, and search filters. Each item can include event-scoped Exhibitor, Social Signals, and Visitor source labels. +Use this endpoint when you want a paginated people directory for one event, with optional exhibitor, department, level, source-type, and search filters. Each item can include event-scoped Exhibitor, Social Signals, and Visitor source labels. ## When to use this endpoint @@ -16,12 +16,13 @@ Common use cases: - browse people associated with an event - filter by department or seniority +- filter by one event-scoped `sourceType` label - find contacts for a selected exhibitor - segment accessible attendees by their event-scoped `sourceType` labels - collect personnel IDs before calling [Unlock contact emails](/api-reference/contacts/unlock-contact-emails) - The endpoint does not currently accept a source filter. Fetch the accessible result set and segment it client-side. See [Attendee source types](/concepts/attendee-source-types). + `sourceType` filtering is event-scoped. Use `exhibitor`, `social`, or `visitors`; labels are still non-exclusive on returned records. See [Attendee source types](/concepts/attendee-source-types). ## Endpoint @@ -41,6 +42,7 @@ See [Authentication](/authentication) | `department` | No | string | Department filter. | | `level` | No | string | Seniority-level filter. | | `search_query` | No | string | Name or job-title search. | +| `sourceType` | No | string | Source label filter. Supported values: `exhibitor`, `social`, `visitors`. | | `page` | No | integer | Defaults to `1`. | | `pageSize` | No | integer | Defaults to `50`; maximum `50`. | @@ -57,6 +59,13 @@ curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&depar -H "Authorization: Bearer $LENSMOR_API_KEY" ``` +### Filter by attendee source + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + ## Response example ```json { diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 1c2d407..12a1703 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "Lensmor API", - "version": "0.24.1", + "version": "0.24.2", "description": "Lensmor Event Intelligence API for event discovery, exhibitor research, personnel lookup, credits, and profile matching.", "license": { "name": "Lensmor Terms of Service", @@ -160,7 +160,7 @@ "Events" ], "summary": "List events", - "description": "Search and filter the event catalog by keyword, geography, date, type, and quality with pagination.", + "description": "Search and filter the event catalog by keyword, geography, date, type, and quality with pagination. Event items include hasVisitors when registered Visitor data is available; the public event list does not currently expose a has_visitors query filter.", "operationId": "listEvents", "parameters": [ { @@ -254,6 +254,7 @@ "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "image": "https://example.com/ces-image.png", "dataSource": "Lensmor" @@ -283,7 +284,7 @@ "Events" ], "summary": "Get event detail", - "description": "Return the detailed public event record for one Lensmor event identifier.", + "description": "Return the detailed public event record for one Lensmor event identifier, including hasVisitors when registered Visitor data is available.", "operationId": "getEventDetail", "parameters": [ { @@ -320,6 +321,7 @@ "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "dataSource": "Lensmor" } @@ -1228,7 +1230,7 @@ "Personnel" ], "summary": "List event personnel", - "description": "Return paginated people for an event with event-scoped attendee source labels and preview or full base-event access semantics. The sourceType array can contain exhibitor, social, and visitors; labels are not mutually exclusive. The endpoint does not currently accept a source filter. Visitor is a separate access layer, so semantics.accessMode does not by itself confirm Visitor access.", + "description": "Return paginated people for an event with event-scoped attendee source labels and preview or full base-event access semantics. The sourceType array can contain exhibitor, social, and visitors; labels are not mutually exclusive. Use the sourceType query parameter to filter by one supported attendee source. Visitor is a separate access layer, so semantics.accessMode does not by itself confirm Visitor access.", "operationId": "listPersonnel", "parameters": [ { @@ -1277,6 +1279,20 @@ "type": "string", "maxLength": 200 } + }, + { + "name": "sourceType", + "in": "query", + "description": "Filter personnel by one event-scoped attendee source label. Supported values are exhibitor, social, and visitors.", + "schema": { + "type": "string", + "enum": [ + "exhibitor", + "social", + "visitors" + ], + "maxLength": 50 + } } ], "responses": { @@ -2833,6 +2849,10 @@ "null" ] }, + "hasVisitors": { + "type": "boolean", + "description": "True when the event currently has registered Visitor data available. This is an availability signal, not proof that the caller has unlocked Visitor access." + }, "sponsorMatchStarred": { "type": "integer", "enum": [ diff --git a/changelog.mdx b/changelog.mdx index 0c001db..964aa63 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -5,6 +5,21 @@ description: "Versioned Lensmor API documentation updates, newly documented endp Track documentation updates, newly documented API capabilities, and behavior clarifications that may affect integrations. +## v0.24.2 + +Released July 30, 2026. + +### Added + +- Documented the `sourceType` query parameter on `GET /external/personnel/list` for filtering event personnel by `exhibitor`, `social`, or `visitors`. +- Documented the `hasVisitors` response field on public event list and detail records. + +### Clarified + +- Clarified that `hasVisitors` is a Visitor-data availability signal and does not prove the caller has unlocked Visitor access. +- Clarified that the public event list documentation does not expose a `has_visitors` query filter yet. +- Updated OpenAPI metadata to version `0.24.2`. + ## v0.24.1 Released July 24, 2026. diff --git a/concepts/attendee-source-types.mdx b/concepts/attendee-source-types.mdx index eb60851..a460772 100644 --- a/concepts/attendee-source-types.mdx +++ b/concepts/attendee-source-types.mdx @@ -53,7 +53,16 @@ The `semantics.accessMode` field on the personnel list describes base event prev ## Filtering -`GET /external/personnel/list` does not currently accept a `sourceType` filter. Fetch the accessible event-scoped result set, then segment it client-side: +`GET /external/personnel/list` accepts a single `sourceType` query parameter when you want the API to return people matching one event-scoped source label: + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + +Supported values are `exhibitor`, `social`, and `visitors`. + +You can also fetch the accessible event-scoped result set without `sourceType`, then segment it client-side: ```js const visitors = items.filter((person) => @@ -61,7 +70,7 @@ const visitors = items.filter((person) => ); ``` -Because labels can overlap, a person may appear in more than one client-side segment. +Because labels can overlap, a person may match a source filter and still include additional `sourceType` values in the response. ## Related workflows diff --git a/docs/response-sources/events.md b/docs/response-sources/events.md index 42ccad0..8582490 100644 --- a/docs/response-sources/events.md +++ b/docs/response-sources/events.md @@ -5,8 +5,15 @@ - DTO/query source: `src/modules/external-api/dto/events/external-event-list-query.dto.ts` - Success status source: Nest default for `@Get()` -> `200 OK` - Response example source: `src/modules/external-api/services/external-events.service.ts#listEvents` and `src/modules/external-api/mappers/external-event-response.mapper.ts` +- Contract note: Public event items include `hasVisitors` from `ExternalEventResponseMapper.toEventItem`. The customer-facing docs expose this as a response field only; `has_visitors` is not documented as a public event-list filter yet. - Ambiguity note: The public example uses only fields directly emitted by `ExternalEventResponseMapper.toEventItem` plus the shared pagination envelope. +## GET /external/events/:id +- Method/path source: `src/modules/external-api/controllers/external-events.controller.ts` +- Success status source: Nest default for `@Get()` -> `200 OK` +- Response example source: `src/modules/external-api/services/external-events.service.ts#getEventDetail` and `src/modules/external-api/mappers/external-event-response.mapper.ts#toEventDetail` +- Contract note: Event detail includes `hasVisitors` from `ExternalEventResponseMapper.toEventDetail`; client types consume this as `ApiEvent.hasVisitors`. + ## POST /external/events/fit-score - Method/path source: `src/modules/external-api/controllers/external-events.controller.ts` - DTO/body source: `src/modules/external-api/dto/common/external-event-id-query.dto.ts` diff --git a/docs/response-sources/personnel-and-contacts.md b/docs/response-sources/personnel-and-contacts.md index 67fda3b..d9a08d6 100644 --- a/docs/response-sources/personnel-and-contacts.md +++ b/docs/response-sources/personnel-and-contacts.md @@ -6,7 +6,7 @@ - Success status source: Nest default for `@Get()` -> `200 OK` - Response example source: `src/modules/external-api/services/external-personnel.service.ts#list` and `src/modules/external-api/mappers/external-contact-response.mapper.ts` - Ambiguity note: Returned people use the contact-style public shape. -- Contract note: `sourceType` is a normalized string array. Supported labels are `exhibitor`, `social`, and `visitors`. +- Contract note: `sourceType` is a normalized string array. Supported labels are `exhibitor`, `social`, and `visitors`. The list query also accepts a single `sourceType` filter, sourced from `ExternalPersonnelListQueryDto.sourceType` and passed into `QueryLeadDto.sourceTypes`. ## GET /external/personnel/profile - Method/path source: `src/modules/external-api/controllers/external-personnel.controller.ts` diff --git a/guides/build-attendee-intelligence.mdx b/guides/build-attendee-intelligence.mdx index a08aea8..10cc37b 100644 --- a/guides/build-attendee-intelligence.mdx +++ b/guides/build-attendee-intelligence.mdx @@ -29,7 +29,7 @@ A person can have multiple labels. See [Attendee source types](/concepts/attende Unlock base event access for broader exhibitor/personnel coverage, Visitor access for registered attendee records, or full access for both missing layers. - Segment accessible records client-side, score the people relevant to your workflow, and unlock email or phone fields only for selected personnel IDs. + Filter or segment accessible records by source, score the people relevant to your workflow, and unlock email or phone fields only for selected personnel IDs. @@ -55,9 +55,18 @@ Each item can include a multi-value `sourceType`: Use the event-scoped list when you need source meaning for one selected event. Personnel profile and contact search can aggregate labels across multiple associated events. -## 2. Segment the accessible audience +## 2. Filter or segment the accessible audience -The personnel endpoint does not currently provide a server-side source filter. Preserve overlapping labels and segment the returned items in your application: +Use `sourceType` when you want the API to return one event-scoped source segment: + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + +Supported values are `exhibitor`, `social`, and `visitors`. Preserve overlapping labels because a matching person can still include additional `sourceType` values. + +When you fetch all accessible records, segment the returned items in your application: ```js const bySource = { @@ -116,6 +125,6 @@ Store the person ID, event ID, full `sourceType` array, and unlock state in your ## Current limitations -- Event list and event detail do not currently expose a public `hasVisitors` field. Use Visitor action precheck for a known event. -- Personnel list does not currently accept a source filter. +- Event list and event detail expose `hasVisitors` as a Visitor-data availability signal. +- Event list does not currently expose a public `has_visitors` query filter. - Visitor coverage varies by event and must not be inferred from event category, size, or location. diff --git a/index.mdx b/index.mdx index c6de7c7..d4a3370 100644 --- a/index.mdx +++ b/index.mdx @@ -7,7 +7,7 @@ Build event and attendee intelligence workflows with the Lensmor API. Use it to Use this documentation to authenticate, make your first request, and integrate Lensmor event, exhibitor, personnel, contact, and recommendation resources into your own workflows. -Current documentation version: `v0.24.1` +Current documentation version: `v0.24.2` ## Base URL `https://platform.lensmor.com` diff --git a/llms-full.txt b/llms-full.txt index 658f846..c4791dc 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -11,7 +11,7 @@ Build event and attendee intelligence workflows with the Lensmor API. Use it to Use this documentation to authenticate, make your first request, and integrate Lensmor event, exhibitor, personnel, contact, and recommendation resources into your own workflows. -Current documentation version: `v0.24.1` +Current documentation version: `v0.24.2` ## Base URL `https://platform.lensmor.com` @@ -209,6 +209,21 @@ Source: /changelog Track documentation updates, newly documented API capabilities, and behavior clarifications that may affect integrations. +## v0.24.2 + +Released July 30, 2026. + +### Added + +- Documented the `sourceType` query parameter on `GET /external/personnel/list` for filtering event personnel by `exhibitor`, `social`, or `visitors`. +- Documented the `hasVisitors` response field on public event list and detail records. + +### Clarified + +- Clarified that `hasVisitors` is a Visitor-data availability signal and does not prove the caller has unlocked Visitor access. +- Clarified that the public event list documentation does not expose a `has_visitors` query filter yet. +- Updated OpenAPI metadata to version `0.24.2`. + ## v0.24.1 Released July 24, 2026. @@ -494,7 +509,7 @@ A person can have multiple labels. See [Attendee source types](/concepts/attende Unlock base event access for broader exhibitor/personnel coverage, Visitor access for registered attendee records, or full access for both missing layers. - Segment accessible records client-side, score the people relevant to your workflow, and unlock email or phone fields only for selected personnel IDs. + Filter or segment accessible records by source, score the people relevant to your workflow, and unlock email or phone fields only for selected personnel IDs. @@ -520,9 +535,18 @@ Each item can include a multi-value `sourceType`: Use the event-scoped list when you need source meaning for one selected event. Personnel profile and contact search can aggregate labels across multiple associated events. -## 2. Segment the accessible audience +## 2. Filter or segment the accessible audience + +Use `sourceType` when you want the API to return one event-scoped source segment: + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + +Supported values are `exhibitor`, `social`, and `visitors`. Preserve overlapping labels because a matching person can still include additional `sourceType` values. -The personnel endpoint does not currently provide a server-side source filter. Preserve overlapping labels and segment the returned items in your application: +When you fetch all accessible records, segment the returned items in your application: ```js const bySource = { @@ -581,8 +605,8 @@ Store the person ID, event ID, full `sourceType` array, and unlock state in your ## Current limitations -- Event list and event detail do not currently expose a public `hasVisitors` field. Use Visitor action precheck for a known event. -- Personnel list does not currently accept a source filter. +- Event list and event detail expose `hasVisitors` as a Visitor-data availability signal. +- Event list does not currently expose a public `has_visitors` query filter. - Visitor coverage varies by event and must not be inferred from event category, size, or location. --- @@ -1378,6 +1402,7 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "image": "https://example.com/ces-image.png", "dataSource": "Lensmor" @@ -1405,6 +1430,7 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le | `dateStart`, `dateEnd` | Event date range. | | `venue`, `city`, `region`, `country` | Location metadata. | | `exhibitorCount` | Known exhibitor count when available. | +| `hasVisitors` | `true` when the event currently has registered Visitor data available. This does not mean the caller has unlocked Visitor access. | | `sponsorMatchStarred` | Sponsor Match starred state (`0` or `1`). | | `dataSource` | Always `Lensmor` for public event records. | | `total`, `page`, `pageSize`, `totalPages`, `hasMore` | Pagination metadata. | @@ -1418,6 +1444,7 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le - Pagination fields follow the shared conventions described in [Pagination conventions](/concepts/pagination). - Results are not guaranteed to be relevance-ranked unless a keyword or filter strongly narrows the result set. - `id` and `eventId` currently return the same value. Use `eventId` when passing to event-scoped endpoints. +- `hasVisitors` is returned as an availability signal, but this endpoint does not expose a public `has_visitors` filter yet. For a known event, use the Visitor or Full Access action precheck before an unlock workflow. - `event_type` and `quality` filters must match actual values in the database (e.g. `In-person`, `conference_led` for event type; `Verified`, `Standard` for quality). Invalid values return an empty result set rather than an error. - Filter values are applied to the event catalog, but summary list items may still omit or return `null` for some classification fields. Fetch event detail when you need the full classification shape. @@ -1510,6 +1537,7 @@ curl "https://platform.lensmor.com/external/events/139574" \ "image": "https://example.com/ces-image.png", "dataSource": "Lensmor", "exhibitorCount": 3259, + "hasVisitors": true, "personnelCount": null, "eventTypes": [] } @@ -1528,6 +1556,7 @@ curl "https://platform.lensmor.com/external/events/139574" \ | `dateStart`, `dateEnd` | Event date range. | | `venue`, `city`, `region`, `country`, `latitude`, `longitude` | Location metadata. Coordinates are string values (e.g. `"36.1313238"`) or `null`. | | `attendeeCount`, `exhibitorCount`, `personnelCount` | Known summary scale and coverage fields when available. These fields can be `null` or differ from current event-scoped list totals. | +| `hasVisitors` | `true` when the event currently has registered Visitor data available. This is separate from the caller's Visitor access state. | | `priceLower`, `priceUpper` | Price range as string values (e.g. `"1295"`) or `null`. | | `eventType`, `eventTypes`, `categories`, `topics`, `topicsCount` | Classification metadata. `categories` is an array of objects with `id`, `code`, `name`, `description`, `confidence` fields. | | `verified`, `future`, `historic`, `historicEvent` | Status flags and historical relationship metadata. | @@ -1555,6 +1584,7 @@ When you need current coverage numbers, call the event-scoped list endpoint and - Some fields can be `null` when the underlying source does not provide that data. - String-typed numeric fields (`latitude`, `longitude`, `priceLower`, `priceUpper`) require client-side parsing when used for calculations. - `dataSource` is always `"Lensmor"` for public event records. +- `hasVisitors` indicates Visitor data availability only. Use the Visitor or Full Access action precheck to confirm unlock eligibility, expected credits, and current access state. - `categories` is an array of objects. Each object contains `id` (integer), `code` (string), `name` (string), `description` (string or null), and `confidence` (string). - This endpoint does not unlock event-scoped exhibitor or personnel access by itself. @@ -3009,7 +3039,7 @@ Source: /api-reference/personnel/list-event-personnel List personnel records for a specific event. -Use this endpoint when you want a paginated people directory for one event, with optional exhibitor, department, level, and search filters. Each item can include event-scoped Exhibitor, Social Signals, and Visitor source labels. +Use this endpoint when you want a paginated people directory for one event, with optional exhibitor, department, level, source-type, and search filters. Each item can include event-scoped Exhibitor, Social Signals, and Visitor source labels. ## When to use this endpoint @@ -3019,12 +3049,13 @@ Common use cases: - browse people associated with an event - filter by department or seniority +- filter by one event-scoped `sourceType` label - find contacts for a selected exhibitor - segment accessible attendees by their event-scoped `sourceType` labels - collect personnel IDs before calling [Unlock contact emails](/api-reference/contacts/unlock-contact-emails) - The endpoint does not currently accept a source filter. Fetch the accessible result set and segment it client-side. See [Attendee source types](/concepts/attendee-source-types). + `sourceType` filtering is event-scoped. Use `exhibitor`, `social`, or `visitors`; labels are still non-exclusive on returned records. See [Attendee source types](/concepts/attendee-source-types). ## Endpoint @@ -3044,6 +3075,7 @@ See [Authentication](/authentication) | `department` | No | string | Department filter. | | `level` | No | string | Seniority-level filter. | | `search_query` | No | string | Name or job-title search. | +| `sourceType` | No | string | Source label filter. Supported values: `exhibitor`, `social`, `visitors`. | | `page` | No | integer | Defaults to `1`. | | `pageSize` | No | integer | Defaults to `50`; maximum `50`. | @@ -3060,6 +3092,13 @@ curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&depar -H "Authorization: Bearer $LENSMOR_API_KEY" ``` +### Filter by attendee source + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + ## Response example ```json { @@ -4710,7 +4749,16 @@ The `semantics.accessMode` field on the personnel list describes base event prev ## Filtering -`GET /external/personnel/list` does not currently accept a `sourceType` filter. Fetch the accessible event-scoped result set, then segment it client-side: +`GET /external/personnel/list` accepts a single `sourceType` query parameter when you want the API to return people matching one event-scoped source label: + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + +Supported values are `exhibitor`, `social`, and `visitors`. + +You can also fetch the accessible event-scoped result set without `sourceType`, then segment it client-side: ```js const visitors = items.filter((person) => @@ -4718,7 +4766,7 @@ const visitors = items.filter((person) => ); ``` -Because labels can overlap, a person may appear in more than one client-side segment. +Because labels can overlap, a person may match a source filter and still include additional `sourceType` values in the response. ## Related workflows diff --git a/openapi.json b/openapi.json index 1c2d407..12a1703 100644 --- a/openapi.json +++ b/openapi.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "Lensmor API", - "version": "0.24.1", + "version": "0.24.2", "description": "Lensmor Event Intelligence API for event discovery, exhibitor research, personnel lookup, credits, and profile matching.", "license": { "name": "Lensmor Terms of Service", @@ -160,7 +160,7 @@ "Events" ], "summary": "List events", - "description": "Search and filter the event catalog by keyword, geography, date, type, and quality with pagination.", + "description": "Search and filter the event catalog by keyword, geography, date, type, and quality with pagination. Event items include hasVisitors when registered Visitor data is available; the public event list does not currently expose a has_visitors query filter.", "operationId": "listEvents", "parameters": [ { @@ -254,6 +254,7 @@ "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "image": "https://example.com/ces-image.png", "dataSource": "Lensmor" @@ -283,7 +284,7 @@ "Events" ], "summary": "Get event detail", - "description": "Return the detailed public event record for one Lensmor event identifier.", + "description": "Return the detailed public event record for one Lensmor event identifier, including hasVisitors when registered Visitor data is available.", "operationId": "getEventDetail", "parameters": [ { @@ -320,6 +321,7 @@ "region": "Nevada", "country": "United States", "exhibitorCount": 3259, + "hasVisitors": true, "sponsorMatchStarred": 0, "dataSource": "Lensmor" } @@ -1228,7 +1230,7 @@ "Personnel" ], "summary": "List event personnel", - "description": "Return paginated people for an event with event-scoped attendee source labels and preview or full base-event access semantics. The sourceType array can contain exhibitor, social, and visitors; labels are not mutually exclusive. The endpoint does not currently accept a source filter. Visitor is a separate access layer, so semantics.accessMode does not by itself confirm Visitor access.", + "description": "Return paginated people for an event with event-scoped attendee source labels and preview or full base-event access semantics. The sourceType array can contain exhibitor, social, and visitors; labels are not mutually exclusive. Use the sourceType query parameter to filter by one supported attendee source. Visitor is a separate access layer, so semantics.accessMode does not by itself confirm Visitor access.", "operationId": "listPersonnel", "parameters": [ { @@ -1277,6 +1279,20 @@ "type": "string", "maxLength": 200 } + }, + { + "name": "sourceType", + "in": "query", + "description": "Filter personnel by one event-scoped attendee source label. Supported values are exhibitor, social, and visitors.", + "schema": { + "type": "string", + "enum": [ + "exhibitor", + "social", + "visitors" + ], + "maxLength": 50 + } } ], "responses": { @@ -2833,6 +2849,10 @@ "null" ] }, + "hasVisitors": { + "type": "boolean", + "description": "True when the event currently has registered Visitor data available. This is an availability signal, not proof that the caller has unlocked Visitor access." + }, "sponsorMatchStarred": { "type": "integer", "enum": [ diff --git a/scripts/test_sync_public_assets.py b/scripts/test_sync_public_assets.py index 2f4c01e..75892bd 100644 --- a/scripts/test_sync_public_assets.py +++ b/scripts/test_sync_public_assets.py @@ -137,7 +137,7 @@ def test_public_openapi_has_descriptions_and_examples(self) -> None: def test_company_search_contract_matches_current_credit_rule(self) -> None: spec = json.loads(self.sync.OPENAPI_SOURCE.read_text(encoding="utf-8")) - self.assertEqual(spec["info"]["version"], "0.24.1") + self.assertEqual(spec["info"]["version"], "0.24.2") company_search = spec["paths"]["/external/exhibitors/search-by-company-name"]["post"] self.assertIn("non-empty", company_search["description"]) @@ -165,6 +165,25 @@ def test_event_search_and_event_item_contracts(self) -> None: event_fields = schemas["EventItem"]["properties"] self.assertEqual(event_fields["dataSource"]["const"], "Lensmor") self.assertEqual(event_fields["sponsorMatchStarred"]["enum"], [0, 1]) + self.assertEqual(event_fields["hasVisitors"]["type"], "boolean") + self.assertIn("availability signal", event_fields["hasVisitors"]["description"]) + + event_list = spec["paths"]["/external/events/list"]["get"] + event_list_parameter_names = [ + parameter.get("name") + for parameter in event_list["parameters"] + if "$ref" not in parameter + ] + self.assertNotIn("has_visitors", event_list_parameter_names) + self.assertTrue( + event_list["responses"]["200"]["content"]["application/json"]["example"]["items"][0][ + "hasVisitors" + ] + ) + self.assertTrue( + spec["paths"]["/external/events/{id}"]["get"]["responses"]["200"]["content"] + ["application/json"]["example"]["event"]["hasVisitors"] + ) event_examples = [ spec["paths"]["/external/events/list"]["get"]["responses"]["200"]["content"] @@ -269,6 +288,18 @@ def test_v024_access_and_balance_contracts(self) -> None: ) self.assertIn("not mutually exclusive", source_type["description"]) + personnel_list = spec["paths"]["/external/personnel/list"]["get"] + self.assertNotIn("does not currently accept a source filter", personnel_list["description"]) + source_type_parameter = next( + parameter + for parameter in personnel_list["parameters"] + if parameter.get("name") == "sourceType" + ) + self.assertEqual( + source_type_parameter["schema"]["enum"], + ["exhibitor", "social", "visitors"], + ) + source_examples = [ spec["paths"]["/external/personnel/list"]["get"]["responses"]["200"] ["content"]["application/json"]["example"]["items"][0]["sourceType"], diff --git a/zh-Hans/concepts/attendee-source-types.mdx b/zh-Hans/concepts/attendee-source-types.mdx index 8b98652..0db46e6 100644 --- a/zh-Hans/concepts/attendee-source-types.mdx +++ b/zh-Hans/concepts/attendee-source-types.mdx @@ -53,7 +53,16 @@ Personnel List 返回的 `semantics.accessMode` 只描述基础 Event Access， ## 来源筛选 -`GET /external/personnel/list` 当前没有 `sourceType` 服务端筛选参数。请先获取当前可访问的数据，再在客户端分类： +`GET /external/personnel/list` 支持使用单个 `sourceType` 查询参数，让 API 返回匹配某个展会范围来源标签的人员： + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + +支持的值为 `exhibitor`、`social` 和 `visitors`。 + +也可以不传 `sourceType`，先获取当前可访问的展会范围数据，再在客户端分类： ```js const visitors = items.filter((person) => @@ -61,7 +70,7 @@ const visitors = items.filter((person) => ); ``` -由于标签可能重叠，同一个人可以同时出现在多个分类中。 +由于标签可能重叠，一个人即使命中某个来源筛选，响应中的 `sourceType` 仍可能包含其他来源值。 ## 相关文档 diff --git a/zh-Hans/guides/build-attendee-intelligence.mdx b/zh-Hans/guides/build-attendee-intelligence.mdx index 89a91b5..71aa9f0 100644 --- a/zh-Hans/guides/build-attendee-intelligence.mdx +++ b/zh-Hans/guides/build-attendee-intelligence.mdx @@ -29,7 +29,7 @@ Lensmor Attendees 包含三种来源标签： 基础 Event Access 用于扩大 Exhibitor/Personnel 覆盖；Visitor Access 用于注册访客；Full Access 可一次解锁两个缺失的访问层。 - 在客户端按来源分类，筛选与业务目标相关的人员，只对最终选中的 Personnel ID 解锁邮箱或电话。 + 按来源筛选或分类当前可访问的人员，只对最终选中的 Personnel ID 解锁邮箱或电话。 @@ -55,9 +55,18 @@ curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&page= 需要判断某个来源与当前展会的关系时，应使用 Personnel List。Personnel Profile 和 Contact Search 可能聚合该人员在多个关联展会中的来源标签。 -## 2. 在客户端分类 +## 2. 按来源筛选或分类 -Personnel List 当前没有来源筛选参数。请保留重叠标签，并在应用中分类： +当你只需要某个展会范围来源分类时，可以在 Personnel List 上使用 `sourceType` 参数： + +```bash +curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&sourceType=visitors&page=1&pageSize=50" \ + -H "Authorization: Bearer $LENSMOR_API_KEY" +``` + +支持的值为 `exhibitor`、`social` 和 `visitors`。由于标签可能重叠，命中筛选的人员仍可能在响应中包含其他 `sourceType` 值。 + +如果一次获取全部可访问人员，请保留重叠标签，并在应用中分类： ```js const bySource = { @@ -116,6 +125,6 @@ curl -X POST "https://platform.lensmor.com/external/actions/precheck" \ ## 当前限制 -- Event List 和 Event Detail 暂未公开 `hasVisitors` 字段，已知展会应通过 Visitor action precheck 判断。 -- Personnel List 暂不支持来源筛选参数。 +- Event List 和 Event Detail 已公开 `hasVisitors` 字段，用于表示 Visitor 数据是否可用。 +- Event List 暂不公开 `has_visitors` 查询筛选参数。 - Visitor 覆盖因展会而异，不能通过展会类别、规模或地点推断。 diff --git a/zh-Hans/index.mdx b/zh-Hans/index.mdx index 8b2e6c0..5f759ea 100644 --- a/zh-Hans/index.mdx +++ b/zh-Hans/index.mdx @@ -5,7 +5,7 @@ description: "使用 Lensmor API 构建展会与参会人员洞察、参展商 使用 Lensmor API 构建展会与参会人员洞察工作流。你可以发现展会、评估展会匹配度、查看参展商和参会人员来源，在数据可用时访问注册 Visitor，并在需要行动时解锁联系方式。 -当前文档版本：`v0.24.1` +当前文档版本：`v0.24.2` ## Base URL