Quickstart - Hostreach

1. Get an API key

Sign up or log in at app.hostreach.io.
Go to Settings › Workspace › Acceso API.
Click New API key, choose a name and scopes, and copy the key — it starts with hr_live_.

The full key is only shown once. Store it securely (e.g. in an environment variable).

2. Verify your identity

curl https://api.hostreach.io/v1/public/v1/me \
  -H "X-Api-Key: hr_live_your_key_here"

const res = await fetch('https://api.hostreach.io/v1/public/v1/me', {
  headers: { 'X-Api-Key': 'hr_live_your_key_here' }
});
const data = await res.json();
console.log(data);

import requests

r = requests.get(
    'https://api.hostreach.io/v1/public/v1/me',
    headers={'X-Api-Key': 'hr_live_your_key_here'}
)
print(r.json())

Response:

{
  "workspaceId": "ws-...",
  "workspaceName": "My Agency",
  "apiKeyName": "my-integration",
  "scopes": []
}

3. Extract your first leads

Lead extraction is asynchronous. Start the job, then poll for completion.

Step 1 — Search for a location

curl "https://api.hostreach.io/v1/public/v1/platforms/idealista/locations?q=Valencia" \
  -H "X-Api-Key: hr_live_your_key_here"

Use the returned location object as the filters.location value below.

Step 2 — Start the extraction

curl -X POST https://api.hostreach.io/v1/public/v1/extractions \
  -H "X-Api-Key: hr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "idealista",
    "filters": {
      "operation": "rent",
      "location": { "id": "0-EU-ES-VC-46-46250-999-2-009", "label": "Valencia" }
    },
    "maxResults": 50
  }'

Response (202 Accepted):

{
  "extractionId": "extr-uuid-here",
  "campaignId": "camp-uuid-here",
  "status": "QUEUED",
  "platform": "idealista",
  "maxResults": 50,
  "message": "Extraction started. Poll GET /extractions/:id or subscribe to the extraction.completed webhook."
}

Step 3 — Poll until complete

curl https://api.hostreach.io/v1/public/v1/extractions/extr-uuid-here \
  -H "X-Api-Key: hr_live_your_key_here"

Poll every 5–10 seconds. Stop when status is COMPLETED or FAILED.

{ "id": "extr-uuid-here", "status": "COMPLETED", "expectedResults": 50 }

Step 4 — Retrieve the leads

curl "https://api.hostreach.io/v1/public/v1/extractions/extr-uuid-here/leads?page=1&limit=50" \
  -H "X-Api-Key: hr_live_your_key_here"

Next steps

Authentication — API key scopes and environments
API Reference — full endpoint documentation
Integrations — MCP server, CLI, and Agent Skill

​1. Get an API key

​2. Verify your identity

​3. Extract your first leads

​Step 1 — Search for a location

​Step 2 — Start the extraction

​Step 3 — Poll until complete

​Step 4 — Retrieve the leads

​Next steps

1. Get an API key

2. Verify your identity

3. Extract your first leads

Step 1 — Search for a location

Step 2 — Start the extraction

Step 3 — Poll until complete

Step 4 — Retrieve the leads

Next steps