Refresh API contract documentation for v0.23.2

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.23.2`.
 
 ---
 

api-reference-backup/contacts/search.mdx

@@ -64,9 +64,12 @@ curl "https://platform.lensmor.com/external/contacts/search?company_name=Acme&pe
       "companyName": "Acme",
       "sourceType": "exhibitor",
       "email": null,
+      "phone": null,
       "contactUnlockStatus": "locked",
+      "phoneUnlockStatus": null,
       "linkedinActivity": null,
-      "linkedinActivityStatus": null
+      "linkedinActivityStatus": null,
+      "eventCount": 3
     }
   ],
   "total": 1,
@@ -89,7 +92,10 @@ curl "https://platform.lensmor.com/external/contacts/search?company_name=Acme&pe
 | `companyName` | Matched company name. |
 | `sourceType` | Source context for the contact record. |
 | `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/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

api-reference-backup/exhibitors/events.mdx

@@ -54,8 +54,9 @@ curl "https://platform.lensmor.com/external/exhibitors/events?exhibitor_id=456&p
       "region": "NY",
       "country": "United States",
       "exhibitorCount": 950,
+      "sponsorMatchStarred": 0,
       "image": null,
-      "dataSource": "database"
+      "dataSource": "Lensmor"
     }
   ],
   "total": 12,
@@ -76,7 +77,9 @@ curl "https://platform.lensmor.com/external/exhibitors/events?exhibitor_id=456&p
 | `dateStart`, `dateEnd` | Event date range. |
 | `venue`, `city`, `region`, `country` | Location metadata. |
 | `exhibitorCount` | Known exhibitor count when available. |
-| `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. |
 | `total`, `page`, `pageSize`, `totalPages`, `hasMore` | Pagination metadata. |
 
 ## Error responses

api-reference-backup/exhibitors/search-by-company-name.mdx

@@ -21,7 +21,7 @@ Choose this endpoint when:
 Use [Exhibitor event search](/api-reference/exhibitors/search-events-by-exhibitor-company-name) instead when the desired output is events related to a company name.
 
 <Warning>
-  This endpoint consumes `50` credits per successful search attempt. Check [Credits balance](/api-reference/credits/get-credits-balance) and confirm with the user before calling it in a credit-safe workflow.
+  This endpoint consumes `50` credits only when the response contains at least one exhibitor. An empty result does not consume credits. Check [Credits balance](/api-reference/credits/get-credits-balance) and confirm with the user before calling it in a credit-safe workflow.
 </Warning>
 
 ## Endpoint
@@ -40,11 +40,17 @@ See [Authentication](/authentication)
 | `page` | No | integer | Defaults to `1`. |
 | `pageSize` | No | integer | Defaults to `20`; maximum `100`. |
 
+## Headers
+| Name | Required | Type | Notes |
+| --- | --- | --- | --- |
+| `x-call-source` | No | string | Optional usage source. Use `api` or `agent`; defaults to `api`. |
+
 ## Request example
 ```bash
 curl -X POST "https://platform.lensmor.com/external/exhibitors/search-by-company-name" \
   -H "Authorization: Bearer $LENSMOR_API_KEY" \
   -H "Content-Type: application/json" \
