Credits and access

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: 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 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.

​

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