Skip to main content

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.

​
1. Get an API key

  1. Sign up or log in at app.hostreach.io.
  2. Go to Settings › Workspace › Acceso API.
  3. 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"
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