Publish API contract documentation for v0.24.0

README.md

@@ -80,7 +80,7 @@ pnpm dlx mintlify dev
 
 ## Changelog
 
-See `changelog.mdx` for versioned documentation updates. The current documentation version is `v0.23.1`.
+See `changelog.mdx` for versioned documentation updates. The current documentation version is `v0.24.0`.
 
 ---
 

api-reference-backup/actions/precheck.mdx

@@ -20,7 +20,7 @@ See [Authentication](/authentication)
 ## Request body
 | Name | Required | Type | Notes |
 | --- | --- | --- | --- |
-| `action_type` | Yes | string | Supported values include `query_event_personnel`, `unlock_event_contacts`, `unlock_contact_emails`, `search_exhibitor_events`, and `others`. |
+| `action_type` | Yes | string | Supported customer actions include `query_event_personnel`, `unlock_event_contacts`, `unlock_event_visitors`, `unlock_event_full_access`, `unlock_contact_emails`, `unlock_contact_phones`, `search_exhibitor_events`, and `others`. |
 | `params` | Yes | object | Action-specific inputs, such as `{ "event_id": "26855" }`. |
 | `call_source` | No | string | Source label such as `api` or `agent`. |
 | `locale` | No | string | Optional locale, such as `en-US`. |
@@ -74,8 +74,33 @@ curl -X POST "https://platform.lensmor.com/external/actions/precheck" \
 | `biz_code` | Billing/business code used by the execution path when applicable. |
 | `detail` | Action-specific metadata. Shape varies by `action_type`. |
 
+## Visitor unlock example
+
+```json
+{
+  "ok": true,
+  "action_type": "unlock_event_visitors",
+  "allowed": true,
+  "should_charge": true,
+  "credits": 3000,
+  "reason_code": "ok",
+  "biz_code": "Visitor Unlock - API",
+  "detail": {
+    "event_id": "26855",
+    "event_unlocked": true,
+    "visitor_unlocked": false,
+    "visitor_data_available": true,
+    "visitor_access_credits": 3000,
+    "available_balance": 8000
+  }
+}
+```
+
 ## Notes
 - Precheck is read-only. It does not unlock records, create tasks, or consume credits.
 - `query_event_personnel` is useful before calling [Personnel list](/api-reference/personnel/list-event-personnel).
+- `unlock_event_visitors` requires base event access first. It can report `3000` expected credits, `state_conflict` when the event is still locked, `no_contacts_available` when visitor data is unavailable, or `forbidden` when the account has no active subscription.
+- `unlock_event_full_access` calculates only the missing access layers: `2000` for base event access plus `3000` for visitor access. It can therefore report `0`, `2000`, `3000`, or `5000` credits.
+- For full-access precheck, `detail` includes `event_unlocked`, `visitor_unlocked`, `visitor_data_available`, `event_access_credits`, `visitor_access_credits`, and `full_access_credits`.
 - Once a list endpoint returns `semantics`, treat that response as the authoritative explanation for the actual list result.
 - Precheck decisions can change as credits, event access, or underlying data changes. Recheck before executing a paid action.

api-reference-backup/contacts/search.mdx

@@ -62,11 +62,14 @@ curl "https://platform.lensmor.com/external/contacts/search?company_name=Acme&pe
       "seniorityLevel": "vp",
       "linkedinUrl": "https://linkedin.com/in/jane",
       "companyName": "Acme",
-      "sourceType": "exhibitor",
+      "sourceType": ["exhibitor"],
       "email": null,
+      "phone": null,
       "contactUnlockStatus": "locked",
+      "phoneUnlockStatus": null,
       "linkedinActivity": null,
-      "linkedinActivityStatus": null
+      "linkedinActivityStatus": null,
+      "eventCount": 3
     }
   ],
   "total": 1,
@@ -87,9 +90,12 @@ curl "https://platform.lensmor.com/external/contacts/search?company_name=Acme&pe
 | `department`, `seniorityLevel` | Normalized role metadata when available. |
 | `linkedinUrl` | LinkedIn profile URL when available. |
 | `companyName` | Matched company name. |
-| `sourceType` | Source context for the contact record. |
+| `sourceType` | Normalized source labels for the contact record. Values can include `exhibitor`, `social`, and `visitors`. |
 | `email` | Email if already unlocked for the caller; otherwise `null`. |
