> ## Documentation Index
> Fetch the complete documentation index at: https://api.lensmor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits and access

> Learn how Lensmor credits, locked event access, preview limits, unlock guidance, and credit-safe integration patterns work across the API.

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

| Operation                | Typical cost                        | Notes                                                                                                                                    |
| ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Event unlock             | `2000` credits                      | Unlocks full event access when contacts are available and the event is not already unlocked.                                             |
| Contact email unlock     | `15` credits per chargeable contact | Batch unlock creates an asynchronous task. Already unlocked contacts are not charged again.                                              |
| Exhibitor company search | `50` credits                        | `POST /external/exhibitors/search-by-company-name` finds exhibitor company records from a company name.                                  |
| Exhibitor event search   | `50` credits                        | `POST /external/exhibitors/search-events` reverse-lookups events from a company name.                                                    |
| LinkedIn activity unlock | No email-unlock charge              | `POST /external/personnel/unlock-linkedin-activity` unlocks or starts analysis for LinkedIn activity. It does not unlock contact emails. |

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](/api-reference/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:

<Steps>
  <Step title="Preview or validate the target">
    Show the event, company, or contact records the user is about to unlock or search.
  </Step>

  <Step title="Check current balance">
    Call `GET /external/credits/balance` and show the current total balance.
  </Step>

  <Step title="Show expected cost">
    Display the known cost from this page, endpoint docs, or `semantics.unlock`.
  </Step>

  <Step title="Execute the paid action">
    Call the unlock or reverse-lookup endpoint only after the user confirms.
  </Step>

  <Step title="Refresh state">
    Update balance, access state, and list results after the response.
  </Step>
</Steps>

For workflows that depend on access state, call [Actions precheck](/api-reference/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

<CardGroup cols={2}>
  <Card title="Credits balance" icon="coins" href="/api-reference/credits/balance">
    Check available subscription and gift credits.
  </Card>

  <Card title="Unlock event" icon="lock-keyhole-open" href="/api-reference/events/unlock">
    Unlock full event-scoped coverage.
  </Card>

  <Card title="Unlock contact emails" icon="mail-check" href="/api-reference/contacts/unlock">
    Start an asynchronous email unlock task.
  </Card>

  <Card title="Exhibitor event search" icon="search" href="/api-reference/exhibitors/search-events">
    Search events from a company name.
  </Card>
</CardGroup>