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

# Create a campaign

> Creates a campaign in `draft` status. Use `PATCH /:id/status` to set it to `running`.

**By platform type:**
- **Portal** (`idealista`, `fotocasa`, `metrocuadrado`, `inmuebles24`, `zonaprop`): Leads are extracted from the real-estate portal on schedule or via `POST /:id/execute`. Include `segmentation.filters` and `segmentation.expectedResults`.
- **CSV import** (`csv_import`): Upload leads via the dashboard; sent on a drip schedule. Requires `segmentation.batchSize` (1–25) and `settings.scheduledHours/Days` before going `running`.
- **Widget** (`widget`): Leads arrive from your embedded widget. Only one `running` widget campaign per workspace.



## OpenAPI

````yaml /openapi.json post /public/v1/campaigns
openapi: 3.0.0
info:
  title: Hostreach API
  description: >-
    Public REST API for Hostreach.


    Authenticate with an API key via the `X-Api-Key` header or `Authorization:
    Bearer <key>` header.


    Generate API keys from **Settings › Workspace › Acceso API** in the
    dashboard.
  version: '1.0'
  contact: {}
servers:
  - url: https://api.hostreach.io/v1
    description: Production
  - url: http://localhost:3001/v1
    description: Local
security:
  - apiKey: []
tags:
  - name: Identity
    description: Current workspace and usage
  - name: Platforms
    description: Supported real-estate portals and filter schemas
  - name: Extractions
    description: Lead extraction jobs
  - name: Leads
    description: Lead management
  - name: Campaigns
    description: Campaign management
  - name: Messaging
    description: Inbox and WhatsApp conversations
  - name: Templates
    description: WhatsApp message templates
  - name: Accounts
    description: WhatsApp accounts
  - name: Valuations
    description: Property valuations
  - name: Fichas
    description: Property listing sheets
  - name: Scheduling
    description: Calendar and appointments
  - name: Webhooks
    description: Event subscriptions
paths:
  /public/v1/campaigns:
    post:
      tags:
        - Campaigns
      summary: Create a campaign
      description: >-
        Creates a campaign in `draft` status. Use `PATCH /:id/status` to set it
        to `running`.


        **By platform type:**

        - **Portal** (`idealista`, `fotocasa`, `metrocuadrado`, `inmuebles24`,
        `zonaprop`): Leads are extracted from the real-estate portal on schedule
        or via `POST /:id/execute`. Include `segmentation.filters` and
        `segmentation.expectedResults`.

        - **CSV import** (`csv_import`): Upload leads via the dashboard; sent on
        a drip schedule. Requires `segmentation.batchSize` (1–25) and
        `settings.scheduledHours/Days` before going `running`.

        - **Widget** (`widget`): Leads arrive from your embedded widget. Only
        one `running` widget campaign per workspace.
      operationId: PublicCampaignsController_createCampaign
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePublicCampaignDto'
      responses:
        '201':
          description: ''
      security:
        - bearerApiKey: []
        - apiKey: []
components:
  schemas:
    CreatePublicCampaignDto:
      type: object
      properties:
        platform:
          type: string
          description: >-
            Campaign platform — determines how leads enter the campaign.


            - `idealista` / `fotocasa` / `metrocuadrado` / `inmuebles24` /
            `zonaprop`: Portal extraction via scheduled or manual runs.

            - `csv_import`: Leads uploaded as CSV; sent on a drip schedule.
            Requires `segmentation.batchSize` (1–25) and
            `settings.scheduledHours/Days` before going `running`.

            - `widget`: Leads from your embedded widget form. Only one `running`
            widget campaign allowed per workspace.
          enum:
            - idealista
            - fotocasa
            - metrocuadrado
            - inmuebles24
            - zonaprop
            - widget
            - csv_import
          example: idealista
        name:
          type: string
          description: Campaign name. Defaults to "Untitled Campaign" if omitted.
          maxLength: 255
          example: Valencia — Rent Q3 2026
        mode:
          type: string
          description: >-
            Controls what happens after leads are extracted.


            - `extract_only`: Scrape leads only; no outreach messages sent.

            - `extract_and_contact`: Scrape leads and send the configured
            WhatsApp sequence.


            Automatically forced to `extract_and_contact` for `widget` and
            `csv_import` campaigns.
          enum:
            - extract_only
            - extract_and_contact
          default: extract_and_contact
          example: extract_and_contact
        contactMode:
          type: string
          description: |-
            Outreach channel to use when sending messages.

            - `whatsapp`: WhatsApp Business API (requires connected account).
            - `whatsapp-no-api`: Manual WhatsApp (no account required).
          enum:
            - whatsapp
            - whatsapp-no-api
          default: whatsapp
          example: whatsapp
        segmentation:
          type: object
          description: >-
            Platform-specific segmentation / filter configuration.


            **Portal campaigns:** `{ filters: <portal-filter-object>,
            expectedResults: 50 }`. Use `GET /platforms/{platform}/filters` to
            discover valid filter keys and `GET /platforms/{platform}/locations`
            to look up location values.


            **CSV import:** `{ batchSize: 10 }` — number of leads to contact per
            scheduled run (1–25). Required before setting status to `running`.


            **Widget:** leave empty.
          example:
            filters:
              operation: rent
              location:
                id: 0-EU-ES-VC-46
                label: Valencia
            expectedResults: 50
        settings:
          description: >-
            Scheduling and messaging settings. `scheduledHours` and
            `scheduledDays` are required for `csv_import` campaigns before
            setting status to `running`.
          allOf:
            - def3aa09-22e1-468e-a4e2-9878b501812f
      required:
        - platform
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        API key (hr_live_... or hr_test_...). Generate from Settings › Workspace
        › Acceso API.

````