+| `phone` | Phone number if already unlocked for the caller; otherwise `null`. |
 | `contactUnlockStatus` | Contact access state for this API key owner. |
+| `phoneUnlockStatus` | `ready`, `processing`, `failed`, or `null`. |
+| `eventCount` | Number of associated events when available. |
 | `linkedinActivity` | Always `null` on this endpoint. Only [Personnel list](/api-reference/personnel/list-event-personnel) populates LinkedIn activity data. |
 | `linkedinActivityStatus` | Always `null` on this endpoint. |
 | `total`, `page`, `pageSize`, `totalPages`, `hasMore` | Pagination metadata. |

api-reference-backup/contacts/unlock-phone.mdx

@@ -1,36 +1,43 @@
 ---
 title: "Unlock contact phone numbers"
-description: "Start an asynchronous phone number unlock workflow for one or more personnel records in a Lensmor event."
+description: "Submit a phone unlock request and receive either an accepted asynchronous task or an immediate no-work success result."
 openapi: "openapi.json POST /external/contacts/unlock-phone"
 ---
 
-Start an asynchronous job to unlock phone numbers for one or more personnel records.
+Submit a request to unlock phone numbers for one or more personnel records. Chargeable work creates an asynchronous task; a request with no chargeable work completes immediately without a task.
 
 Use this endpoint after finding contacts from personnel or contact search results when you need direct phone numbers rather than email addresses.
 
 ## When to use this endpoint
 
 Use `POST /external/contacts/unlock-phone` when your integration needs verified phone numbers for outbound calling or SMS workflows.
 
-This endpoint is asynchronous. The create call returns a task identifier; poll [Get phone unlock task](/api-reference/contacts/get-phone-unlock-task) until the job reaches a terminal state.
+When the response has `status: "accepted"`, the create call returns a task identifier. Poll [Get phone unlock task](/api-reference/contacts/get-phone-unlock-task) until that job reaches a terminal state. When the response has `status: "success"`, no task was created and there is nothing to poll.
 
 <Note>
   Phone unlock is a separate workflow from email unlock. Use [Unlock contact emails](/api-reference/contacts/unlock-contact-emails) for email addresses.
 </Note>
 
 <Warning>
-  A `201 Created` response means the task was accepted. Always inspect item-level results before counting a contact phone as delivered.
+  A `201 Created` response means the request was processed. `status: "accepted"` means a task was created; `status: "success"` means there was no chargeable work to enqueue. Neither state guarantees that every submitted personnel record will return a phone number.
 </Warning>
 
 ## Credit behavior
 
-Phone unlock costs credits per chargeable contact.
+Phone unlock costs `150` credits per chargeable contact.
 
 - Already unlocked contacts are not charged again.
 - Insufficient balance returns `402 Payment Required`.
 - The API rejects batches larger than 100 personnel IDs.
 
+If there is no chargeable work to enqueue, the endpoint can return `status: "success"` without `task_id` or `job_id`. The response can also include `skipped_personnel_ids` and `skipped_detail` so the caller can explain invalid, missing, unlinked, already unlocked, or currently unlocking records.
+
+## Response handling
+
+- For `status: "accepted"`, use `task_id` (or its `job_id` alias) to poll the phone unlock task.
+- For `status: "success"`, do not poll. Inspect `skipped_personnel_ids` and `skipped_detail` to explain why no task was needed.
+
 ## Notes
-- This endpoint creates an asynchronous unlock job. Poll [Get phone unlock task](/api-reference/contacts/get-phone-unlock-task) with `task_id`.
+- Only poll [Get phone unlock task](/api-reference/contacts/get-phone-unlock-task) when `status` is `accepted` and `task_id` is present.
 - Do not create duplicate unlock tasks while a prior task is still pending or processing.
 - See [Credits and access](/concepts/credits-and-access) for shared credit behavior.

api-reference-backup/contacts/unlock.mdx

@@ -19,7 +19,7 @@ This endpoint is intentionally asynchronous because email unlock can involve mul
 </Note>
 
 <Warning>
-  A `201 Created` response means the unlock task was accepted. It does not guarantee that every submitted personnel record will return an email. Always inspect item-level task results before counting a contact as enriched.
+  A `201 Created` response means the request was processed. `status: "accepted"` means a task was created; `status: "success"` means there was no chargeable work to enqueue. Neither state guarantees that every submitted personnel record will return an email.
 </Warning>
 
 ## Endpoint
