> ## 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.

# Quickstart

> Make your first Hostreach API call in under 5 minutes.

## 1. Get an API key

1. Sign up or log in at [app.hostreach.io](https://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_`.

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

## 2. Verify your identity

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.hostreach.io/v1/public/v1/me \
    -H "X-Api-Key: hr_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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`):

```json theme={null}
{
  "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

```bash theme={null}
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`.

```json theme={null}
{ "id": "extr-uuid-here", "status": "COMPLETED", "expectedResults": 50 }
```

### Step 4 — Retrieve the leads

```bash theme={null}
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](/authentication) — API key scopes and environments
* [API Reference](/api-reference) — full endpoint documentation
* [Integrations](/integrations/overview) — MCP server, CLI, and Agent Skill