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

# SphereScout REST API overview

> Explore SphereScout's REST API for programmatic access to the contact database: search, filter, and export business contacts at scale.

The SphereScout REST API gives you programmatic access to the contact database. Use it to search and filter millions of business contacts by location, category, and contact method; stream results into your CRM; trigger CSV exports; and manage API credentials — all over standard HTTPS with JSON request and response bodies.

## Base URL

All API endpoints are served from a single origin:

```
https://www.spherescout.io
```

Every endpoint lives under the `/api/` path prefix. For example, the company search endpoint is:

```
GET https://www.spherescout.io/api/companies
```

## Authentication methods

The API supports two ways to authenticate requests. Both use the `Authorization` header: API keys with the `Token` prefix, JWT access tokens with the `Bearer` prefix.

<Tabs>
  <Tab title="API keys (recommended)">
    API keys are long-lived credentials you generate in the Dashboard. They do not expire by default, making them the right choice for server-to-server integrations and automation scripts.

    ```bash theme={null}
    Authorization: Token YOUR_API_KEY
    ```

    See [API keys](/api-access/api-keys) for how to create and manage your keys.
  </Tab>

  <Tab title="JWT bearer tokens">
    JWT tokens are short-lived and tied to a user session. Obtain them by calling `POST /api/auth/login` with your email and password. Use access tokens in the same `Authorization` header, and refresh them before they expire using `POST /api/token/refresh`.

    JWT auth is suitable for user-facing applications that sign in on behalf of a specific user.

    ```bash theme={null}
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    ```

    See [Authentication](/api-access/authentication) for the full login and token-refresh flow.
  </Tab>
</Tabs>

<Tip>
  For integrations and server-side scripts, use API keys. They are simpler to manage and do not require a token-refresh cycle.
</Tip>

## Request format

All requests that include a body (POST, PATCH) must send JSON and set the `Content-Type` header accordingly:

```
Content-Type: application/json
```

GET requests pass parameters as URL query strings. Boolean filters use the string values `"true"` and `"false"`.

## Quick example

