Quickstart

Make your first Lensmor API request, search events, review exhibitors and personnel, handle locked data, and prepare a production integration.

Make your first Lensmor API request and understand the core objects you will use in most integrations.

The Lensmor API is designed around a typical event-intelligence workflow:

1. Start with a company profile, buyer profile, keyword, or target market.
2. Discover relevant trade shows and event records.
3. Inspect exhibitors and people connected to those events.
4. Unlock full access or contact emails only when the data is actionable.

Before you begin

You need a valid user API key and an environment capable of sending HTTPS requests.

Create an account at app.lensmor.com, upgrade to a paid subscription plan, then create an API key from Settings → API Keys.

export LENSMOR_API_KEY="uak_your_api_key"

Lensmor API keys use the uak_ prefix. Older sk_ examples are historical and should not be used for new integrations.

1. Check your credit balance

Credit-aware workflows return clear billing semantics, but most integrations should still check balance before running unlock operations.

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

The response includes subscription credits, gift credits, the total balance, and the next reset timestamp when available. This is the same credit pool used by the Lensmor SaaS app.

Choose the right starting point

User goal	First endpoint	Credit note
Search for events by keyword, country, city, or date	GET /external/events/list	Read-only
Rank events from a company profile or audience description	POST /external/profile-matching/actions/apply-recommended-events/paged	Read-only
Browse companies inside a selected event	GET /external/exhibitors/list	Read-only unless the user unlocks event access
Browse people inside a selected event	GET /external/personnel/list	Read-only unless the user unlocks event access or emails
Find exhibitor records from a company name	POST /external/exhibitors/search-by-company-name	Can consume 50 credits
Find events associated with a company name	POST /external/exhibitors/search-events	Can consume 50 credits
Unlock selected contact emails	POST /external/contacts/unlock	Can consume 15 credits per chargeable contact

2. Search the event catalog

Use the events list endpoint when you need a broad catalog query.

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

The event list is paginated. Use the eventId field from responses when calling other endpoints:

• id and eventId currently return the same value for all events.
• Use eventId when passing to endpoints that accept event_id.
• Many event-scoped endpoints accept either value.

3. Inspect a specific event

After selecting an event, fetch the event detail record.

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

Use the detail response to confirm event dates, venue, geography, source URL, and available count fields before deciding whether to explore exhibitors or personnel.

4. Fetch exhibitors or personnel

Event-scoped lists may return preview results if the event is locked.

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

When the response contains semantics.accessMode: "preview", read semantics.counts.visibleTotal and semantics.unlock.requiredForMoreResults before calling an unlock endpoint. These fields tell you whether more data is available and which action unlocks it.

5. Handle errors and limits

Production integrations should handle these responses explicitly:

• 401 Unauthorized means the API key is missing or invalid.
• 402 Payment Required means the requested credit-consuming workflow cannot proceed with the current balance or access state.
• 404 Not Found means the requested event, exhibitor, person, or task does not exist.
• 429 Too Many Requests means your integration should back off and retry later.

See Error conventions, Credits and access, and Rate limits for shared behavior across endpoints.

Next steps

Find and unlock an event

Learn how preview access works and when to spend credits on full event coverage.

Unlock contact emails

Start an email unlock task and poll until the result is ready.