Lensmor Profile Matching API

openapi: 3.2.0
info:
  title: Lensmor Profile Matching API
  version: 0.27.0
  description: Lensmor Event Intelligence API for event discovery, exhibitor research, personnel lookup, credits, and profile matching.
  license:
    name: Lensmor Terms of Service
    url: https://www.lensmor.com/terms
servers:
- url: https://platform.lensmor.com
security:
- bearerAuth: []
tags:
- name: Profile Matching
  description: Apply a buyer profile to rank events and recommend exhibitors.
paths:
  /external/profile-matching/actions/apply-recommended-events/paged:
    post:
      tags:
      - Profile Matching
      summary: Apply profile and get recommended events
      description: 'Apply company-profile inputs synchronously and return a paginated set of Lensmor events ranked for that profile.


        Use this endpoint when discovery starts from a company website or target-audience description rather than from a known event. Provide at least one of `company_url` or `target_audience`, then optionally narrow results by geography, category, event type, dates, future status, or attendee-count range.


        This endpoint does not spend credits or unlock event access. Recommendation scores, tiers, reasons, and matched-exhibitor evidence are point-in-time outputs that can change as the profile or Lensmor data changes. Use neutral event list search when profile-based ranking is not required.'
      operationId: applyRecommendedEventsPaged
      requestBody:
        $ref: '#/components/requestBodies/ProfileMatchingBody'
      responses:
        '201':
          description: Recommended events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileEventRecommendationPage'
              example:
                status: completed
                items:
                - id: '501'
                  eventId: '10067'
                  name: American Banker Digital Banking 2026
                  city: Orlando
                  country: United States
                  attendeeCount: 1825
                  declaredExpectedAttendees: 600
                  sourceTags: []
                  dataSource: Lensmor
                  matched_exhibitor_count: 19
                  matched_personnel_count: 85
                  match_score: 0.84
                  unlocked: false
                  relevanceReason: null
                  rank: 1
                total: 42
                page: 1
                pageSize: 20
                totalPages: 3
                hasMore: true
                condition_tags: {}
                profile_version: 12
                active_result_version: 12
                is_stale: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
  /external/profile-matching/recommendations/exhibitors:
    get:
      tags:
      - Profile Matching
      summary: Get recommended exhibitors for event
      description: 'Return exhibitor recommendation state for one selected event under the authenticated user''s current profile.


        Use this endpoint when the workflow needs profile-aware exhibitor prioritization rather than the neutral event exhibitor catalog. Filters can narrow the recommendation page by location, company text or exact name, category, industry, and employee-count range.


        Depending on recommendation readiness, items can contain ranked match evidence or an unranked fallback state. Inspect `recommendationProcessing`, `isRecommended`, rank, status, score, tier, and reason instead of assuming every result is fully scored. Use the standard exhibitor list when preview/full event-access semantics are the primary requirement.'
      operationId: getRecommendedExhibitors
      parameters:
      - $ref: '#/components/parameters/EventIdQuery'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - name: location
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by one or more country or region labels. Repeat the query parameter for multiple values.
        example:
        - United States
      - name: searchQuery
        in: query
        schema:
          type: string
        description: Search company names or descriptions within the event recommendation set.
        example: analytics
      - name: exhibitorName
        in: query
        schema:
          type: array
          items:
            type: string
        description: Filter by one or more exact exhibitor company names.
        example:
        - Acme
      - $ref: '#/components/parameters/CategoryArray'
      - $ref: '#/components/parameters/IndustryArray'
      - name: employeesMin
        in: query
        schema:
          type: integer
          minimum: 0
        description: Minimum company employee count, inclusive.
        example: 50
      - name: employeesMax
        in: query
        schema:
          type: integer
          minimum: 0
        description: Maximum company employee count, inclusive.
        example: 1000
      responses:
        '200':
          description: Paginated recommendation state or unranked fallback exhibitor rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendedExhibitorPage'
              example:
                items:
                - id: '456'
                  companyName: Acme Retail Systems
                  isRecommended: true
                  recommendationRank: 1
                  matchStatus: ready
                  matchScore: 91
                  matchTier: top_match
                  reason: Strong fit for the active profile.
                total: 87
                page: 1
                pageSize: 20
                totalPages: 5
                hasMore: true
                recommendationProcessing: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    EventIdQuery:
      name: event_id
      in: query
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 100
      description: Lensmor event identifier returned as `id` or `eventId` by event responses.
      example: '26855'
    Page:
      name: page
      in: query
      description: One-based page number. Use `1` for the first page and increment it while `hasMore` is `true`.
      example: 1
      schema:
        type: integer
        minimum: 1
        default: 1
    CategoryArray:
      name: category
      in: query
      schema:
        type: array
        items:
          type: string
      description: Filter by one or more category labels. Repeat the query parameter for multiple values.
      example:
      - Technology
    IndustryArray:
      name: industry
      in: query
      schema:
        type: array
        items:
          type: string
      description: Filter by one or more industry labels. Repeat the query parameter for multiple values.
      example:
      - Software
    PageSize:
      name: pageSize
      in: query
      description: Maximum number of records requested per page. The shared default is `20` and the shared upper limit is `100`; individual endpoints can document a lower maximum.
      example: 20
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  schemas:
    EventItem:
      type: object
      required:
      - id
      - eventId
      - name
      properties:
        id:
          type: string
          description: Stable Lensmor identifier for this record.
        eventId:
          type: string
          description: Public event identifier accepted by event-scoped endpoints.
        name:
          type:
          - string
          - 'null'
          description: Display name when available.
        nickname:
          type:
          - string
          - 'null'
          description: Alternative or shortened event name when available.
        description:
          type:
          - string
          - 'null'
          description: Public description when available.
        url:
          type:
          - string
          - 'null'
          description: Canonical public website URL when available.
        dateStart:
          type:
          - string
          - 'null'
          format: date
          description: Event start date in ISO `YYYY-MM-DD` format when available.
        dateEnd:
          type:
          - string
          - 'null'
          format: date
          description: Event end date in ISO `YYYY-MM-DD` format when available.
        venue:
          type:
          - string
          - 'null'
          description: Event venue name when available.
        city:
          type:
          - string
          - 'null'
          description: City associated with the record when available.
        region:
          type:
          - string
          - 'null'
          description: Region, state, or province when available.
        country:
          type:
          - string
          - 'null'
          description: Country associated with the record when available.
        exhibitorCount:
          type:
          - integer
          - 'null'
          description: Known exhibitor count for the event when available.
        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:
          - 0
          - 1
          description: Sponsor Match starred state returned by Lensmor.
        image:
          type:
          - string
          - 'null'
          description: Public image or logo URL when available.
        dataSource:
          type: string
          const: Lensmor
          description: Source label for the returned Lensmor record.
      additionalProperties: true
      description: Shared public event summary used by event lists, search results, and recommendation workflows.
    ProfileEventRecommendationPage:
      allOf:
      - $ref: '#/components/schemas/EventPage'
      - type: object
        properties:
          status:
            type: string
            enum:
            - completed
            - completed_empty
            description: 'Synchronous recommendation outcome: results returned or no matching events found.'
          condition_tags:
            type: object
            additionalProperties: true
            description: Condition tags returned as part of this profile event recommendation page object.
          profile_version:
            type:
            - integer
            - 'null'
            description: Profile version returned as part of this profile event recommendation page object.
          active_result_version:
            type:
            - integer
            - 'null'
            description: Active result version returned as part of this profile event recommendation page object.
          is_stale:
            type: boolean
            description: Is stale returned as part of this profile event recommendation page object.
          items:
            type: array
            items:
              $ref: '#/components/schemas/ProfileRecommendedEvent'
            description: Recommended event records for the requested page.
        additionalProperties: true
        required:
        - status
        - condition_tags
        - profile_version
        - active_result_version
        - is_stale
      description: Paginated profile-matched events and recommendation metadata.
    RecommendedExhibitorItem:
      type: object
      required:
      - id
      - companyName
      - isRecommended
      properties:
        id:
          type: string
          description: Stable Lensmor identifier for this record.
        companyName:
          type: string
          description: Company display name when available.
        description:
          type:
          - string
          - 'null'
          description: Public description when available.
        logo:
          type:
          - string
          - 'null'
          description: Company logo URL when available.
        website:
          type:
          - string
          - 'null'
          description: Company website URL when available.
        country:
          type:
          - string
          - 'null'
          description: Country associated with the record when available.
        industry:
          type:
          - string
          - 'null'
          description: Normalized company industry when available.
        categories:
          type: array
          items:
            type: string
          description: Category labels associated with the company or event.
        employeeCount:
          type:
          - integer
          - 'null'
          description: Known company employee count when available.
        companySize:
          type:
          - string
          - 'null'
          description: Normalized company-size band when available.
        fundingRound:
          type:
          - string
          - 'null'
          description: Latest known funding-round label when available.
        techStacks:
          type: array
          items:
            type: string
          description: Known technology-stack labels associated with the company.
        isRecommended:
          type: boolean
          description: True only when the item belongs to the active recommendation snapshot.
        recommendationRank:
          type:
          - integer
          - 'null'
          minimum: 1
          description: One-based recommendation rank when scoring is ready.
        matchStatus:
          type:
          - string
          - 'null'
          enum:
          - pending_unlock
          - processing
          - ready
          - failed
          - null
          description: Current recommendation or matching processing state.
        matchScore:
          type:
          - number
          - 'null'
          description: Numeric profile-match score when available.
        matchTier:
          type:
          - string
          - 'null'
          enum:
          - top_match
          - strong_match
          - qualifying_match
          - null
          description: Normalized match tier when available.
        reason:
          type:
          - string
          - 'null'
          description: Recommendation reason when matchStatus is ready. The field name is reason, not matchReason.
      additionalProperties: true
      description: Exhibitor company plus recommendation readiness and match evidence.
    EventPage:
      type: object
      required:
      - items
      - total
      - page
      - pageSize
      - totalPages
      - hasMore
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EventItem'
          description: Records returned on the current page or in the current batch.
        total:
          type: integer
          description: Total matching records across all pages.
        page:
          type: integer
          description: One-based page number returned.
        pageSize:
          type: integer
          description: Maximum records requested for this page.
        totalPages:
          type: integer
          description: Total pages available for the current query.
        hasMore:
          type: boolean
          description: Whether another result page is available.
      additionalProperties: true
      description: Standard paginated collection of public event summaries.
    RecommendedExhibitorPage:
      type: object
      required:
      - items
      - total
      - page
      - pageSize
      - totalPages
      - hasMore
      - recommendationProcessing
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RecommendedExhibitorItem'
          description: Records returned on the current page or in the current batch.
        total:
          type: integer
          minimum: 0
          description: Total matching records across all pages.
        page:
          type: integer
          minimum: 1
          description: One-based page number returned.
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          description: Maximum records requested for this page.
        totalPages:
          type: integer
          minimum: 0
          description: Total pages available for the current query.
        hasMore:
          type: boolean
          description: Whether another result page is available.
        recommendationProcessing:
          type: boolean
          description: True when recommendation detail generation is still processing for the event.
        code:
          type:
          - string
          - 'null'
          enum:
          - AI_SEARCH_RESULT_MISMATCH
          - null
          description: Present on unranked fallback results.
        show_refresh_hint:
          type: boolean
          description: Present on fallback results. This flag does not identify the cause or prescribe a required action.
      additionalProperties: true
      description: Paginated exhibitor recommendation state for one event.
    ProfileRecommendedEvent:
      allOf:
      - $ref: '#/components/schemas/EventDetail'
      - type: object
        required:
        - matched_exhibitor_count
        - matched_personnel_count
        - match_score
        - unlocked
        - rank
        properties:
          declaredExpectedAttendees:
            type:
            - integer
            - 'null'
            description: Organizer-declared expected attendee count when available.
          estimatedExpectedAttendees:
            type:
            - string
            - 'null'
            description: Estimated expected attendee count serialized as a string when available.
          quality:
            type:
            - string
            - 'null'
            description: Event quality label when available.
          sourceTags:
            type: array
            items:
              type: string
            description: Source classification tags associated with the event.
          visibilityStatus:
            type: integer
            description: Event visibility state returned by the service.
          previewPersonnelCount:
            type:
            - integer
            - 'null'
            description: Preview personnel count when populated for the event.
          createTime:
            type: string
            pattern: ^[0-9]+$
            description: Creation time as a millisecond timestamp serialized to a decimal string.
          updateTime:
            type: string
            pattern: ^[0-9]+$
            description: Last update time as a millisecond timestamp serialized to a decimal string.
          matched_exhibitor_count:
            type: integer
            description: Number of exhibitors matched to the supplied profile for this event.
          matched_personnel_count:
            type: integer
            description: Number of personnel matched to the supplied profile for this event.
          match_score:
            type:
            - number
            - 'null'
            minimum: 0
            maximum: 1
            description: Profile-to-event match score, or `null` when the scorer did not return one.
          unlocked:
            type: boolean
            description: Whether base event access is already unlocked for the API key owner.
          relevanceReason:
            type:
            - string
            - 'null'
            description: Human-readable recommendation reason when generated; otherwise omitted or `null`.
          rank:
            type: integer
            minimum: 1
            description: One-based recommendation rank returned by the ICP recommendation pipeline.
      description: Full Lensmor event metadata plus profile-recommendation evidence and rank.
    ApiError:
      type: object
      required:
      - code
      - message
      - errorKey
      - traceId
      properties:
        code:
          type: integer
          description: Numeric or symbolic code that identifies the response or business condition.
        message:
          type: string
          description: Human-readable explanation suitable for logs or user-facing error handling.
        errorKey:
          type: string
          description: Stable machine-readable error key for branching and analytics.
        traceId:
          type: string
          description: Request trace identifier to include in support or incident reports.
        details:
          description: Optional structured business or validation context. Omitted when the error has no additional details.
      description: Shared error envelope returned by public Lensmor API endpoints.
    EventDetail:
      allOf:
      - $ref: '#/components/schemas/EventItem'
      - type: object
        properties:
          latitude:
            type:
            - string
            - 'null'
            description: Latitude returned as part of this event detail object.
          longitude:
            type:
            - string
            - 'null'
            description: Longitude returned as part of this event detail object.
          attendeeCount:
            type:
            - integer
            - 'null'
            description: Attendee Count returned as part of this event detail object.
          priceLower:
            type:
            - string
            - 'null'
            description: Price Lower returned as part of this event detail object.
          priceUpper:
            type:
            - string
            - 'null'
            description: Price Upper returned as part of this event detail object.
          eventType:
            type:
            - string
            - 'null'
            description: Event Type returned as part of this event detail object.
          categories:
            type: array
            items:
              type: object
              additionalProperties: true
            description: Category labels associated with the company or event.
          topics:
            type: array
            items:
              type: string
            description: Topics returned as part of this event detail object.
          topicsCount:
            type: integer
            description: Topics Count returned as part of this event detail object.
          verified:
            type: integer
            description: Verified returned as part of this event detail object.
          future:
            type: integer
            description: Future returned as part of this event detail object.
          historic:
            type: integer
            description: Historic returned as part of this event detail object.
          historicEvent:
            type:
            - string
            - 'null'
            description: Historic Event returned as part of this event detail object.
          personnelCount:
            type:
            - integer
            - 'null'
            description: Personnel Count returned as part of this event detail object.
          eventTypes:
            type: array
            items:
              type: object
              additionalProperties: true
            description: Event Types returned as part of this event detail object.
      description: Detailed event response that extends the shared event summary.
  responses:
    Conflict:
      description: Business conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 409
            message: Request conflicts with the current resource state
            errorKey: STATE_CONFLICT
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 404
            message: Resource not found
            errorKey: NOT_FOUND
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 400
            message: Invalid request
            errorKey: INVALID_REQUEST
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 429
            message: Rate limit exceeded
            errorKey: RATE_LIMIT_EXCEEDED
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 401
            message: Invalid API key
            errorKey: INVALID_API_KEY
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
  requestBodies:
    ProfileMatchingBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              company_url:
                type: string
                format: uri
                description: Public `http(s)` company website used as profile context. Provide it or `target_audience`.
                example: https://acme.example
                maxLength: 500
              target_audience:
                type: string
                description: Free-form ideal-customer or target-audience description. Provide it or `company_url`.
                example: Enterprise marketing teams in North America
              page:
                type: integer
                minimum: 1
                default: 1
                description: One-based result page number.
                example: 1
              pageSize:
                type: integer
                minimum: 1
                maximum: 100
                default: 20
                description: Maximum records requested per page; defaults to `20` and cannot exceed `100`.
                example: 20
              autoRecommendTop3EventsEnabled:
                type: boolean
                description: Override synchronous top-three recommendation-reason generation for this request.
                example: true
              city:
                type: string
                description: Filter recommendations by city.
                example: Las Vegas
              region:
                type: string
                description: Filter recommendations by region or state.
                example: Nevada
              country:
                type: string
                description: Filter recommendations by country.
                example: United States
              category:
                type: array
                items:
                  type: string
                description: Filter by category labels. Arrays and comma-separated inputs are normalized.
                example:
                - Technology
              eventTypeIds:
                type: array
                items:
                  type: integer
                description: Filter by Lensmor event-type identifiers.
                example:
                - 1
              dateStartFrom:
                type: string
                format: date
                description: Inclusive lower bound for event start date in `YYYY-MM-DD` format.
                example: '2025-01-01'
              dateStartTo:
                type: string
                format: date
                description: Inclusive upper bound for event start date in `YYYY-MM-DD` format.
                example: '2025-12-31'
              future:
                type: integer
                description: Future-event flag used by the recommendation filter.
                example: 1
              attendeeCountMin:
                type: integer
                minimum: 0
                description: Minimum attendee count, inclusive.
                example: 500
              attendeeCountMax:
                type: integer
                minimum: 0
                description: Maximum attendee count, inclusive.
                example: 50000
              linkedin_url:
                type: string
                format: uri
                maxLength: 500
                description: Optional safe public LinkedIn profile URL used as additional profile context.
                example: https://www.linkedin.com/in/jane-doe
              company_description:
                type: string
                maxLength: 2000
                description: Optional company description used as additional profile-matching context.
                example: We help retailers connect with technology vendors through trade shows and events.
              industry:
                type: string
                maxLength: 255
                description: Optional company industry used as profile context.
                example: Retail Technology
              target_industry:
                type: array
                items:
                  type: string
                  maxLength: 255
                description: Optional target industries used to scope exhibitor recommendations.
                example:
                - Artificial Intelligence
                - Technology & Software
              planned_events:
                type: string
                maxLength: 500
                description: Optional free-text description of events the caller already plans to attend.
                example: NRF, Shoptalk, and regional retail trade shows
              target_management_level:
                type: array
                items:
                  type: string
                  maxLength: 100
                description: Optional management-level labels used for personnel matching.
                example:
                - C-Level
                - VP
              target_job_titles:
                type: array
                items:
                  type: string
                  maxLength: 255
                description: Optional job-title or function terms. The runtime normalizes the input and retains the first five non-empty values.
                example:
                - marketing
                - ecommerce
                - VP Marketing
              timeout_ms:
                type: integer
                minimum: 60000
                maximum: 3600000
                description: Optional synchronous processing timeout in milliseconds, from one minute to one hour.
                example: 900000
            anyOf:
            - required:
              - company_url
            - required:
              - target_audience
          example:
            company_url: https://acme.example
            page: 1
            pageSize: 20
            country: United States
            future: 1
      description: Provide company-profile context, pagination, and optional event filters for recommendation generation.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Business sk API key
      description: 'Send the full Business API key from Settings -> API Keys, for example `Authorization: Bearer sk_your_api_key`.'