Skip to main content
POST
/
public
/
v1
/
campaigns
Create a campaign
curl --request POST \
  --url https://api.hostreach.io/v1/public/v1/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "platform": "idealista",
  "name": "Valencia — Rent Q3 2026",
  "mode": "extract_and_contact",
  "contactMode": "whatsapp",
  "segmentation": {
    "filters": {
      "operation": "rent",
      "location": {
        "id": "0-EU-ES-VC-46",
        "label": "Valencia"
      }
    },
    "expectedResults": 50
  },
  "settings": "<unknown>"
}
'

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.

Authorizations

​
X-Api-Key
string
header
required

API key (hr_live_... or hr_test_...). Generate from Settings › Workspace › Acceso API.

Body

application/json
​
platform
enum<string>
required

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.
Available options:
idealista,
fotocasa,
metrocuadrado,
inmuebles24,
zonaprop,
widget,
csv_import
Example:

"idealista"

​
name
string

Campaign name. Defaults to "Untitled Campaign" if omitted.

Maximum string length: 255
Example:

"Valencia — Rent Q3 2026"

​
mode
enum<string>
default:extract_and_contact

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.

Available options:
extract_only,
extract_and_contact
Example:

"extract_and_contact"

​
contactMode
enum<string>
default:whatsapp

Outreach channel to use when sending messages.

  • whatsapp: WhatsApp Business API (requires connected account).
  • whatsapp-no-api: Manual WhatsApp (no account required).
Available options:
whatsapp,
whatsapp-no-api
Example:

"whatsapp"

​
segmentation
object

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
any

Scheduling and messaging settings. scheduledHours and scheduledDays are required for csv_import campaigns before setting status to running.

Response

201 - undefined