Credits and access

Some Lensmor API operations are credit-aware. Most read-only discovery endpoints are available with a valid API key, while unlock and paid company-name 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.
• addonBalance — credits from active one-time add-on purchases.
• giftBalance — non-expiring gift credits.
• totalBalance — total currently available credits.
• resetAt — the earliest active subscription credit expiration timestamp in milliseconds, or null.
• addonExpireAt — the latest active add-on 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

Base event unlock grants full access to event-scoped exhibitor and personnel results. Visitor access is a separate registered-attendee data layer, sourced through organizer or data-provider partnerships, that can be unlocked after base event access or together through the full-access endpoint. semantics.accessMode on an event-scoped list describes base event access only. It does not prove that Visitor access is unlocked. Use the Visitor or full-access action precheck when registered Visitor records are required.

​

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: 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 base event unlock, visitor unlock, full event access, contact unlock, phone unlock, exhibitor company search, 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

​

Related endpoints