@@ -64,9 +64,11 @@ curl -X POST "https://platform.lensmor.com/external/contacts/unlock" \
 
 | Field | Description |
 | --- | --- |
-| `status` | Initial task acceptance state. Usually `accepted` when the task was created. |
-| `task_id` | Identifier used to poll task status. Store this value. |
-| `job_id` | Alias for the background job identifier. It currently matches `task_id`. |
+| `status` | `accepted` when an asynchronous task was created, or `success` when there was no chargeable work to enqueue. |
+| `task_id` | Identifier used to poll task status. Present only when `status` is `accepted`. |
+| `job_id` | Alias for `task_id`. Present only when `status` is `accepted`. |
+| `skipped_personnel_ids` | Personnel IDs omitted from the unlock task, when applicable. |
+| `skipped_detail` | Optional grouped reasons for skipped IDs, including invalid, missing, unlinked, already unlocked, or currently unlocking records. |
 
 ## Polling pattern
 

api-reference-backup/credits/balance.mdx

@@ -6,13 +6,15 @@ openapi: "openapi.json GET /external/credits/balance"
 
 Get the current credit balance for the API key owner.
 
-Use this endpoint before credit-consuming workflows such as event unlock, contact email unlock, or exhibitor event search.
+Use this endpoint before credit-consuming workflows such as event unlock, visitor unlock, contact email unlock, or exhibitor event search.
 
 ## When to use this endpoint
 
 Call `GET /external/credits/balance` before any workflow that can spend credits:
 
 - [Unlock event](/api-reference/events/unlock-event-access)
+- [Unlock event visitor access](/api-reference/events/unlock-event-visitor-access)
+- [Unlock full event access](/api-reference/events/unlock-full-event-access)
 - [Unlock contact emails](/api-reference/contacts/unlock-contact-emails)
 - [Search exhibitor events](/api-reference/exhibitors/search-events-by-exhibitor-company-name)
 
