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

# Quickstart

> Make your first Lensmor API request, search events, review exhibitors and personnel, handle locked data, and prepare a production integration.

Make your first Lensmor API request and understand the core objects you will use in most integrations.

The Lensmor API is designed around a typical event-intelligence workflow:

1. Start with a company profile, buyer profile, keyword, or target market.
2. Discover relevant trade shows and event records.
3. Inspect exhibitors and people connected to those events.
4. Unlock full access or contact emails only when the data is actionable.

## Before you begin

You need a valid user API key and an environment capable of sending HTTPS requests.

Create an account at [app.lensmor.com](https://app.lensmor.com), upgrade to a paid subscription plan, then create an API key from **Settings → API Keys**.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export LENSMOR_API_KEY="uak_your_api_key"
```

<Note>
  Lensmor API keys use the `uak_` prefix. Older `sk_` examples are historical and should not be used for new integrations.
</Note>

## 1. Check your credit balance

Credit-aware workflows return clear billing semantics, but most integrations should still check balance before running unlock operations.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://platform.lensmor.com/external/credits/balance" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"
```

The response includes subscription credits, gift credits, the total balance, and the next reset timestamp when available. This is the same credit pool used by the Lensmor SaaS app.

## Choose the right starting point

| User goal                                                  | First endpoint                                                           | Credit note                                              |
| ---------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------- |
| Search for events by keyword, country, city, or date       | `GET /external/events/list`                                              | Read-only                                                |
| Rank events from a company profile or audience description | `POST /external/profile-matching/actions/apply-recommended-events/paged` | Read-only                                                |
| Browse companies inside a selected event                   | `GET /external/exhibitors/list`                                          | Read-only unless the user unlocks event access           |
| Browse people inside a selected event                      | `GET /external/personnel/list`                                           | Read-only unless the user unlocks event access or emails |
| Find exhibitor records from a company name                 | `POST /external/exhibitors/search-by-company-name`                       | Can consume `50` credits                                 |
| Find events associated with a company name                 | `POST /external/exhibitors/search-events`                                | Can consume `50` credits                                 |
| Unlock selected contact emails                             | `POST /external/contacts/unlock`                                         | Can consume `15` credits per chargeable contact          |

## 2. Search the event catalog

Use the events list endpoint when you need a broad catalog query.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://platform.lensmor.com/external/events/list?keyword=retail&country=United%20States&page=1&pageSize=20" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"
```

The event list is paginated. Use the `eventId` field from responses when calling other endpoints:

* `id` and `eventId` currently return the same value for all events.
* Use `eventId` when passing to endpoints that accept `event_id`.
* Many event-scoped endpoints accept either value.

## 3. Inspect a specific event

After selecting an event, fetch the event detail record.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://platform.lensmor.com/external/events/139574" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"
```

Use the detail response to confirm event dates, venue, geography, source URL, and available count fields before deciding whether to explore exhibitors or personnel.

## 4. Fetch exhibitors or personnel

Event-scoped lists may return preview results if the event is locked.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://platform.lensmor.com/external/exhibitors/list?event_id=139574&page=1&pageSize=20" \
  -H "Authorization: Bearer $LENSMOR_API_KEY"
```

When the response contains `semantics.accessMode: "preview"`, read `semantics.counts.visibleTotal` and `semantics.unlock.requiredForMoreResults` before calling an unlock endpoint. These fields tell you whether more data is available and which action unlocks it.

## 5. Handle errors and limits

Production integrations should handle these responses explicitly:

* `401 Unauthorized` means the API key is missing or invalid.
* `402 Payment Required` means the requested credit-consuming workflow cannot proceed with the current balance or access state.
* `404 Not Found` means the requested event, exhibitor, person, or task does not exist.
* `429 Too Many Requests` means your integration should back off and retry later.

See [Error conventions](/concepts/errors), [Credits and access](/concepts/credits-and-access), and [Rate limits](/concepts/rate-limits) for shared behavior across endpoints.

## Next steps

<CardGroup cols={2}>
  <Card title="Find and unlock an event" icon="lock-keyhole-open" href="/guides/find-and-unlock-event">
    Learn how preview access works and when to spend credits on full event coverage.
  </Card>

  <Card title="Unlock contact emails" icon="mail-check" href="/guides/unlock-contact-emails">
    Start an email unlock task and poll until the result is ready.
  </Card>
</CardGroup>