Skip to main content
Use this checklist before putting a Lensmor API integration in front of customers or internal sales teams. Production integrations should handle authentication, pagination, credit-aware actions, asynchronous jobs, and rate limits explicitly. This keeps workflows predictable and prevents accidental credit spend.

​
Request checklist

1

Send authentication on every request

Include Authorization: Bearer uak_your_api_key. Treat 401 Unauthorized as a key or account configuration issue.
2

Use pagination consistently

Always pass page and pageSize for list endpoints. Do not assume all records fit in the first response.
3

Check credits before paid actions

Use GET /external/credits/balance before event unlocks, email unlocks, or exhibitor event searches.
4

Precheck when the next action depends on access state

Use POST /external/actions/precheck before workflows where you need to know whether an action is allowed, whether it should charge credits, or which unlock path applies.
5

Make asynchronous jobs resumable

Store task_id from contact unlock responses so polling can continue after page refreshes, worker restarts, or network failures.
6

Handle item-level async outcomes

Treat a terminal task as complete for the job, then inspect each item result before counting delivered emails or failed contacts.
7

Back off on rate limits

Respect Retry-After for 429 Too Many Requests and use X-RateLimit-* headers for proactive throttling.

​
Error handling matrix

StatusMeaningRecommended behavior
400 Bad RequestRequest shape or validation failed.Fix client-side input and show a validation message.
401 UnauthorizedAPI key is missing, invalid, revoked, or not visible to the caller.Ask the user to reconnect or rotate the key.
402 Payment RequiredThe operation needs credits or access that is not currently available.Pause the workflow, show credit context, and let the user decide.
404 Not FoundThe requested event, exhibitor, person, or task was not found.Re-check stored identifiers and avoid retry loops.
409 ConflictThe request conflicts with current profile, task, or workflow state.Refresh current state before retrying.
429 Too Many RequestsRate limit exceeded.Retry only after Retry-After; use exponential backoff.

​
Credit-safe UI pattern

For credit-consuming actions, use a two-step confirmation pattern:
  1. Show what the user is about to unlock or search.
  2. Show the expected credit cost when known.
  3. Check current balance.
  4. Ask the user to confirm.
  5. Execute the API call.
  6. Refresh balance and result state.
  7. Reconcile final billing against the post-action balance and task or endpoint response.
This pattern is especially important for Unlock event, Unlock contact emails, Exhibitor company search, and Exhibitor event search.

​
Credit-consuming actions

ActionEndpointCurrent behavior
Event unlockPOST /external/events/:id/unlockCharges 2000 credits when the event was not already unlocked. Repeating the same unlock is idempotent and returns creditsUsed: 0.
Contact email unlockPOST /external/contacts/unlockStarts an async task and charges 15 credits per chargeable contact. A completed task can contain mixed item-level outcomes.
Exhibitor company searchPOST /external/exhibitors/search-by-company-nameCharges 50 credits per successful company search attempt.
Exhibitor event searchPOST /external/exhibitors/search-eventsCharges 50 credits per successful search attempt.
Read-only list, profile, search, and precheck endpoints do not spend credits by themselves.

​
Rate-limit friendly polling

For contact unlock tasks, avoid tight polling loops. 
Create task -> wait 3s -> poll -> wait 5s -> poll -> wait 10s -> poll
Stop polling when the task is completed or failed. If the user leaves the page, store the task ID and resume later. For completed contact unlock tasks, inspect item-level results before updating CRM fields. Count only records that include an unlocked email, surface item-level failures separately, and refresh credit balance after terminal states when users need a spend audit.

​
Logging and support

Log enough context to investigate issues without storing sensitive data:
  • endpoint path and method
  • response status
  • traceId from error responses when available
  • X-Request-ID if your client sends one
  • task ID for asynchronous jobs
  • event or personnel identifiers involved in the workflow
Do not log API keys or unlocked email addresses in plaintext application logs.

Authentication

How to authenticate API requests.

Error conventions

Shared error response shape and tracing fields.

Pagination conventions

Standard pagination fields and page-size limits.

Rate limits

Headers, retry behavior, and integration guidance.