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

# Preview a filter

> Evaluate an unsaved filter with the same query parameters and compiler as `GET /contacts`, returning the exact match count plus a small sample.



## OpenAPI

````yaml /public_openapi.json get /api/public/v1/contacts/lists/preview
openapi: 3.0.3
info:
  title: ColdSend Public API
  description: >-
    Programmatic access to ColdSend for managing cold email campaigns and sender
    accounts.
  version: 1.0.0
  contact:
    name: ColdSend Support
    email: support@coldsend.pro
    url: https://coldsend.pro
servers:
  - url: https://api.coldsend.pro
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/public/v1/contacts/lists/preview:
    get:
      tags:
        - Contacts
      summary: Preview a filter
      description: >-
        Evaluate an unsaved filter with the same query parameters and compiler
        as `GET /contacts`, returning the exact match count plus a small sample.
      operationId: preview_contact_filter_api_public_v1_contacts_lists_preview_get
      parameters:
        - name: sample_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 0
            description: Sample rows to return
            default: 10
            title: Sample Size
          description: Sample rows to return
        - name: signal
          in: query
          required: false
          schema:
            items:
              $ref: '#/components/schemas/ContactSignal'
            type: array
            nullable: true
            title: Signal
            description: Match any of these engagement signals
          description: Match any of these engagement signals
        - name: tag_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
            nullable: true
            title: Tag Ids
            description: Match contacts carrying any of these tags
          description: Match contacts carrying any of these tags
        - name: is_unsubscribed
          in: query
          required: false
          schema:
            type: boolean
            nullable: true
            title: Is Unsubscribed
            description: Filter on team-level suppression
          description: Filter on team-level suppression
        - name: is_bounced
          in: query
          required: false
          schema:
            type: boolean
            nullable: true
            title: Is Bounced
            description: Filter on whether any membership bounced
          description: Filter on whether any membership bounced
        - name: source_type
          in: query
          required: false
          schema:
            items:
              $ref: '#/components/schemas/ContactSourceType'
            type: array
            nullable: true
            title: Source Type
            description: Match any of these acquisition sources
          description: Match any of these acquisition sources
        - name: source_name
          in: query
          required: false
          schema:
            type: string
            nullable: true
            title: Source Name
            description: Exact origin name, e.g. the uploaded file name
          description: Exact origin name, e.g. the uploaded file name
        - name: campaign_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            nullable: true
            title: Campaign Id
            description: Only contacts with a membership in this campaign
          description: Only contacts with a membership in this campaign
        - name: not_in_campaign_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            nullable: true
            title: Not In Campaign Id
            description: Exclude contacts already in this campaign
          description: Exclude contacts already in this campaign
        - name: last_touch_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
            title: Last Touch After
            description: Last outbound contact at or after this time
          description: Last outbound contact at or after this time
        - name: last_touch_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
            title: Last Touch Before
            description: Last outbound contact strictly before this time
          description: Last outbound contact strictly before this time
        - name: has_replied
          in: query
          required: false
          schema:
            type: boolean
            nullable: true
            title: Has Replied
            description: Filter on whether the contact ever replied
          description: Filter on whether the contact ever replied
        - name: has_opened
          in: query
          required: false
          schema:
            type: boolean
            nullable: true
            title: Has Opened
            description: Filter on whether the contact ever opened
          description: Filter on whether the contact ever opened
        - name: search
          in: query
          required: false
          schema:
            type: string
            nullable: true
            title: Search
            description: Substring match across email, name and company
          description: Substring match across email, name and company
      responses:
        '200':
          description: Preview evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactListPreviewApiResponse'
        '403':
          description: Insufficient permissions - requires 'contacts:read' scope
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ContactSignal:
      type: string
      enum:
        - NEVER_CONTACTED
        - CONTACTED
        - ENGAGED
        - HOT_LEAD
        - BOUNCED
        - UNSUBSCRIBED
      title: ContactSignal
      description: |-
        Engagement signal for a directory contact.

        Materialised onto `contacts.signal` by the contact rollup job so the
        directory can filter and sort on it without touching `leads`. Derived
        from the contact's campaign memberships in strict precedence order --
        the first match wins:

            UNSUBSCRIBED    : suppressed for this team, i.e. a row exists in
                              `unsubscribes` for (team_id, email) with
                              unsubscribed_at IS NOT NULL. Suppression is
                              email-keyed, so this is independent of any
                              particular lead row.
            BOUNCED         : a membership bounced and the contact has never
                              otherwise engaged.
            HOT_LEAD        : a thread carries a positive INTENT tag
                              (Demo Booked / Interested).
            ENGAGED         : has replied or opened, or a thread carries the
                              Question INTENT tag.
            CONTACTED       : has been sent to, but no engagement recorded.
            NEVER_CONTACTED : no membership has been sent yet.

        A non-NULL `contacts.signal_override` always wins over the derived
        value, so a manually pinned signal is never clobbered by the job.

        Mirrors the `contactsignal` Postgres enum created in migration
        `20260826_0001_add_contact_directory.py`. Keep in sync.
    ContactSourceType:
      type: string
      enum:
        - CSV
        - MANUAL
        - COPY
        - EXTERNAL_EMAIL
        - API
      title: ContactSourceType
      description: |-
        How a contact first entered the directory.

        Stored as a plain string column (not a Postgres enum) to match the
        existing `lead_batches.source_type` convention; this class is the
        canonical set of allowed values and is enforced by a CHECK constraint.
    ContactListPreviewApiResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: true
        message:
          type: string
          title: Message
        total:
          type: integer
          title: Total
        sample:
          items:
            $ref: '#/components/schemas/ContactResponse'
          type: array
          title: Sample
      type: object
      required:
        - message
        - total
        - sample
      title: ContactListPreviewApiResponse
      description: Outcome of evaluating an unsaved filter.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ContactResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        team_id:
          type: string
          format: uuid
          title: Team Id
        email:
          type: string
          title: Email
        first_name:
          type: string
          nullable: true
          title: First Name
        last_name:
          type: string
          nullable: true
          title: Last Name
        company:
          type: string
          nullable: true
          title: Company
        custom_fields:
          additionalProperties: true
          type: object
          nullable: true
          title: Custom Fields
        signal:
          $ref: '#/components/schemas/ContactSignal'
        signal_override:
          $ref: '#/components/schemas/ContactSignal'
          nullable: true
        signal_computed_at:
          type: string
          format: date-time
          nullable: true
          title: Signal Computed At
        source_type:
          type: string
          nullable: true
          title: Source Type
        source_name:
          type: string
          nullable: true
          title: Source Name
        first_batch_id:
          type: string
          format: uuid
          nullable: true
          title: First Batch Id
        last_touch_at:
          type: string
          format: date-time
          nullable: true
          title: Last Touch At
        last_reply_at:
          type: string
          format: date-time
          nullable: true
          title: Last Reply At
        last_open_at:
          type: string
          format: date-time
          nullable: true
          title: Last Open At
        campaign_count:
          type: integer
          title: Campaign Count
          default: 0
        is_unsubscribed:
          type: boolean
          title: Is Unsubscribed
          default: false
        is_bounced:
          type: boolean
          title: Is Bounced
          default: false
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        tags:
          items:
            $ref: '#/components/schemas/ContactTagResponse'
          type: array
          title: Tags
        campaign_names:
          items:
            type: string
          type: array
          title: Campaign Names
      type: object
      required:
        - id
        - team_id
        - email
        - signal
        - created_at
        - updated_at
      title: ContactResponse
      description: |-
        A directory row.

        `signal` is the effective signal: the rollup job materialises
        COALESCE(signal_override, derived) into the column, so a manual pin is
        already reflected here. `signal_override` is surfaced separately only so
        the UI can show whether the value is pinned.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ContactTagResponse:
      properties:
        tag_id:
          type: string
          format: uuid
          title: Tag Id
        name:
          type: string
          title: Name
        color:
          type: string
          nullable: true
          title: Color
        category_group:
          type: string
          nullable: true
          title: Category Group
        is_system:
          type: boolean
          title: Is System
          default: false
        applied_by_id:
          type: string
          format: uuid
          nullable: true
          title: Applied By Id
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - tag_id
        - name
        - created_at
      title: ContactTagResponse
      description: A team tag applied to a contact.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key with format cs_live_xxx

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.