Skip to main content
Some Lensmor API operations are credit-aware. Read-only discovery endpoints are available with a valid API key, while unlock and reverse-lookup workflows may consume credits. API credits are shared with the Lensmor SaaS app. The API key belongs to a subscribed Lensmor user account, and API usage draws from the same credit pool as product usage in the app.

​
Credit balance

Use GET /external/credits/balance to inspect the API key owner’s current balance before running credit-consuming workflows. The balance is split into:
  • subscriptionBalance — credits from the active subscription period.
  • giftBalance — non-expiring gift credits.
  • totalBalance — total currently available credits.
  • resetAt — the earliest active subscription credit expiration timestamp in milliseconds, or null.

​
Preview and full access

Event-scoped exhibitor and personnel lists can return preview results before the event is unlocked. When an event is locked, list responses may include semantics metadata describing:
  • whether access is preview or full
  • how many matching records are visible
  • whether more results require unlocking the event
  • which unlock action and credit amount applies
Unlocking an event grants full access to event-scoped exhibitor and personnel results for that event.

​
Credit-consuming operations

Prices can change by plan or product policy. Treat the API response and your commercial agreement as the source of truth for billing.

​
Final billing reconciliation

Precheck responses, endpoint docs, and UI estimates help users decide whether to proceed, but they are not final billing records. After a paid action, refresh Credits balance and the affected resource. This is especially important when:
  • an event or contact was already unlocked
  • an asynchronous contact unlock task completes with mixed item-level outcomes
  • a submitted contact is ineligible, failed, or does not produce an email
  • a workflow is retried after a timeout
For contact unlocks, count delivered enrichment only when an item-level result is unlocked and contains an email. Keep failed or unresolved items visible separately from successful unlocks.

​
Credit-safe integration pattern

Use a confirmation step for operations that can spend credits:
1

Preview or validate the target

Show the event, company, or contact records the user is about to unlock or search.
2

Check current balance

Call GET /external/credits/balance and show the current total balance.
3

Show expected cost

Display the known cost from this page, endpoint docs, or semantics.unlock.
4

Execute the paid action

Call the unlock or reverse-lookup endpoint only after the user confirms.
5

Refresh state

Update balance, access state, and list results after the response.
For workflows that depend on access state, call Actions precheck before execution. Precheck is read-only and returns whether the action is allowed, whether it should charge credits, and the expected credit amount when known.

​
Headers

Some credit-consuming or task-producing routes accept x-call-source. Supported values are:
  • api — default customer API usage.
  • agent — agent-driven usage.
If omitted or unrecognized, the API records the call as api. This header is currently used by event unlock, contact unlock, phone unlock, exhibitor event search, LinkedIn activity unlock, and outreach message generation workflows.

​
Handling 402 Payment Required

402 Payment Required means the API understood the request but the current account cannot complete the credit-consuming action. Recommended behavior:
  • stop automatic retries
  • show the credit requirement or insufficient-balance message
  • let the user choose whether to add credits, change scope, or cancel
  • avoid creating duplicate tasks for the same unlock intent

Credits balance

Check available subscription and gift credits.

Unlock event

Unlock full event-scoped coverage.

Unlock contact emails

Start an asynchronous email unlock task.

Exhibitor event search

Search events from a company name.