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

# Update a Lead Insight

> Updates topic, preference text, and/or confidence for one insight.

Path `{id}` here is the preference document `_id` (MongoDB ObjectId),
not the lead id.

Requires `conversations:edit` permission.




## OpenAPI

````yaml PATCH /api/preferences/{id}
openapi: 3.1.0
info:
  title: Naturalead Lead Insights (Preferences) API
  version: 1.0.0
  description: >
    Lead Insights are structured key points the AI extracts from conversations

    (budget, timeline, location, etc.). They power the "Lead Insights" sidebar

    in the dashboard and are the recommended CRM sync payload for what the

    lead shared — more useful than a free-form conversation `summary`.


    Insights are **lead-scoped** (one set per lead, accumulated across
    sessions),

    not conversation-scoped. All endpoints require API key or Clerk auth and are

    scoped to the caller's account.


    Path note: `GET` uses the **lead id**; `PATCH` / `DELETE` use the
    **preference

    document `_id`**. Same URL pattern, different identifiers by method.
servers:
  - url: https://api.naturalead.ai
    description: Production
  - url: http://localhost:3001
    description: Local development
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Lead Insights
    description: Extracted lead preferences / key points for CRM sync and agent memory
paths:
  /api/preferences/{id}:
    patch:
      tags:
        - Lead Insights
      summary: Update a Lead Insight
      description: |
        Updates topic, preference text, and/or confidence for one insight.

        Path `{id}` here is the preference document `_id` (MongoDB ObjectId),
        not the lead id.

        Requires `conversations:edit` permission.
      operationId: updateLeadPreference
      parameters:
        - name: id
          in: path
          required: true
          description: MongoDB ObjectId of the preference document.
          schema:
            type: string
          example: 507f1f77bcf86cd799439011
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLeadPreferenceRequest'
            example:
              preference: $75k-120k
              confidence: high
      responses:
        '200':
          description: Updated insight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadPreference'
        '400':
          description: Invalid id, empty body, invalid confidence, or rejected content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidId:
                  value:
                    error: Invalid preference ID
                invalidConfidence:
                  value:
                    error: 'Invalid confidence. Must be: high, medium, or low'
                noFields:
                  value:
                    error: No valid fields to update
        '404':
          description: Preference not found in this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Preference not found
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    UpdateLeadPreferenceRequest:
      type: object
      description: |
        Partial update. At least one of `topic`, `preference`, or `confidence`
        must be provided.
      properties:
        topic:
          type: string
          maxLength: 100
        preference:
          type: string
          maxLength: 200
        confidence:
          type: string
          enum:
            - high
            - medium
            - low
    LeadPreference:
      type: object
      description: |
        A single extracted lead insight (preference). Unique per
        `(accountId, leadId, topic)` — updates overwrite the same topic.
      properties:
        _id:
          type: string
          description: Preference document id.
        leadId:
          type: string
          description: Lead id these insights belong to.
        accountId:
          type: string
          description: Owning account id.
        conversationId:
          type: string
          description: Conversation that last wrote or updated this insight.
        topic:
          type: string
          maxLength: 100
          description: Preference domain (e.g. budget, timeline, location).
        preference:
          type: string
          maxLength: 200
          description: Extracted value for the topic.
        confidence:
          type: string
          enum:
            - high
            - medium
            - low
          description: Model confidence in the extraction.
        source:
          type: string
          description: Short snippet or provenance of the extraction.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: TTL expiry (default ~90 days from last write).
      required:
        - _id
        - leadId
        - topic
        - preference
        - confidence
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
      required:
        - error
  responses:
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Failed to fetch preferences
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for programmatic access (format nl_live_* or nl_test_*)
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token using an API key (format nl_live_* or nl_test_*) or Clerk
        session

````