+  -H "x-call-source: api" \
   -d '{"company_name":"Acme","page":1,"pageSize":20}'
 ```
 
@@ -104,7 +110,7 @@ curl -X POST "https://platform.lensmor.com/external/exhibitors/search-by-company
 
 ## Credit behavior
 
-This endpoint consumes `50` credits per successful search attempt. If the account cannot spend the required credits, the API returns `402 Payment Required`.
+This endpoint consumes `50` credits after the company-name matcher finds at least one exhibitor. A successful empty response consumes `0` credits. If a non-empty search cannot spend the required credits, the API returns `402 Payment Required` instead of returning the matched records.
 
 Refresh [Credits balance](/api-reference/credits/get-credits-balance) after successful searches when your UI or audit log needs final credit reconciliation.
 
@@ -120,5 +126,5 @@ This endpoint is precision-first. It is designed to avoid surprising broad match
 
 ## Notes
 - This endpoint uses `POST` because company name matching may evolve to accept additional body parameters. It does not create a persistent resource.
-- No matches return an empty paginated success response rather than `404 Not Found`.
+- No matches return an empty paginated success response rather than `404 Not Found`, and do not consume credits.
 - If you need event results for a company name, use `POST /external/exhibitors/search-events`.

api-reference-backup/exhibitors/search-events.mdx

@@ -36,6 +36,7 @@ See [Authentication](/authentication)
 | Name | Required | Type | Notes |
 | --- | --- | --- | --- |
 | `company_name` | Yes | string | Company name input. Incomplete names are allowed, but matching stays precision-first. |
+| `sponsor_match_starred` | No | integer | `1` returns starred Sponsor Match events, `0` returns non-starred events; omit to include both. |
 | `page` | No | integer | Defaults to `1`. |
 | `pageSize` | No | integer | Defaults to `20`; maximum `100`. |
 
@@ -50,7 +51,7 @@ curl -X POST "https://platform.lensmor.com/external/exhibitors/search-events" \
   -H "Authorization: Bearer $LENSMOR_API_KEY" \
   -H "Content-Type: application/json" \
   -H "x-call-source: api" \
-  -d '{"company_name":"Acme","page":1,"pageSize":20}'
+  -d '{"company_name":"Acme","sponsor_match_starred":1,"page":1,"pageSize":20}'
 ```
 
 ## Response example
@@ -70,11 +71,10 @@ curl -X POST "https://platform.lensmor.com/external/exhibitors/search-events" \
       "city": "Las Vegas",
       "region": "Nevada",
       "country": "United States",
-      "attendeeCount": null,
       "exhibitorCount": 100,
-      "personnelCount": 50,
+      "sponsorMatchStarred": 1,
       "image": null,
-      "dataSource": null,
+      "dataSource": "Lensmor",
       "matchedExhibitors": [
         {
           "id": "456",
@@ -100,13 +100,15 @@ curl -X POST "https://platform.lensmor.com/external/exhibitors/search-events" \
 | `name`, `nickname`, `description`, `url` | Event display and source fields. |
 | `dateStart`, `dateEnd` | Event date range. |
 | `venue`, `city`, `region`, `country` | Event location fields. Values can be `null` or empty strings when the event source does not provide normalized location metadata. |
-| `attendeeCount`, `exhibitorCount`, `personnelCount` | Event scale and coverage fields when available. |
+| `exhibitorCount` | Exhibitor coverage count when available. |
+| `sponsorMatchStarred` | Sponsor Match starred state (`0` or `1`). |
+| `dataSource` | Always `Lensmor` for public event records. |
 | `matchedExhibitors` | Matched company records that connect the input to the returned event. Treat this as the primary evidence that the company-name input matched the returned event. |
 | `total`, `page`, `pageSize`, `totalPages`, `hasMore` | Pagination metadata. |
 
 ## Credit behavior
 
-This endpoint currently consumes `50` credits per successful search attempt. If the account cannot spend the required credits, the API returns `402 Payment Required`.
+This endpoint consumes `50` credits after the company-name matcher finds at least one event. A successful empty response consumes `0` credits. If a non-empty search cannot spend the required credits, the API returns `402 Payment Required` instead of returning the matched records.
 
 Refresh [Credits balance](/api-reference/credits/get-credits-balance) after successful searches when your UI or audit log needs final credit reconciliation. Use the returned event count, page count, and `matchedExhibitors` as the main value evidence for the search result.
 
@@ -118,8 +120,8 @@ Refresh [Credits balance](/api-reference/credits/get-credits-balance) after succ
 
 ## Notes
 - This endpoint is separate from `GET /external/exhibitors/events`, which requires a known `exhibitor_id`.
-- This endpoint currently consumes `50` credits per successful search attempt. See [Credits and access](/concepts/credits-and-access).
+- This endpoint consumes `50` credits only for a non-empty result. See [Credits and access](/concepts/credits-and-access).
 - Compact-normalized queries shorter than `3` characters use exact-only matching after case, whitespace, and connector-punctuation normalization.
 - Longer queries use strict token or prefix admission instead of permissive `contains` matching.
-- No matches return an empty paginated success response rather than `404 Not Found`.
+- No matches return an empty paginated success response rather than `404 Not Found`, and do not consume credits.
 - `matchedExhibitors` contains only the admitted matched exhibitors that actually participate in the returned event, and event results are returned in deterministic recency order.