The following request searches for contacts in France who have an email address on file:

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://www.spherescout.io/api/companies" \
    -H "Authorization: Token YOUR_API_KEY" \
    --data-urlencode "countries=FR" \
    --data-urlencode "email=true"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://www.spherescout.io/api/companies",
      headers={"Authorization": "Token YOUR_API_KEY"},
      params={"countries": "FR", "email": "true"},
  )
  data = response.json()
  print(f"Found {data['totalCount']} contacts")
  print(data["preview"][:3])
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://www.spherescout.io/api/companies?countries=FR&email=true",
    {
      headers: { Authorization: "Token YOUR_API_KEY" },
    }
  );
  const data = await response.json();
  console.log(`Found ${data.totalCount} contacts`);
  ```
</CodeGroup>

## Search and export flow

Exporting contacts is asynchronous. Preview the result set, start an export with the same filters, poll its `search_id`, then request the completed file.

<Steps>
  <Step title="Run a search">
    Call `GET /api/companies` with the filters that describe the contacts you want (country, category, contact method, etc.). The response includes a `totalCount` and a paginated `preview` of results. Previewing does not create a search ID.

    Permanently closed businesses are excluded by default. Set `include_closed_businesses=true` here and on the export request if you want to include them. Using the same value on both requests keeps the preview count and export credit cost aligned.

    ```bash theme={null}
    curl -G "https://www.spherescout.io/api/companies" \
      -H "Authorization: Token YOUR_API_KEY" \
      --data-urlencode "countries=FR" \
      --data-urlencode "email=true"
    ```

    ```json Response theme={null}
    {
      "totalCount": 12480,
      "preview": []
    }
    ```
  </Step>

  <Step title="Initiate the CSV export">
    Call `GET /api/download-csv` with the same filters to enqueue the export. This endpoint returns a numeric `search_id`. That value is the only identifier used for the rest of the export workflow.

    ```bash theme={null}
    curl -G "https://www.spherescout.io/api/download-csv" \
      -H "Authorization: Token YOUR_API_KEY" \
      --data-urlencode "countries=FR" \
      --data-urlencode "email=true" \
      --data-urlencode "export_format=csv"
    ```

    ```json Response theme={null}
    {
      "status": "processing",
      "validation_code": "processing_started",
      "search_id": 12345,
      "lead_count": 12480
    }
    ```
  </Step>

  <Step title="Poll for completion">
    Call `GET /api/download-status/{search_id}` periodically until `status` becomes `completed` or `failed`. We recommend polling every **2–5 seconds** with exponential backoff; most exports complete in under a minute, but large result sets can take longer.

    Possible `status` values:

    | Status | Meaning |
    | - | - |
    | `pending` | Job is queued, not yet started. Keep polling. |
    | `processing` | Job is running. Keep polling. |
    | `completed` | The export file is ready. Proceed to the download endpoint. |
    | `failed` | Job failed. Check `validation_code` and, when present, `error_message`. |

    ```json Completed response theme={null}
    {
      "status": "completed",
      "validation_code": "processing_completed",
      "lead_count": 12480,
      "file_size_bytes": 845220,
      "expires_at": "2026-06-04T12:00:00Z"
    }
    ```
  </Step>

  <Step title="Download the CSV">
    Call `GET /api/download-completed-csv/{search_id}` with the same `search_id`. The response contains a time-limited `download_url`; fetch that URL to download the file.

    ```json Response theme={null}
    {
      "download_url": "https://storage.googleapis.com/...",
      "filename": "spherescout_leads_12345.csv",
      "file_size_bytes": 845220,
      "file_size_mb": 0.81,
      "expires_at": "2026-06-04T12:00:00Z"
    }
    ```
  </Step>
</Steps>

<Tip>
  `search_id` is created by the export request, not by the preview request. Persist the exact `search_id` returned in step 2 and use it for both status polling and file download.
</Tip>

## Optional export fields

Both export options default to `false`, so existing integrations keep the same result set and column layout.

| Parameter | Where to use it | Effect |
| - | - | - |
| `include_additional_fields=true` | `/api/download-csv` | Appends `Latitude`, `Longitude`, `Rating`, `Review Count`, `Claimed`, `Opening Hours`, and `Business Status` to CSV and XLSX files. |
| `include_closed_businesses=true` | `/api/companies` and `/api/download-csv` | Includes permanently closed businesses in the preview count and export. Use it with `include_additional_fields=true` to identify those rows through `Business Status`. |

For example:

```bash theme={null}
curl -G "https://www.spherescout.io/api/download-csv" \
  -H "Authorization: Token YOUR_API_KEY" \
  --data-urlencode "countries=FR" \
  --data-urlencode "include_additional_fields=true" \
  --data-urlencode "include_closed_businesses=true" \
  --data-urlencode "export_format=csv"
```

## Rate limits

The API enforces rate limits to ensure availability for all users. Specific thresholds depend on your plan. Contact [support](mailto:support@spherescout.io) for rate limit details relevant to your account.

## Endpoint reference

The table below groups the public API surface by category.

### Authentication

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/auth/login` | Obtain JWT access and refresh tokens |
| `POST` | `/api/token/refresh` | Exchange a refresh token for a new access token |

### Account

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/user/profile` | Retrieve account details and remaining credit balance |

### API key management

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/user/api-keys` | List all API keys on your account |
| `POST` | `/api/user/api-keys` | Create a new API key |
| `DELETE` | `/api/user/api-keys/{key_id}` | Permanently revoke an API key |

### Contact search

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/companies` | Search and filter business contacts (authenticated) |
| `GET` | `/api/public/companies` | Preview contacts without authentication (limited results) |

### Reference data

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/categories` | List all business categories and their IDs |
| `GET` | `/api/locations/countries` | List available countries |
| `GET` | `/api/locations/search` | Search for locations by query string |
| `GET` | `/api/professions/summary` | Retrieve profession and subcategory data |

### Exports

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/download-csv` | Initiate an async export with search filters; returns a `search_id` |
| `GET` | `/api/download-status/{search_id}` | Poll the status of an export |
| `GET` | `/api/download-completed-csv/{search_id}` | Get the signed URL for a completed export |

### Export history

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/user/search-history` | List all past exports on your account |
| `GET` | `/api/user/search-history/{id}/freshness` | Check whether new contacts match a past search |
| `GET` | `/api/user/search-history/{id}/download-delta` | Download only the new contacts since a previous export |

## Next steps

<CardGroup cols={2}>
  <Card title="API keys" icon="key" href="/api-access/api-keys">
    Generate and manage long-lived API credentials for server integrations.
  </Card>

  <Card title="Authentication" icon="lock" href="/api-access/authentication">
    Learn the full JWT login flow and token-refresh cycle.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.