> ## 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 same `Authorization: Bearer` header format.

<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: Bearer sk_live_xxxxxxxxxxxxxxxx
    ```

    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: Bearer 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": "Bearer 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: "Bearer YOUR_API_KEY" },
    }
  );
  const data = await response.json();
  console.log(`Found ${data.totalCount} contacts`);
  ```
</CodeGroup>

## Search and export flow

Exporting contacts is a two-step process: you first run a search to define the result set, then trigger an asynchronous CSV export against that search and poll until the file is ready.

<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`, a paginated `preview` of results, and a `search_id` that uniquely identifies this query.

    Use the `search_id` to drive the export — there is no need to re-send the filters.

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

    ```json Response theme={null}
    {
      "search_id": "srch_01HZ...",
      "totalCount": 12480,
      "preview": [ /* first page of contacts */ ]
    }
    ```
  </Step>

  <Step title="Initiate the CSV export">
    Call `GET /api/download-csv?search_id={search_id}` to enqueue the export. This endpoint is **asynchronous**: it returns immediately with a `task_id` that identifies the background job — it does **not** return the CSV itself.

    ```bash theme={null}
    curl -G "https://www.spherescout.io/api/download-csv" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      --data-urlencode "search_id=srch_01HZ..."
    ```

    ```json Response theme={null}
    {
      "task_id": "task_01HZ...",
      "status": "pending"
    }
    ```
  </Step>

  <Step title="Poll for completion">
    Call `GET /api/download-status/{task_id}` periodically until `status` becomes `ready`. 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.                                                         |
    | `ready`      | CSV is ready. Response includes a `download_url`.                                     |
    | `failed`     | Job failed. Response includes an `error` message; do not retry without investigating. |

    ```json Ready response theme={null}
    {
      "task_id": "task_01HZ...",
      "status": "ready",
      "download_url": "https://www.spherescout.io/exports/...csv",
      "expires_at": "2026-06-04T12:00:00Z"
    }
    ```
  </Step>

  <Step title="Download the CSV">
    Fetch the file from the `download_url` returned in the previous step. Links remain valid for 30 days; after that, regenerate the export from your [search history](/guides/export-history).
  </Step>
</Steps>

<Tip>
  Re-running the same search returns the same `search_id` for a short window, so you can safely retry step 1 if the network drops. The `task_id` from step 2, however, is unique per export — always poll the exact `task_id` you received.
</Tip>

## 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 CSV export for a given `search_id`; returns a `task_id` |
| `GET`  | `/api/download-status/{task_id}` | Poll the status of an export job and retrieve the download URL when ready |

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