@@ -36,10 +38,13 @@ curl "https://platform.lensmor.com/external/credits/balance" \
 ## Response example
 ```json
 {
-  "totalAmount": 35050,
-  "totalBalance": 30050,
+  "totalAmount": 45050,
+  "totalBalance": 38050,
   "subscriptionAmount": 35000,
   "subscriptionBalance": 30000,
+  "addonAmount": 10000,
+  "addonBalance": 8000,
+  "addonExpireAt": 1784851200000,
   "giftAmount": 50,
   "giftBalance": 50,
   "resetAt": 1714521600000
@@ -50,26 +55,29 @@ curl "https://platform.lensmor.com/external/credits/balance" \
 
 | Field | Description |
 | --- | --- |
-| `totalAmount` | Total credits ever granted across active subscription and gift buckets. |
+| `totalAmount` | Total credits granted across active subscription, add-on, and gift buckets. |
 | `totalBalance` | Total currently available credits. Use this for simple "can this user spend credits?" checks. |
 | `subscriptionAmount` | Subscription credits granted for the active credit period. |
-| `subscriptionBalance` | Remaining subscription credits. These are consumed before gift credits. |
+| `subscriptionBalance` | Remaining subscription credits. |
+| `addonAmount` | Add-on credits granted in currently active add-on buckets. |
+| `addonBalance` | Remaining add-on credits. |
+| `addonExpireAt` | Latest active add-on credit expiration timestamp in milliseconds, or `null`. |
 | `giftAmount` | Gift credits granted to the user. |
 | `giftBalance` | Remaining gift credits. |
 | `resetAt` | Earliest active subscription credit expiration timestamp in milliseconds, or `null`. |
 
 ## Integration guidance
 
 - Use `totalBalance` for high-level balance checks.
-- Use bucket-specific fields when your UI needs to explain subscription vs. gift credit usage.
+- Use bucket-specific fields when your UI needs to explain subscription, add-on, and gift credit usage.
 - Refresh the balance after credit-consuming operations because `balanceAfter` may differ from a previously cached value.
-- Treat `resetAt` as nullable. Some accounts may only have gift credits or no active subscription credit expiration.
+- Treat `resetAt` and `addonExpireAt` as nullable. Some accounts may not have an active expiring bucket of that type.
 
 ## Error responses
 - `401 Unauthorized`
 - `429 Too Many Requests`
 
 ## Notes
 - `resetAt` is a timestamp in milliseconds for the earliest active subscription credit expiration, or `null`.
-- Subscription credits are consumed before gift credits.
+- `addonExpireAt` is a timestamp in milliseconds for the latest active add-on credit expiration, or `null`.
 - See [Credits and access](/concepts/credits-and-access) for shared credit behavior.

api-reference-backup/events/brief.mdx

@@ -51,8 +51,9 @@ curl "https://platform.lensmor.com/external/events/brief?event_id=139574" \
     "region": "NY",
     "country": "United States",
     "exhibitorCount": 950,
+    "sponsorMatchStarred": 0,
     "image": null,
-    "dataSource": "database"
+    "dataSource": "Lensmor"
   },
   "summary": {
     "attendeeCount": 40000,

api-reference-backup/events/detail.mdx

@@ -61,6 +61,7 @@ curl "https://platform.lensmor.com/external/events/139574" \
     "priceLower": "0",
     "priceUpper": "0",
     "eventType": "In-person",
+    "sponsorMatchStarred": 0,
     "categories": [
       {
         "id": 11,
@@ -107,7 +108,9 @@ curl "https://platform.lensmor.com/external/events/139574" \
 | `priceLower`, `priceUpper` | Price range as string values (e.g. `"1295"`) or `null`. |
 | `eventType`, `eventTypes`, `categories`, `topics`, `topicsCount` | Classification metadata. `categories` is an array of objects with `id`, `code`, `name`, `description`, `confidence` fields. |
 | `verified`, `future`, `historic`, `historicEvent` | Status flags and historical relationship metadata. |
-| `image`, `dataSource` | Media and source metadata. |
+| `sponsorMatchStarred` | Sponsor Match starred state (`0` or `1`). |
+| `image` | Event image URL when available. |
+| `dataSource` | Always `Lensmor` for public event records. |
 
 ## Count fields
 
@@ -128,6 +131,6 @@ When you need current coverage numbers, call the event-scoped list endpoint and
 - For event identifiers, see [Identifiers](/concepts/identifiers). In the current API version, `id` and `eventId` return the same value.
 - Some fields can be `null` when the underlying source does not provide that data.
 - String-typed numeric fields (`latitude`, `longitude`, `priceLower`, `priceUpper`) require client-side parsing when used for calculations.
-- `dataSource` indicates the data origin (e.g. `"Lensmor"`, `"local_import"`). Do not hard-code checks against specific values.
+- `dataSource` is always `"Lensmor"` for public event records.
 - `categories` is an array of objects. Each object contains `id` (integer), `code` (string), `name` (string), `description` (string or null), and `confidence` (string).
 - This endpoint does not unlock event-scoped exhibitor or personnel access by itself.

api-reference-backup/events/fit-score.mdx

@@ -53,8 +53,9 @@ curl -X POST "https://platform.lensmor.com/external/events/fit-score" \
     "region": "NY",
     "country": "United States",
     "exhibitorCount": 950,
+    "sponsorMatchStarred": 0,
     "image": null,
-    "dataSource": "database"
+    "dataSource": "Lensmor"
   },
   "score": 8.1,
   "recommendation": "recommended",

api-reference-backup/events/list.mdx

@@ -81,6 +81,7 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le
       "region": "Nevada",
       "country": "United States",
       "exhibitorCount": 3259,
+      "sponsorMatchStarred": 0,
       "image": "https://example.com/ces-image.png",
       "dataSource": "Lensmor"
     }
@@ -107,7 +108,8 @@ curl "https://platform.lensmor.com/external/events/list?event_type=conference_le
 | `dateStart`, `dateEnd` | Event date range. |
 | `venue`, `city`, `region`, `country` | Location metadata. |
 | `exhibitorCount` | Known exhibitor count when available. |
-| `dataSource` | Source category for the returned record (e.g. `"Lensmor"`, `"local_import"`). Do not hard-code checks against specific values. |
+| `sponsorMatchStarred` | Sponsor Match starred state (`0` or `1`). |
+| `dataSource` | Always `Lensmor` for public event records. |
 | `total`, `page`, `pageSize`, `totalPages`, `hasMore` | Pagination metadata. |
 
 ## Error responses