> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hrizn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit a Vehicle Spotlight lead

> Captures a shopper inquiry from a public Vehicle Spotlight share page and enqueues CRM (ADF) delivery. Idempotent on idempotency_key. Rate limit: 8 per minute and 200 per day per client IP. Origin must be the Hrizn app.



## OpenAPI

````yaml /openapi.yaml post /share/shopper-lead
openapi: 3.1.0
info:
  title: Hrizn Public API
  version: 1.2.0
  description: >
    The Hrizn Public API allows partners to programmatically create content,
    manage inventory descriptions, and integrate with the Hrizn platform.


    All endpoints are prefixed with `/public` and require an API key passed via
    the `X-API-Key` header (except the health check).
  contact:
    email: support@hrizn.io
servers:
  - url: https://api.app.hrizn.io/v1/public
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Analytics
    description: >-
      Warehoused Google Search Console and GA4 reads (Teams+ API access,
      analytics:read). URL Inspection is live only on pages/performance.
  - name: IdeaClouds
    description: Create and manage AI-powered keyword research
  - name: Content Intelligence
    description: AI-powered content gap analysis and recommendations
  - name: Content
    description: Generate content from IdeaClouds
  - name: Compliance
    description: Run OEM compliance checks on content
  - name: Content Tools
    description: Generate SEO metadata, schemas, and social snippets
  - name: Inventory
    description: Access vehicle data and AI descriptions
  - name: Images
    description: >-
      Media Library images. Read the library (images:read): list and fetch
      images with alt text, AI-written title/caption/description, the generating
      prompt, dimensions, article links, and social variant cuts. Generate
      (images:write): async AI image generation returning an image_id;
      completion is delivered via image.generation.completed /
      image.generation.failed webhooks.
  - name: Market
    description: >-
      Live local market listings, days supply, competitive set, and pricing
      insights (Unlimited plan + market_data:read)
  - name: Site
    description: View dealership details and configuration
  - name: Webhooks
    description: Manage webhook subscriptions for real-time events
  - name: Reference
    description: Look up available types, scopes, and events
  - name: Social
    description: >-
      Social Hub posting and reviews across all connected platforms (X,
      Facebook, Instagram, LinkedIn, Google Business Profile)
  - name: Health
    description: Health check (no authentication)
  - name: Share
    description: >-
      Anonymous share-page routes (no API key). Called by Hrizn share pages
      (/s/{publicId}) on behalf of shoppers who are not signed in. Requests must
      originate from the Hrizn app origin (CORS is origin-checked, never
      wildcard) and are rate limited per client IP. Responses use a flat `{
      error }` / `{ success }` body, not the `{ error: { code, message } }`
      envelope of API-key routes.
paths:
  /share/shopper-lead:
    post:
      tags:
        - Share
      summary: Submit a Vehicle Spotlight lead
      description: >-
        Captures a shopper inquiry from a public Vehicle Spotlight share page
        and enqueues CRM (ADF) delivery. Idempotent on idempotency_key. Rate
        limit: 8 per minute and 200 per day per client IP. Origin must be the
        Hrizn app.
      operationId: submitShareShopperLead
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareShopperLeadRequest'
      responses:
        '200':
          description: Lead captured (or replayed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareShopperLeadResponse'
        '400':
          $ref: '#/components/responses/ShareError'
        '403':
          $ref: '#/components/responses/ShareError'
        '404':
          $ref: '#/components/responses/ShareError'
        '429':
          $ref: '#/components/responses/ShareRateLimited'
        '500':
          $ref: '#/components/responses/ShareError'
      security: []
components:
  schemas:
    ShareShopperLeadRequest:
      type: object
      required:
        - articleId
        - idempotencyKey
        - shopperName
        - shopperEmail
      properties:
        articleId:
          type: string
          format: uuid
          description: Vehicle Spotlight article id from the share page
        shareToken:
          type: string
          nullable: true
          maxLength: 128
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
          description: Client-generated key; replays return the same lead id
        shopperName:
          type: string
          maxLength: 120
        shopperEmail:
          type: string
          format: email
          maxLength: 254
        shopperPhone:
          type: string
          nullable: true
          minLength: 7
          maxLength: 40
        shopperMessage:
          type: string
          nullable: true
          maxLength: 2000
        clientRequestId:
          type: string
          nullable: true
          maxLength: 128
    ShareShopperLeadResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        id:
          type: string
          format: uuid
        alreadyExisted:
          type: boolean
          description: True when the idempotency key matched an existing lead
    ShareErrorBody:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Invalid lead submission.
  responses:
    ShareError:
      description: Share-route error (flat body, not the API-key envelope)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ShareErrorBody'
    ShareRateLimited:
      description: Per-IP rate limit or per-profile daily cap reached
      headers:
        Retry-After:
          description: Seconds until the window resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ShareErrorBody'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Hrizn API key (prefix hzk_)

````