Lensmor Credits API

openapi: 3.2.0
info:
  title: Lensmor Credits API
  version: 0.27.0
  description: Lensmor Event Intelligence API for event discovery, exhibitor research, personnel lookup, credits, and profile matching.
  license:
    name: Lensmor Terms of Service
    url: https://www.lensmor.com/terms
servers:
- url: https://platform.lensmor.com
security:
- bearerAuth: []
tags:
- name: Credits
  description: Inspect the credit balance available to the authenticated API key owner.
paths:
  /external/credits/balance:
    get:
      tags:
      - Credits
      summary: Get credits balance
      description: 'Return the current credit position for the authenticated API key owner without spending credits.


        Use this endpoint before and after any workflow that can consume credits, including event access, Visitor access, contact enrichment, and charged company searches. The response separates subscription, add-on, and gift balances so a client can show both the usable total and the buckets that contribute to it.


        This is a read-only account check. A successful response does not reserve credits or guarantee that a later paid action will still have sufficient balance, so refresh the balance immediately before user-confirmed spending and again after the action completes.'
      operationId: getExternalCreditsBalance
      responses:
        '200':
          description: Credits balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalance'
              example:
                totalAmount: 45050
                totalBalance: 38050
                subscriptionAmount: 35000
                subscriptionBalance: 30000
                addonAmount: 10000
                addonBalance: 8000
                addonExpireAt: 1784851200000
                giftAmount: 50
                giftBalance: 50
                resetAt: 1714521600000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 429
            message: Rate limit exceeded
            errorKey: RATE_LIMIT_EXCEEDED
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 401
            message: Invalid API key
            errorKey: INVALID_API_KEY
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
  schemas:
    CreditBalance:
      type: object
      required:
      - totalAmount
      - totalBalance
      - subscriptionAmount
      - subscriptionBalance
      - addonAmount
      - addonBalance
      - addonExpireAt
      - giftAmount
      - giftBalance
      - resetAt
      properties:
        totalAmount:
          type: number
          description: Total credits allocated across subscription, add-on, and gift buckets.
        totalBalance:
          type: number
          description: Total credits currently available to spend across all buckets.
        subscriptionAmount:
          type: number
          description: Credits allocated by the current subscription period.
        subscriptionBalance:
          type: number
          description: Subscription credits currently available to spend.
        addonAmount:
          type: number
          description: Total credits allocated through add-on purchases.
        addonBalance:
          type: number
          description: Add-on credits currently available to spend.
        addonExpireAt:
          type:
          - number
          - 'null'
          description: Unix timestamp for add-on credit expiry, or `null` when no expiry applies.
        giftAmount:
          type: number
          description: Total promotional or gifted credits allocated.
        giftBalance:
          type: number
          description: Promotional or gifted credits currently available to spend.
        resetAt:
          type:
          - number
          - 'null'
          description: Unix timestamp for the next subscription-credit reset, or `null` when unavailable.
      description: Current total and per-bucket Lensmor credit amounts for the API key owner.
    ApiError:
      type: object
      required:
      - code
      - message
      - errorKey
      - traceId
      properties:
        code:
          type: integer
          description: Numeric or symbolic code that identifies the response or business condition.
        message:
          type: string
          description: Human-readable explanation suitable for logs or user-facing error handling.
        errorKey:
          type: string
          description: Stable machine-readable error key for branching and analytics.
        traceId:
          type: string
          description: Request trace identifier to include in support or incident reports.
        details:
          description: Optional structured business or validation context. Omitted when the error has no additional details.
      description: Shared error envelope returned by public Lensmor API endpoints.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Business sk API key
      description: 'Send the full Business API key from Settings -> API Keys, for example `Authorization: Bearer sk_your_api_key`.'