Find and unlock an event

Use this guide when your integration needs to move from discovery to base event coverage, registered Visitor access, or both. Event unlocks are intentionally explicit. Lensmor lets you preview exhibitor and personnel data first, then choose the access layer the user actually needs. Visitor records are registered event attendees obtained through organizer or data-provider partnerships and are available only for selected events.

Recommended workflow

Find candidate events

Search the event catalog, rank events, or apply profile matching to identify a shortlist.

Inspect the event

Fetch the event detail and confirm the event identity, date, venue, source URL, and available data counts.

Preview exhibitors or personnel

Call event-scoped list endpoints. If the event is locked, read the semantics object to understand preview limits.

Choose and precheck the access layer

Use base event unlock for exhibitor and personnel coverage, visitor unlock after base access, or full-access unlock for both layers. Precheck before each paid action.

1. Search events

curl "https://platform.lensmor.com/external/events/list?keyword=retail&page=1&pageSize=20" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"

For fit-based discovery, use Get event fit score, Rank events, or Apply recommended events.

2. Fetch event detail

curl "https://platform.lensmor.com/external/events/139574" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"

Confirm that the event is the one your team expects before unlocking. For example, check name, dateStart, dateEnd, venue, country, url, and any count fields returned by the API.

3. Preview event-scoped data

curl "https://platform.lensmor.com/external/personnel/list?event_id=139574&page=1&pageSize=20" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"

Locked events can return a response like this:

{
  "items": [
    {
      "id": "789",
      "fullName": "Jane Doe",
      "title": "VP of Partnerships",
      "companyName": "Example Retail Co",
      "sourceType": ["exhibitor", "social"],
      "email": null,
      "contactUnlockStatus": "locked"
    }
  ],
  "total": 120,
  "page": 1,
  "pageSize": 20,
  "hasMore": true,
  "semantics": {
    "accessMode": "preview",
    "previewLimit": 50,
    "counts": {
      "actualTotal": 120,
      "visibleTotal": 20,
      "remainingLockedCount": 100
    },
    "pageState": {
      "requestedPage": 1,
      "accessible": true,
      "maxAccessiblePage": 1
    },
    "unlock": {
      "requiredForMoreResults": true,
      "actionType": "unlock_event_personnel",
      "credits": 2000
    },
    "guidance": {
      "code": "preview_results_truncated",
      "message": "This event is locked. Unlock the event to access the remaining matching results."
    }
  }
}

Use semantics to decide whether to unlock base event coverage. semantics.accessMode does not describe the separate Visitor layer, so do not infer Visitor access from pagination or "full" base access alone.

4. Unlock base event access

curl -X POST "https://platform.lensmor.com/external/events/139574/unlock" \
  -H "Authorization: Bearer $LENSMOR_API_KEY" \
  -H "x-call-source: api"

The response tells you whether credits were used:

{
  "success": true,
  "alreadyUnlocked": false,
  "creditsUsed": 2000,
  "balanceAfter": {
    "subscriptionBalance": 0,
    "permanentBalance": 451021,
    "totalBalance": 451021,
    "unlimited": false
  },
  "event": {
    "id": "26855",
    "eventId": "26855",
    "name": "CES 2025"
  }
}

If alreadyUnlocked is true, the event was already available and creditsUsed is 0.

5. Add visitor access or unlock both layers

Visitor access is separate from base event access:

POST /external/events/:id/visitors/unlock costs 3000 credits and requires base event access, an active subscription, and registered Visitor data for the event.
POST /external/events/:id/full-access/unlock atomically charges only for missing layers: 2000 for base event access plus 3000 for visitor access.

Precheck the intended action before execution:

curl -X POST "https://platform.lensmor.com/external/actions/precheck" \
  -H "Authorization: Bearer $LENSMOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "unlock_event_full_access",
    "call_source": "api",
    "params": {
      "event_id": "139574"
    }
  }'

Continue only when allowed is true, show the returned credits to the user, and refresh the balance after execution. Read detail.visitor_data_available instead of inferring availability from the event category or list counts. If full-access precheck returns no_contacts_available because Visitor data is unavailable, use base event unlock when exhibitor and personnel coverage is still needed.

Common mistakes

Unlocking before checking preview results. Preview first to verify the event has relevant records.
Using only the event name as your local key. Store id or eventId so follow-up calls are deterministic.
Treating 402 Payment Required as a generic failure. It usually means your integration needs to pause, notify the user, or ask them to add credits.
Ignoring semantics. It tells you whether a list is in preview mode or has full access.
Calling visitor unlock before base event access. Precheck returns state_conflict in that state.
Treating base event access and visitor access as the same layer. They have separate access records and credit costs.
Treating Social Signals as official registration evidence. Only the Visitor label represents registered attendees in the current source taxonomy.

List events

Browse events with filters and pagination.

Unlock event

Spend credits to access full exhibitor and personnel coverage.

Unlock visitor access

Add visitor records after base event access.

Unlock full access

Atomically unlock missing base and visitor layers.

List event exhibitors

Fetch exhibitors for a selected event.

List event personnel

Fetch people associated with a selected event.

Attendee source types

Map product attendee labels to API sourceType values.

Introduction

Guides

Concepts

Find and unlock an event

Recommended workflow

1. Search events

2. Fetch event detail

3. Preview event-scoped data

4. Unlock base event access

5. Add visitor access or unlock both layers

Common mistakes

List events

Unlock event

Unlock visitor access

Unlock full access

List event exhibitors

List event personnel

Attendee source types

​Recommended workflow

​1. Search events

​2. Fetch event detail

​3. Preview event-scoped data

​4. Unlock base event access

​5. Add visitor access or unlock both layers

​Common mistakes

​Related endpoints

List events

Unlock event

Unlock visitor access

Unlock full access

List event exhibitors

List event personnel

Attendee source types

Recommended workflow

1. Search events

2. Fetch event detail

3. Preview event-scoped data

4. Unlock base event access

5. Add visitor access or unlock both layers

Common mistakes

Related endpoints