# Create and configure your SphereScout account
Source: https://docs.spherescout.io/account-setup
Sign up with email or Google, log in to your dashboard, reset your password, and understand where your credits and search history live.
Your SphereScout account is the starting point for everything: searching the database, exporting contacts, managing your subscription, and generating API keys. This page covers how to create an account, sign in, and find your way around after you log in.
## Sign up
Go to [spherescout.io](https://www.spherescout.io) and click **Get 100 Free Leads** in the navigation bar. You have two options:
1. Enter your email address.
2. Choose a password and confirm it by entering it a second time.
3. Click **Create Account**.
You are redirected to your dashboard immediately. No email verification step is required before you can start searching.
If the email address you enter is already registered, you will see a prompt to log in instead. Click the prompt to go to the login page with your email pre-filled.
Click **Continue with Google** and complete the Google sign-in flow. SphereScout uses Google OAuth — you are not asked to create a separate password.
If your Google account is already linked to a SphereScout account, you will be signed in directly.
By creating an account you agree to the [Terms of Service](https://www.spherescout.io/terms-of-service/) and [Privacy Policy](https://www.spherescout.io/privacy-policy/).
New accounts receive **100 free leads** with no credit card required. Your credit balance is visible on the dashboard as soon as you sign in.
## Log in
Go to [spherescout.io](https://www.spherescout.io) and click **Login** in the navigation bar.
* **Email and password** — enter the email and password you used when signing up, then click **Login**.
* **Google** — click **Continue with Google** to sign in using the Google account linked to your SphereScout profile.
After a successful login you are redirected to your dashboard.
## Reset your password
If you signed up with an email and password and cannot remember it:
Navigate to the login page and click the **Forgot password?** link below the sign-in form.
Enter the email address associated with your account and submit the form. SphereScout sends a password-reset link to that address.
Open the email and click the reset link. Enter your new password and confirm it. You are then redirected to the login page to sign in with your new credentials.
Password reset is only available for accounts created with an email and password. If you signed up with Google, use Google's account recovery flow to regain access.
## Your dashboard
After logging in you land on the main dashboard. The key sections are:
* **Search** — the primary search and filter interface. Select a business category, country, and optional location refinements to query the database and preview results.
* **History** — a record of every search you have exported. From here you can re-download a previous export, check whether the underlying data has been refreshed since your last export (data freshness), or rename a saved search for easier reference.
* **Plans / Billing** — view your current plan, your remaining monthly credit balance, and upgrade or change your subscription. You can also access one-time purchase options here.
Your remaining credit balance appears at the top of the dashboard. Each exported contact consumes one credit. Credits reset on your monthly billing date.
## API keys
If you want to query SphereScout programmatically, you can generate an API key from your account settings. API keys give your application the same search and export capabilities available in the dashboard.
Learn how to create an API key and authenticate your requests.
## Support
If you run into any issues with your account, reach out to the support team at [support@spherescout.io](mailto:support@spherescout.io).
# Create and manage SphereScout API keys
Source: https://docs.spherescout.io/api-access/api-keys
Generate long-lived API keys in the SphereScout Dashboard or via the API, then use them to authenticate programmatic requests to the contact database.
API keys are the recommended way to authenticate server-to-server integrations with SphereScout. Unlike JWT tokens, API keys do not expire by default, so you don't need to manage a token-refresh cycle in your code. You can create multiple keys — one per integration or environment — and revoke any key instantly if it is compromised.
## Create an API key in the dashboard
Log in to your SphereScout account and navigate to **Dashboard → Plans**.
Select the **API Keys** tab within the Plans section. This page lists all existing keys on your account, showing each key's prefix, creation date, and expiry date (if set).
Click **Create API Key**. Optionally set an expiry date if you want the key to auto-expire after a specific period. Leave the field blank to create a key with no expiry.
After creation, the dashboard displays the full API key **once**. Copy it immediately and store it in a secrets manager, environment variable, or another secure location. The dashboard will only show the key prefix (`token_key`) from this point on — the full key cannot be retrieved again.
The full API key is shown only once at creation time. If you lose it, you must revoke the key and create a new one.
## Use an API key in requests
Pass your API key in the `Authorization` header of every request using the `Token` scheme:
```
Authorization: Token YOUR_API_KEY
```
```bash curl theme={null}
curl -G "https://www.spherescout.io/api/companies" \
-H "Authorization: Token YOUR_API_KEY" \
--data-urlencode "countries=US" \
--data-urlencode "email=true"
```
```python Python theme={null}
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://www.spherescout.io/api/companies",
headers={"Authorization": f"Token {API_KEY}"},
params={"countries": "US", "email": "true"},
)
response.raise_for_status()
data = response.json()
print(f"Total contacts: {data['totalCount']}")
```
```typescript TypeScript theme={null}
const API_KEY = process.env.SPHERESCOUT_API_KEY!;
const response = await fetch(
"https://www.spherescout.io/api/companies?countries=US&email=true",
{
headers: { Authorization: `Token ${API_KEY}` },
}
);
if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}
const data = await response.json();
console.log(`Total contacts: ${data.totalCount}`);
```
Store your API key in an environment variable (e.g. `SPHERESCOUT_API_KEY`) and never commit it to source control.
## Manage keys via the API
You can also manage API keys programmatically using the key management endpoints. These endpoints require authentication with an existing API key or a valid JWT access token.
### List API keys
Retrieve all keys on your account. The response includes the key prefix (`token_key`), not the full key value.
```bash curl theme={null}
curl "https://www.spherescout.io/api/user/api-keys" \
-H "Authorization: Token YOUR_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
"https://www.spherescout.io/api/user/api-keys",
headers={"Authorization": f"Token {API_KEY}"},
)
keys = response.json()
for key in keys:
print(key["id"], key["token_key"], key["created"], key["expiry"])
```
**Response fields**
Unique identifier for the API key. Use this ID to revoke the key.
The key prefix (first several characters). The full key value is not retrievable after creation.
ISO 8601 timestamp of when the key was created.
ISO 8601 expiry date, or `null` if the key has no expiry.
### Create an API key
Send a POST request with an optional `expiry` field. If you omit `expiry`, the key has no expiry.
```bash curl theme={null}
# Create a key with no expiry
curl -X POST "https://www.spherescout.io/api/user/api-keys" \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# Create a key that expires on a specific date
curl -X POST "https://www.spherescout.io/api/user/api-keys" \
-H "Authorization: Token YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expiry": "2027-01-01T00:00:00Z"}'
```
```python Python theme={null}
import requests
# No expiry
response = requests.post(
"https://www.spherescout.io/api/user/api-keys",
headers={
"Authorization": f"Token {API_KEY}",
"Content-Type": "application/json",
},
json={},
)
result = response.json()
# Save the full token immediately — it won't be shown again
new_key = result["token"]
key_info = result["api_key"]
print(f"New key ID: {key_info['id']}")
print(f"Full key (save this now): {new_key}")
```
**Request body**
Optional ISO 8601 expiry date and time (e.g. `"2027-01-01T00:00:00Z"`). Omit to create a key with no expiry.
**Response fields**
The full API key value. Store this immediately — it is only returned once.
Metadata about the newly created key.
Unique key ID. Use this to revoke the key later.
Key prefix shown in the dashboard.
ISO 8601 creation timestamp.
Expiry date, or `null` if no expiry was set.
### Revoke an API key
Send a DELETE request with the key ID. Revocation is permanent and takes effect immediately. Any requests using the revoked key will receive a `401 Unauthorized` response.
```bash curl theme={null}
curl -X DELETE "https://www.spherescout.io/api/user/api-keys/KEY_ID" \
-H "Authorization: Token YOUR_API_KEY"
```
```python Python theme={null}
import requests
key_id = "the-key-id-to-revoke"
response = requests.delete(
f"https://www.spherescout.io/api/user/api-keys/{key_id}",
headers={"Authorization": f"Token {API_KEY}"},
)
if response.status_code == 204:
print("Key revoked successfully")
else:
print(f"Error: {response.status_code}")
```
A successful revocation returns `204 No Content` with no response body.
Revoking an API key is irreversible. Any integration using that key will stop working immediately. Rotate credentials by creating a new key before revoking the old one.
# Authenticate requests to the SphereScout API
Source: https://docs.spherescout.io/api-access/authentication
Learn both authentication methods for the SphereScout API: long-lived API keys for integrations and JWT bearer tokens for user-session-based applications.
Every request to a protected SphereScout endpoint must include an `Authorization` header. The API supports two authentication methods: **API keys** for server-to-server integrations and **JWT bearer tokens** for user-session-based applications. Both use the same header format — only the credential type differs.
## Choose an authentication method
| | API keys | JWT tokens |
| - | - | - |
| **Best for** | Server integrations, scripts, automation | User-facing apps, per-user sessions |
| **Lifetime** | No expiry by default (or set a custom expiry) | Short-lived; must be refreshed |
| **Setup** | Generate once in the Dashboard | Login endpoint → access + refresh tokens |
| **Complexity** | Low | Higher (requires token-refresh logic) |
For most integrations, API keys are the simpler and more reliable choice. Use JWT tokens only when your application needs to act on behalf of a specific logged-in user.
***
## API key authentication
API keys are long-lived credentials that you generate in the Dashboard or via the API. Send your API key in the `Authorization` header with the `Token` prefix in every request.
```
Authorization: Token YOUR_API_KEY
```
```bash curl theme={null}
curl "https://www.spherescout.io/api/user/profile" \
-H "Authorization: Token YOUR_API_KEY"
```
```python Python theme={null}
import requests
API_KEY = "YOUR_API_KEY"
response = requests.get(
"https://www.spherescout.io/api/user/profile",
headers={"Authorization": f"Token {API_KEY}"},
)
response.raise_for_status()
profile = response.json()
print(profile)
```
See [API keys](/api-access/api-keys) for how to create, list, and revoke keys.
***
## JWT token authentication
JWT authentication involves three steps: logging in to obtain tokens, using the access token in requests, and refreshing the access token before it expires.
### Step 1 — Obtain tokens
Send a POST request to `/api/auth/login` with your account credentials. The response contains an access token and a refresh token.
**Request**
Your account email address. The field is named `username` in the request body.
Your account password.
```bash curl theme={null}
curl -X POST "https://www.spherescout.io/api/auth/login" \
-H "Content-Type: application/json" \
-d '{
"username": "you@example.com",
"password": "your-password"
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://www.spherescout.io/api/auth/login",
json={
"username": "you@example.com",
"password": "your-password",
},
)
response.raise_for_status()
tokens = response.json()
access_token = tokens["access"]
refresh_token = tokens["refresh"]
print(f"Access token: {access_token[:20]}...")
```
**Response fields**
Short-lived JWT access token. Use this as your Bearer token in subsequent requests.
Long-lived refresh token. Use this to obtain a new access token when the current one expires. Store this token securely — treat it like a password.
Account information returned at login.
Unique account identifier.
Account email address.
First name on the account.
Last name on the account.
Credits available for exports this billing period.
Current subscription plan name.
### Step 2 — Use the access token
Include the access token as a Bearer token in the `Authorization` header of every request:
```
Authorization: Bearer ACCESS_TOKEN
```
```bash curl theme={null}
curl "https://www.spherescout.io/api/companies?countries=DE&email=true" \
-H "Authorization: Bearer ACCESS_TOKEN"
```
```python Python theme={null}
import requests
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(
"https://www.spherescout.io/api/companies",
headers=headers,
params={"countries": "DE", "email": "true"},
)
response.raise_for_status()
data = response.json()
print(f"Total contacts: {data['totalCount']}")
```
### Step 3 — Refresh the access token
Access tokens expire after a short period. When a request returns `401 Unauthorized`, exchange your refresh token for a new access token by calling `POST /api/token/refresh`.
**Request**
The refresh token you received when you logged in.
```bash curl theme={null}
curl -X POST "https://www.spherescout.io/api/token/refresh" \
-H "Content-Type: application/json" \
-d '{"refresh": "YOUR_REFRESH_TOKEN"}'
```
```python Python theme={null}
import requests
def refresh_access_token(refresh_token: str) -> str:
response = requests.post(
"https://www.spherescout.io/api/token/refresh",
json={"refresh": refresh_token},
)
response.raise_for_status()
data = response.json()
return data["access"]
# Call when you receive a 401
new_access_token = refresh_access_token(refresh_token)
```
**Response fields**
A new short-lived access token. Replace the expired token in your application with this value.
A new refresh token, if token rotation is enabled. Update your stored refresh token if this field is present in the response.
***
## Error responses
### 401 Unauthorized
A `401` response means your credential is missing, invalid, or expired.
```json theme={null}
{
"detail": "Authentication credentials were not provided."
}
```
```json theme={null}
{
"detail": "Given token not valid for any token type",
"code": "token_not_valid"
}
```
**What to do:**
* **API key:** Verify the key is correctly copied and has not been revoked in the Dashboard.
* **JWT access token:** The token has expired. Call `POST /api/token/refresh` with your refresh token to get a new access token.
* **JWT refresh token:** If the refresh call also returns `401`, the refresh token has expired or been invalidated. Re-authenticate by calling `POST /api/auth/login` again.
### Full JWT refresh pattern
The following Python example shows a complete pattern for handling token expiry automatically:
```python Python theme={null}
import requests
BASE_URL = "https://www.spherescout.io"
class SphereScoutClient:
def __init__(self, email: str, password: str):
self.email = email
self.password = password
self.access_token: str | None = None
self.refresh_token: str | None = None
def login(self) -> None:
response = requests.post(
f"{BASE_URL}/api/auth/login",
json={"username": self.email, "password": self.password},
)
response.raise_for_status()
data = response.json()
self.access_token = data["access"]
self.refresh_token = data["refresh"]
def _refresh(self) -> None:
if not self.refresh_token:
raise RuntimeError("No refresh token — call login() first")
response = requests.post(
f"{BASE_URL}/api/token/refresh",
json={"refresh": self.refresh_token},
)
response.raise_for_status()
data = response.json()
self.access_token = data["access"]
if "refresh" in data:
self.refresh_token = data["refresh"]
def get(self, path: str, **kwargs) -> dict:
headers = {"Authorization": f"Bearer {self.access_token}"}
response = requests.get(f"{BASE_URL}{path}", headers=headers, **kwargs)
if response.status_code == 401:
self._refresh()
headers["Authorization"] = f"Bearer {self.access_token}"
response = requests.get(f"{BASE_URL}{path}", headers=headers, **kwargs)
response.raise_for_status()
return response.json()
# Usage
client = SphereScoutClient("you@example.com", "your-password")
client.login()
data = client.get("/api/companies", params={"countries": "US", "email": "true"})
print(f"Found {data['totalCount']} contacts")
```
***
## Summary
For server-to-server integrations, use an API key — it requires no token management and works with a single header on every request. Reserve JWT tokens for applications where individual users log in with their own SphereScout credentials.
# SphereScout REST API overview
Source: https://docs.spherescout.io/api-access/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.
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.
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.
For integrations and server-side scripts, use API keys. They are simpler to manage and do not require a token-refresh cycle.
## 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:
```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`);
```
## 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.
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": []
}
```
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
}
```
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"
}
```
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"
}
```
`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.
## 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
Generate and manage long-lived API credentials for server integrations.
Learn the full JWT login flow and token-refresh cycle.
# List and create API keys
Source: https://docs.spherescout.io/api-reference/api-keys/list-and-create-api-keys
/api-reference/openapi.json get /api/user/api-keys/
# List and create API keys
Source: https://docs.spherescout.io/api-reference/api-keys/list-and-create-api-keys-1
/api-reference/openapi.json post /api/user/api-keys/
# Revoke an API key
Source: https://docs.spherescout.io/api-reference/api-keys/revoke-an-api-key
/api-reference/openapi.json delete /api/user/api-keys/{key_id}/
# Post apiauthmagic
Source: https://docs.spherescout.io/api-reference/auth/post-apiauthmagic
/api-reference/openapi.json post /api/auth/magic/
# Post apiauthlogout
Source: https://docs.spherescout.io/api-reference/authentication/post-apiauthlogout
/api-reference/openapi.json post /api/auth/logout/
Logs out the current user
# Post apiauthrequest password reset
Source: https://docs.spherescout.io/api-reference/authentication/post-apiauthrequest-password-reset
/api-reference/openapi.json post /api/auth/request-password-reset/
Send password reset link to email address
# Post apiauthreset password
Source: https://docs.spherescout.io/api-reference/authentication/post-apiauthreset-password
/api-reference/openapi.json post /api/auth/reset-password/
Reset password using the token received via email. Returns new JWT tokens on success.
# Post apiauthsign up
Source: https://docs.spherescout.io/api-reference/authentication/post-apiauthsign-up
/api-reference/openapi.json post /api/auth/sign-up/
Register a new user account
# Post apitokenrefresh
Source: https://docs.spherescout.io/api-reference/authentication/post-apitokenrefresh
/api-reference/openapi.json post /api/token/refresh/
Refresh access token using refresh token
# Post apicompanies reveal contact
Source: https://docs.spherescout.io/api-reference/companies/post-apicompanies-reveal-contact
/api-reference/openapi.json post /api/companies/{company_id}/reveal-contact/
# Get apiplans
Source: https://docs.spherescout.io/api-reference/credits-&-profile/get-apiplans
/api-reference/openapi.json get /api/plans
List all active subscription plans with pricing and credit allowances.
No authentication required. Use this to display plan options to users.
# Get apiuserprofile
Source: https://docs.spherescout.io/api-reference/credits-&-profile/get-apiuserprofile
/api-reference/openapi.json get /api/user/profile/
Get the authenticated user's profile, including remaining credits, subscription plan, and billing period dates.
**Prerequisites:** Authenticated with a valid JWT.
# Patch apiuserprofile
Source: https://docs.spherescout.io/api-reference/credits-&-profile/patch-apiuserprofile
/api-reference/openapi.json patch /api/user/profile/
Get the authenticated user's profile, including remaining credits, subscription plan, and billing period dates.
**Prerequisites:** Authenticated with a valid JWT.
# Get apidownload completed csv
Source: https://docs.spherescout.io/api-reference/download/get-apidownload-completed-csv-
/api-reference/openapi.json get /api/download-completed-csv/{search_id}/
Get a signed download URL for a completed lead export.
**Prerequisites:** Authenticated. The search must have `status=COMPLETED`.
The returned `download_url` is a time-limited signed URL. Download the file before `expires_at`. Returns `410 Gone` if the link has already expired.
# Get apidownload csv
Source: https://docs.spherescout.io/api-reference/download/get-apidownload-csv
/api-reference/openapi.json get /api/download-csv/
Initiate an asynchronous lead export.
**Prerequisites:** Authenticated. Sufficient credits (1 per lead).
Credits are deducted immediately. The response contains a `search_id` — use it to poll `/api/download-status/{search_id}/` until the file is ready.
# Get apidownload status
Source: https://docs.spherescout.io/api-reference/download/get-apidownload-status-
/api-reference/openapi.json get /api/download-status/{search_id}/
Poll the processing status of a lead export.
**Prerequisites:** Authenticated. The `search_id` must belong to the current user.
Keep polling until `status` is `COMPLETED` or `FAILED`. When completed, call `/api/download-completed-csv/{search_id}/` to get the file.
# Post apidownload csv
Source: https://docs.spherescout.io/api-reference/download/post-apidownload-csv
/api-reference/openapi.json post /api/download-csv/
Initiate an asynchronous lead export.
**Prerequisites:** Authenticated. Sufficient credits (1 per lead).
Credits are deducted immediately. The response contains a `search_id` — use it to poll `/api/download-status/{search_id}/` until the file is ready.
# Get apicities
Source: https://docs.spherescout.io/api-reference/geography/get-apicities-
/api-reference/openapi.json get /api/cities/{country_alpha2_code}/
Get a list of Level 3 Locations (Cities) that have associated companies.
# Get apilocationscountries
Source: https://docs.spherescout.io/api-reference/geography/get-apilocationscountries
/api-reference/openapi.json get /api/locations/countries/
Get a list of countries that have companies
# Get apiusersearch history
Source: https://docs.spherescout.io/api-reference/history/get-apiusersearch-history
/api-reference/openapi.json get /api/user/search-history/
List all past lead searches for the authenticated user.
Each entry includes the search ID, credits consumed, processing status, and the filters that were used. Use `id` with the download-status and download-completed-csv endpoints.
# Patch apiusersearch history rename
Source: https://docs.spherescout.io/api-reference/history/patch-apiusersearch-history-rename
/api-reference/openapi.json patch /api/user/search-history/{search_id}/rename/
Rename a saved search history export.
# Post apiusersearch history download delta
Source: https://docs.spherescout.io/api-reference/history/post-apiusersearch-history-download-delta
/api-reference/openapi.json post /api/user/search-history/{search_id}/download-delta/
Start a fresh-data export for a previous search. Uncapped searches export only companies created after the original export. Capped searches create a full-expansion export and charge current total credits minus the original capped credits.
# Post apiusersearch history freshness
Source: https://docs.spherescout.io/api-reference/history/post-apiusersearch-history-freshness
/api-reference/openapi.json post /api/user/search-history/{search_id}/freshness/
Check and cache fresh data availability for a previous search.
# Get apilocationslevel1
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationslevel1
/api-reference/openapi.json get /api/locations/level1/
ViewSet for Level1 locations (states/regions) with filtering support.
Query parameters:
- country: Country alpha2 code (e.g., 'AU', 'FR')
Example: /api/locations/level1/?country=AU
# Get apilocationslevel1
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationslevel1-
/api-reference/openapi.json get /api/locations/level1/{id}/
ViewSet for Level1 locations (states/regions) with filtering support.
Query parameters:
- country: Country alpha2 code (e.g., 'AU', 'FR')
Example: /api/locations/level1/?country=AU
# Get apilocationslevel2
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationslevel2
/api-reference/openapi.json get /api/locations/level2/
ViewSet for Level2 locations (counties/departments) with filtering support.
Query parameters:
- states: State IDs (repeated parameter format, e.g., 'states=46&states=44&states=51')
- country: Country alpha2 code (e.g., 'AU', 'FR')
Example: /api/locations/level2/?states=46&states=44&states=51&country=AU
# Get apilocationslevel2
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationslevel2-
/api-reference/openapi.json get /api/locations/level2/{id}/
ViewSet for Level2 locations (counties/departments) with filtering support.
Query parameters:
- states: State IDs (repeated parameter format, e.g., 'states=46&states=44&states=51')
- country: Country alpha2 code (e.g., 'AU', 'FR')
Example: /api/locations/level2/?states=46&states=44&states=51&country=AU
# Get apilocationslevel3
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationslevel3
/api-reference/openapi.json get /api/locations/level3/
ViewSet for Level3 locations (cities) with filtering support.
Query parameters:
- counties: County IDs (repeated parameter format, e.g., 'counties=123&counties=456')
- country: Country alpha2 code (e.g., 'AU', 'FR')
Example: /api/locations/level3/?counties=123&counties=456&country=AU
# Get apilocationslevel3
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationslevel3-
/api-reference/openapi.json get /api/locations/level3/{id}/
ViewSet for Level3 locations (cities) with filtering support.
Query parameters:
- counties: County IDs (repeated parameter format, e.g., 'counties=123&counties=456')
- country: Country alpha2 code (e.g., 'AU', 'FR')
Example: /api/locations/level3/?counties=123&counties=456&country=AU
# Get apilocationssearch
Source: https://docs.spherescout.io/api-reference/locations/get-apilocationssearch
/api-reference/openapi.json get /api/locations/search/
# Get apipage snapshots
Source: https://docs.spherescout.io/api-reference/page-snapshots/get-apipage-snapshots-
/api-reference/openapi.json get /api/page-snapshots/{alpha2}/
Return the full country page-data payload from DB snapshots.
Shape is equivalent to ui/src/data/categoryCheckout/countries/{alpha2}.json
so Next.js can fetch this instead of reading static JSON files.
Token-gated via PROFESSION_SUMMARY_TOKEN.
# Get apicategories
Source: https://docs.spherescout.io/api-reference/search/get-apicategories
/api-reference/openapi.json get /api/categories/
List or search available business categories (e.g. Restaurant, Bakery, Plumber).
Use the returned `id` values as the `category` parameter in search endpoints. When `q` is provided, results include match metadata for agent disambiguation.
# Get apicompanies
Source: https://docs.spherescout.io/api-reference/search/get-apicompanies
/api-reference/openapi.json get /api/companies/
Search for business leads matching the given filters and return a preview.
**Prerequisites:** Authenticated with a valid JWT.
The response includes `totalCount` which tells you how many credits an export will cost. Use this endpoint to refine filters before calling `/api/download-csv/`.
# Post apitoken|apiauthlogin
Source: https://docs.spherescout.io/api-reference/token/post-apitoken|apiauthlogin
/api-reference/openapi.json post /api/token/|api/auth/login/
Takes a set of user credentials and returns an access and refresh JSON web
token pair to prove the authentication of those credentials.
# Post apiusersearch history retry
Source: https://docs.spherescout.io/api-reference/user/post-apiusersearch-history-retry
/api-reference/openapi.json post /api/user/search-history/{search_id}/retry/
# Manage your SphereScout plan and billing
Source: https://docs.spherescout.io/billing/managing-subscription
View your plan and credit balance, upgrade or downgrade, buy credit top-ups, manage payment methods, and review billing history from the Plans dashboard.
Everything related to your subscription, credits, and billing is available in the **Plans** section of your SphereScout dashboard. This page explains how to use each part of that section.
## View your current plan and credits
Navigate to **Dashboard → Plans** to see your plan overview. The **My Plan** tab shows:
* Your current plan name (Starter, Growth, Pro, or Scale)
* Subscription start date and next billing date
* Monthly price
* Remaining subscription credits for the current period
* Top-up credits available (purchased separately)
* Credits expiring soon
Your total available credits combine your subscription balance and any top-up credits you have purchased. Top-up credits have their own expiry date and are used after your subscription credits are exhausted.
## Upgrade your plan
Upgrading moves you to a higher plan immediately and unlocks a larger credit allowance right away.
Go to **Dashboard → Plans**. Your current plan is shown in the My Plan tab.
Click **Upgrade** or browse to the plan selection view. Choose the plan you want to move to and confirm your selection.
You are redirected to a secure Stripe checkout page. Enter your payment details and confirm the upgrade. The new plan activates immediately after payment.
Once checkout is complete, your new monthly credit allowance is available in your account. You are redirected back to the dashboard.
Upgrade charges are processed immediately at checkout. Your new billing period starts from the upgrade date.
## Downgrade your plan
Downgrading schedules a plan change to take effect at the end of your current billing period. You keep your current plan and credits until that date.
In the Plans section, choose a plan with a lower price than your current one and confirm the downgrade request.
The system schedules the downgrade for the end of your current billing period. A confirmation message shows the date the change takes effect.
You retain full access to your current plan and credit balance until the billing period ends. No changes take effect immediately.
Once a downgrade is scheduled, it enters a lock period and cannot be changed through the dashboard. If you scheduled a downgrade by mistake or want to cancel it, contact [support@spherescout.io](mailto:support@spherescout.io) before the scheduled date.
### Pending downgrade notice
If you have a scheduled downgrade, a notice appears at the top of the Plans section showing:
* Your current plan
* The plan you are moving to
* The date the change takes effect
The button for the target plan is disabled while the downgrade is pending. You cannot select that plan again until the change has processed.
## Buy a credit top-up
If you run out of subscription credits before your monthly reset, you can purchase additional credits as a one-time add-on. Top-up credits are available on any paid plan.
Open the **My Plan** tab in the Plans section of your dashboard.
In the **Buy extra credits** section, enter how many additional credits you want. The minimum purchase is 1,000 credits. A price estimate updates as you type.
Click **Buy credits**. You are redirected to a Stripe checkout page to complete the purchase.
After payment, the top-up credits are added to your balance immediately. They appear separately from your subscription credits and have their own expiry date.
Top-up credits expire independently of your subscription renewal. Check the expiry date in your My Plan tab to avoid losing unused top-up credits.
## View billing history
The **Billing History** tab shows a record of all past payments, including subscription charges, top-up purchases, and any refunds. Each entry shows:
* Description of the charge
* Date
* Amount
* Payment status
* A link to download the invoice or receipt (where available)
To access billing history, go to **Dashboard → Plans → Billing History**.
## Manage payment methods
The **Payment Methods** tab lets you view, add, and manage the cards or digital wallets linked to your account.
* **Default payment method** — the card or wallet marked as default is charged automatically for subscription renewals and top-up purchases.
* **Set a new default** — click **Set as default** next to any saved payment method to make it the primary method.
* **Add a payment method** — use the add payment method option to save a new card. SphereScout uses Stripe to handle all payment data securely.
To manage payment methods, go to **Dashboard → Plans → Payment Methods**.
## Legacy plans
If you subscribed before the current plan lineup was introduced, your dashboard shows a **Legacy plan** notice in the My Plan tab. Legacy plans are no longer available for new subscriptions, but you can keep your current plan and pricing as long as your subscription remains active.
If you cancel or downgrade off a legacy plan, you cannot return to it later — only current plans are available for new subscriptions. Contact [support@spherescout.io](mailto:support@spherescout.io) before making changes if you want to confirm what happens to your pricing.
## Cancel your subscription
There is no self-serve cancellation button in the dashboard. The recommended approach is to downgrade to the free tier, which schedules the removal of your paid plan at the end of your current billing period.
If you need to cancel immediately or have questions about your billing, contact [support@spherescout.io](mailto:support@spherescout.io).
Downgrading to the free tier rather than cancelling outright lets you keep your account and any saved searches. You can reactivate a paid plan at any time without losing your account history.
## Advanced billing management
For advanced billing tasks — such as updating your billing address, downloading tax invoices, or managing VAT details — you can access the Stripe customer portal through the Plans section. The portal is managed by Stripe and gives you direct access to your billing records.
# Buy business contacts without a subscription
Source: https://docs.spherescout.io/billing/one-time-purchase
Buy a specific set of business contacts with a single payment and no subscription. Select a category and location, get a price quote, then download your CSV.
A one-time purchase lets you buy a precisely defined set of business contacts with a single Stripe payment and no recurring charges. You select the industry category and location you want to target, receive a price quote based on the available contacts, complete checkout, and download your file. This path suits project-based outreach or one-off campaigns where you know exactly what you need.
## When to choose a one-time purchase
Choose a one-time purchase when you:
* Have a specific campaign with a fixed contact target
* Want to reach a single category or location without committing to a monthly plan
* Are testing a new market before deciding on a subscription
* Need a fast, defined dataset for a client or project
There are no recurring charges. You pay once and receive access to your file for a limited period after purchase.
Choose a subscription when you:
* Run outreach on a regular monthly cadence
* Need contacts across multiple categories or locations over time
* Want the lowest per-contact cost through a monthly credit allowance
See [subscription plans and pricing](/billing/plans) for a full comparison.
## How to buy contacts
From the SphereScout homepage or directory, navigate to the **Buy Email Database** section. You can also browse to a specific category or location page and use the direct purchase option shown there.
Use the filters to choose the business category and geographic region you want to target. You can narrow by country, state or region, and business type. The more specific your filters, the more targeted your contact list will be.
Click **Get Instant Price** to submit your filter selection. SphereScout searches the database and calculates how many contacts match your criteria along with the price for that dataset.
Quotes are generated asynchronously — the system searches the database in the background and returns a result within a few seconds. If you submit a quote request and the page is still loading, wait a moment or refresh the page to see the result. You do not need to resubmit.
Once the quote is ready, you see a summary showing:
* Total number of matching business contacts
* Breakdown of email addresses and phone numbers available
* Price (excluding VAT; final tax is calculated at Stripe checkout based on your country)
If the results do not match what you need, click **Modify Search** to adjust your filters and request a new quote.
Enter the email address where you want to receive your download link, then click through to the Stripe checkout page. Payment is processed securely by Stripe. SphereScout does not store your payment details.
After payment is confirmed, your contact file is prepared and a download link is sent to the email address you provided. You can also download directly from the confirmation page.
The download link expires after 7 days. Download your file promptly after purchase. If your link expires before you download, contact [support@spherescout.io](mailto:support@spherescout.io) for assistance.
Your contacts are delivered as a CSV file compatible with Excel, Google Sheets, and most CRM import tools.
## What your file includes
Each contact record in a one-time purchase contains the same fields available through a subscription:
* Company name and website
* Email address (where available)
* Phone number (where available)
* Business address and location
* Social media profile links
Coverage of email and phone fields varies by business category and region. The quote summary shows exact email and phone counts for your specific selection before you pay.
## No recurring charges
A one-time purchase is a single transaction. No subscription is created, no recurring billing is set up, and your card is charged only once. If you want to buy additional contacts in the future, you go through the same purchase flow again.
If you find yourself buying contacts regularly, a subscription plan offers a lower per-contact cost and a faster workflow. The Growth plan at \$99/month gives you 40,000 credits — enough for frequent outreach without managing individual purchases. See [subscription plans](/billing/plans) for details.
# SphereScout subscription plans and pricing
Source: https://docs.spherescout.io/billing/plans
Compare Starter, Growth, Pro, and Scale monthly plans. Understand how credits work, how to sign up, and when to choose a subscription over a one-time purchase.
SphereScout subscriptions give you a monthly allowance of credits you can spend on business contacts across any category and location in our database. Each credit unlocks one contact record. Credits reset at the start of every billing period, so you get a fresh allowance every month without carrying over unused credits from the previous cycle.
## Plans at a glance
**\$49 / month**
10,000 credits per month
Paid access for light prospecting and small teams.
\~\$4.90 per 1,000 contacts
**\$99 / month**
40,000 credits per month
For recurring prospecting workflows.
\~\$2.48 per 1,000 contacts
**\$199 / month**
100,000 credits per month
For teams scaling outbound campaigns.
\~\$1.99 per 1,000 contacts
**\$499 / month**
300,000 credits per month
For high-volume sales teams and agencies.
\~\$1.66 per 1,000 contacts — highest volume
When you create a free account, you receive 100 credits at no cost — no credit card required. Use them to explore the database and test data quality before committing to a plan.
## How credits work
Every subscription plan comes with a fixed number of credits that renew automatically each month on your billing date. When you export or download a contact record, one credit is deducted from your balance.
* **Monthly reset** — credits refresh at the start of each billing period. Unused subscription credits do not roll over.
* **Credit top-ups** — if you run out of credits before your next reset, you can purchase additional credits as a one-time add-on. Top-up credits have their own expiry date, separate from your monthly cycle. See [managing your subscription](/billing/managing-subscription) for details.
* **Free tier** — new accounts start with 100 free credits. These are enough to preview contact quality across different categories and locations.
## What each contact includes
Every contact record you unlock with a credit includes:
* Company name and website
* Email address and phone number (coverage varies by business)
* Social media profiles
* Business address and location data
* Advanced filtering attributes such as Google Maps ratings and social media presence
## How to sign up for a plan
Go to the SphereScout sign-up page and create a free account. You receive 100 free credits immediately — no payment details needed at this stage.
Use your free credits to search contacts by category and location. This lets you verify the data quality and coverage for your target market before you pay.
Navigate to the **Plans** section in your dashboard. Select the plan that matches your monthly volume and click **Get started**. You are redirected to a secure Stripe checkout page.
Enter your payment details on the Stripe checkout page. Once payment is confirmed, your new credit balance is available immediately and your billing period starts.
## Subscription vs one-time purchase
SphereScout offers two ways to access contacts. Choose based on how often you need data.
A subscription gives you a recurring monthly credit allowance at a lower per-contact cost. It works best when you:
* Run outreach campaigns on a regular cadence
* Need contacts across multiple categories or locations each month
* Want to build prospecting lists incrementally over time
* Require access to advanced filtering options
Credits reset every month, so you always have a fresh budget for new contacts without managing one-off purchases.
A one-time purchase lets you buy a defined set of contacts for a single payment, with no recurring charges. It works best when you:
* Have a specific campaign with a fixed contact target
* Do not need contacts on an ongoing basis
* Want to test a new market before committing to a subscription
See [buying contacts without a subscription](/billing/one-time-purchase) for the full purchase flow.
## Need more contacts?
If you need more contacts than your plan provides, you can buy additional credits as a one-time top-up at any time once you have an active subscription. Top-up credits are added on top of your monthly allowance and have their own expiry date. See [managing your subscription](/billing/managing-subscription) for the top-up flow.
For custom data delivery, volume pricing, or dedicated support, contact the SphereScout team at [contact@spherescout.io](mailto:contact@spherescout.io).
## Legacy plans
If you subscribed to an older plan, you keep your current pricing and credit allowance for as long as your subscription remains active. Legacy plans are no longer offered to new subscribers and do not appear in the public plan list. Your dashboard shows a **Legacy plan** notice if you are on one of these plans.
# What's included in a SphereScout contact record
Source: https://docs.spherescout.io/concepts/contacts
SphereScout contacts include name, email, phone, location, website, and social profiles. Learn what each field contains and how data accuracy is maintained.
Every contact in SphereScout represents a single local business — one physical location, one set of contact details, one category. When you export contacts, you receive a CSV file where each row is one business record. Not every business has every field filled in; data availability varies by location and business type. Understanding what each field contains helps you set the right expectations before you export and build your outreach list.
## Data fields in each contact record
Each contact record can include up to 12 fields. Fields marked as optional may be blank for some contacts.
The registered or trading name of the business.
The primary contact email address for the business. Validated monthly for deliverability.
The main business phone number, including country code where available.
The city where the business operates.
The country of the business location.
The state, province, or region where the business is located.
The ZIP or postal code of the business address.
The business's primary website URL, where available.
A link to the business's LinkedIn page, where available.
A link to the business's Twitter/X profile, where available.
A link to the business's Instagram profile, where available.
A link to the business's Facebook page, where available.
## Business categories
Every contact in SphereScout is tagged with a primary business category — for example, Restaurant, Lawyer, Dentist, or Plumber. Categories let you target a specific industry segment when you search and are one of the most important filters you can apply. A single business has one primary category, which reflects its main line of activity.
Use the category filter to restrict your search to the exact type of business you want to reach. You can select multiple categories in a single search.
## Data quality and accuracy
SphereScout is built on a database of 50M+ local business contacts across 20+ countries. The data team applies the following quality controls:
Email addresses are validated every month for deliverability. Records that fail validation are flagged or removed, keeping the database fresh and reducing bounce rates.
All data in SphereScout is collected and maintained in compliance with GDPR requirements. The database covers business contact information rather than personal consumer data, and usage rights are unlimited upon export.
Beyond monthly email validation, the database is continuously updated to reflect new businesses, closures, and contact changes across all covered countries.
## Field availability varies by contact
Not every business in the database has every field populated. Email and phone coverage in particular varies by country and business type — some markets have higher email coverage than others, and some business categories publish contact details more consistently.
Use the **presence filters** (has email, has phone, has website, and so on) before exporting to ensure every credit you spend produces a contact with the fields you need. See [Search filters](/concepts/filters) for details.
## CSV column structure
When you export contacts, the CSV file uses the following column headers:
| CSV Column | Description |
| - | - |
| `Company Name` | Business name |
| `Email` | Primary email address |
| `Phone` | Main phone number |
| `City` | City of operation |
| `Location` | Region or state |
| `Country` | Country |
| `Postal Code` | ZIP or postal code |
| `Website` | Business website URL |
| `LinkedIn` | LinkedIn page URL |
| `Twitter / X` | Twitter/X profile URL |
| `Instagram` | Instagram profile URL |
| `Facebook` | Facebook page URL |
| `Last Seen` | Date the record was last verified or updated |
The CSV is ready to import into any CRM, email marketing platform, or spreadsheet tool without additional formatting.
# Understanding SphereScout credits and usage
Source: https://docs.spherescout.io/concepts/credits
Credits are the currency you spend to export contacts from SphereScout. Learn how credits work, when they reset, and what to do when you run out.
Credits are the unit of measurement for contact exports in SphereScout. Every time you export a contact record, one credit is deducted from your balance. Your plan gives you a fixed pool of credits each month, and that balance resets on your billing date — unused credits do not carry over. Understanding how credits work helps you plan your outreach campaigns without interruption.
## What counts as one credit
One credit equals one exported contact record. When you run a search and export 500 contacts, SphereScout deducts 500 credits. Browsing search results, previewing contacts in the dashboard, and running searches without exporting are all free — credits are only consumed at the point of export.
## Viewing your credit balance
Your current credit balance is always visible in the top bar of your dashboard. The display shows:
* **Subscription credits remaining** — credits from your current monthly plan
* **Purchased credits remaining** — one-time top-up credits, if you have any
Both pools are available to use at any time. SphereScout draws down your subscription credits first, then uses purchased credits once your subscription balance reaches zero.
## Monthly credit reset
Subscription credits reset on the same date each month — your billing date. The reset brings your balance back to your plan's full monthly allocation. Credits that you did not use in the previous month are forfeited; they do not roll over to the next cycle.
Purchased (one-time) credits do **not** reset monthly. They remain in your account until you use them, regardless of billing cycles.
## Subscription plans and credit allocations
SphereScout offers four subscription tiers. All plans include access to every search filter, all export formats, and unlimited searches.
| Plan | Monthly credits | Price |
| - | - | - |
| Starter | 10,000 | \$49 / month |
| Growth | 40,000 | \$99 / month |
| Pro | 100,000 | \$199 / month |
| Scale | 300,000 | \$499 / month |
Need more contacts than your plan provides? Once you have an active subscription, you can buy a one-time credit top-up at any time. See [managing your subscription](/billing/managing-subscription) for the top-up flow.
## What happens when you run out of credits
When your credit balance reaches zero, exports stop. You can still search and preview results, but the export button will be disabled until you replenish your balance.
You have two options to restore access:
Purchase a one-time block of credits to continue exporting without waiting for your monthly reset. Top-ups are immediately added to your purchased credit balance.
Switch to a higher plan tier to get a larger monthly credit allocation. Your new plan credits become available immediately on upgrade.
## Subscription credits vs. purchased credits
SphereScout maintains two separate credit pools in your account.
These credits come from your active monthly plan. They refresh automatically on your billing date and are the primary source of credits for most users. Subscription credits expire at the end of each billing cycle if unused.
These are credits you buy as a one-time purchase outside your subscription. They do not expire and are not affected by billing cycles. SphereScout uses your subscription credits first; purchased credits only draw down after your subscription balance is exhausted.
Cancelling your subscription removes access to subscription credits immediately. Purchased credits remain in your account and can still be used after cancellation.
## How to make the most of your credits
Use filters to target exactly the contacts you need. A tighter search means fewer irrelevant records in your export, so your credits go further.
Filter for contacts that have an email, phone, or specific social profiles before exporting. This ensures every credit you spend produces a contact you can actually reach.
Keep an eye on the credit counter in the dashboard top bar, especially mid-month during active campaigns. Top up early to avoid campaign interruptions.
If you exhaust your credits before your billing date every month, upgrading your plan is more cost-effective than buying repeated top-ups.
# Search filters in SphereScout explained
Source: https://docs.spherescout.io/concepts/filters
Narrow 50M+ contacts by category, location, and presence filters in SphereScout. Learn how each filter works, how they combine, and tips for efficient searches.
Filters are how you turn SphereScout's entire database into a precise, targeted list. You can apply filters to narrow by business type, geography, and the specific contact details each business has on file. All filters work together with AND logic — every filter you add further restricts the results to contacts that satisfy all your criteria simultaneously. The more filters you apply, the smaller and more targeted your result set becomes.
## Filter categories
### Category (business type)
The category filter lets you select one or more business types. Categories represent the primary industry or profession of the business — for example, Restaurant, Dentist, Real Estate Agent, or Electrician.
* You can select multiple categories in a single search. The results will include businesses that match **any** of the selected categories.
* Each business is tagged with a single primary category, so a business will only appear in results when its primary category matches your selection.
Start your search by picking a category first. It is the fastest way to cut the database down to the industry segment you want to reach.
### Country
The country filter sets the geographic scope of your search. Most searches require a country selection before other location filters become available.
* SphereScout covers 20+ countries across multiple continents.
* Selecting a country unlocks the region/state and city filters for that country.
### Region / State
The region filter narrows your results to a specific state, province, or administrative region within the selected country — for example, California in the United States or Île-de-France in France.
* You can select multiple regions within the same country.
* Leaving this filter blank returns results from the entire country.
### City
The city filter narrows results to a specific city or town within a region. Use it when you want to target a local market precisely — for example, only businesses in Austin, Texas rather than all of Texas.
* You can select multiple cities.
* City filtering is available after you have selected a country. Selecting a region first will narrow the list of available cities.
You do not have to select filters in strict order, but choosing Country → Region → City in sequence gives you the most relevant options at each step.
***
## Presence filters
Presence filters let you restrict results to contacts that have a specific piece of contact information on file. Use them to guarantee that every exported contact has the data you need to run your outreach.
Only return businesses that have a validated email address on file.
Only return businesses that have a phone number on file.
Only return businesses that have a website URL on file.
Only return businesses with a Facebook page on file.
Only return businesses with a Twitter/X profile on file.
Only return businesses with a LinkedIn page on file.
Only return businesses with an Instagram profile on file.
Enabling multiple presence filters at once can significantly reduce your result count. For example, requiring both email **and** phone will exclude any business that has only one of the two. Start with the single most important field for your campaign.
***
## Additional filters
### Main activity only
When enabled, this filter excludes secondary or satellite locations from the results. Some businesses operate across multiple locations and appear in the database more than once. Enabling "main activity only" keeps one primary record per business and removes branch or franchise duplicates.
Use this filter when you want to contact a business once rather than reaching the same organisation through multiple locations.
### Exclude closed businesses
SphereScout's database includes records that have been flagged as closed based on data updates. By default, these records may appear in search results. Enable this filter to remove closed businesses and export only currently operating locations.
Enabling "exclude closed businesses" is recommended for most outreach campaigns. It avoids wasted credits on contacts that are no longer active.
***
## How filters combine
All filters in SphereScout use AND logic. This means a contact must satisfy every filter you have set in order to appear in your results. For example:
* Category: **Dentist** AND Country: **United States** AND Region: **Texas** AND Has Email: **true**
This search returns only dentists in Texas (USA) that have a validated email address — not dentists elsewhere, not Texas businesses in other categories, and not dentists without an email.
***
## Tips for effective filtering
Begin with just a category and country. Check the result count, then add a region or city to narrow further. This approach helps you understand how large each market segment is before you commit to a narrow filter set.
If your campaign depends on email outreach, enable "has email" before exporting. If you plan to call, enable "has phone." This prevents you from spending credits on contacts that cannot be reached through your chosen channel.
Enable "main activity only" to avoid receiving the same franchise or chain location multiple times under different regional records. This is especially useful for categories like fast food, retail, or hotel chains.
Always enable the closed business exclusion filter when building a list for active outreach. Contacting closed businesses wastes credits and can hurt your sender reputation.
Once you are satisfied with your filter combination and the result count, save your search before exporting. This lets you re-run the same search next month to capture newly added contacts without rebuilding your filters from scratch.
# Frequently asked questions about SphereScout
Source: https://docs.spherescout.io/faq
Answers to the most common questions about SphereScout credits, data quality, exports, billing, and API access for B2B contact database users.
SphereScout is designed to be straightforward, but you may have questions as you get started or scale your outbound campaigns. This page covers the questions users ask most often — from how credits work and what the data includes, to GDPR compliance and re-downloading past exports.
## Getting started
SphereScout is a B2B contact database with over 50 million local business contacts across 20+ countries. You search by business category — such as restaurants, lawyers, dentists, or contractors — and filter by country, state/region, and city. You can also narrow results by contact type: only show businesses that have an email address, a phone number, a website, or a specific social profile. When you find the right segment, you export the results to CSV with one click.
SphereScout is built for sales teams, marketers, and agencies that need verified, ready-to-use contact data without complex data pipelines.
Create a free account at [spherescout.io](https://www.spherescout.io). As soon as your account is active, your dashboard shows 100 free credits — no credit card required. Run a search, apply filters, and export up to 100 contacts to see the data quality firsthand before you decide on a plan.
No. You can create an account and export your first 100 leads without entering any payment details. A credit card is only required when you purchase a subscription plan, buy a credit top-up, or make a one-time purchase.
SphereScout covers 20+ countries, with business contacts spanning North America, Europe, and beyond. You can browse available countries directly in the dashboard using the country filter on the search page. Coverage depth varies by country — larger markets tend to have higher contact volumes and more complete data fields.
## Credits and billing
One credit equals one exported contact record. When you run a search and export 200 contacts, 200 credits are deducted from your balance. Searching, browsing, and previewing results in the dashboard are all free — credits are only consumed when you download an export.
Re-downloading a previous export within 30 days does **not** use additional credits. See the exports section below for details.
When your credit balance hits zero, exports are paused. You can still search and preview results, but the export button is disabled until you add more credits. You have two options:
* **Buy a credit top-up** — a one-time purchase of additional credits added to your account immediately.
* **Upgrade your plan** — switch to a higher tier and get a larger monthly credit allocation right away.
Your monthly subscription credits reset on your billing date each month.
Yes. Credit top-ups let you purchase an additional block of credits without changing your subscription plan. Top-up credits do not expire and are not tied to your billing cycle — they stay in your account until you use them. SphereScout draws down your subscription credits first, then uses top-up credits once your subscription balance runs out.
A **subscription** gives you a set number of credits each month that reset on your billing date. It's the best fit for teams running continuous outbound campaigns. SphereScout offers four subscription tiers:
| Plan | Monthly credits | Price |
| - | - | - |
| Starter | 10,000 | \~\$49 / month |
| Growth | 40,000 | \~\$99 / month |
| Pro | 100,000 | \~\$199 / month |
| Scale | 300,000 | \~\$499 / month |
A **one-time purchase** is a single transaction for a specific list, with no recurring charge. It's ideal for a single campaign or project where you know exactly how many contacts you need. You pay once and download your file.
If you run campaigns regularly, a subscription plan is more cost-efficient per contact. For occasional use, a one-time purchase keeps things simple.
Yes. You can cancel your subscription at any time from your account settings. Cancellation stops future billing, but your credits remain available until the end of the current billing period. Purchased (top-up) credits stay in your account after cancellation and can still be used.
Unused subscription credits expire at the end of your billing period. They do not carry over to the next month or convert to purchased credits.
## Data quality
SphereScout maintains a 95% accuracy rate across the database. Email addresses are validated monthly to check deliverability, so you can expect the contact data you export to be current and actionable. Records that fail validation checks are flagged or removed during each refresh cycle, keeping the database clean over time.
Yes. SphereScout is GDPR compliant. The database is built and maintained with data protection regulations in mind, and all contact records are sourced and processed to meet compliance requirements. If you have specific questions about data processing or need documentation for your own compliance needs, contact [support@spherescout.io](mailto:support@spherescout.io).
The database is continuously updated and quality-checked. Email addresses go through a validation cycle monthly to verify deliverability. New contacts are added as they are discovered, and existing records are refreshed when changes are detected. You can use the data freshness feature in your dashboard to check whether new contacts have been added to a specific segment since your last export.
## Exports and downloads
All exports are delivered as CSV files. You can open them directly in Excel, Google Sheets, or any spreadsheet application, and import them into most CRMs and outbound sequencers without additional conversion. Each row represents one business contact and includes the fields available for that record — such as company name, email, phone, city, website, and social media links.
Export download links are available for 30 days from the date of export. After 30 days, the link expires. If you need the file after that point, you would need to run the same search again and export, which will consume credits.
Yes. Your export history is saved in the dashboard, and you can re-download any export within 30 days of the original export date. Re-downloading does not use any additional credits — you only pay credits once, at the time of the initial export.
Go to **Export History** in your dashboard to see all your past exports and access their download links.
Data freshness is a feature that lets you check whether new contacts have been added to a specific segment — defined by category and location — since the last time you exported it. Instead of re-exporting the entire segment and paying credits for contacts you already have, you run a freshness check to see if there are net-new records. If there are, you can download only the new contacts, called a delta, without duplicating records from your previous export.
## API
Yes. SphereScout provides API access so you can query the contact database programmatically. The API lets you search for contacts, apply filters, and retrieve results directly from your own applications or data pipelines — without using the web dashboard. API usage is tied to your account credits, the same way dashboard exports are.
An API key is a unique token that authenticates your requests to the SphereScout API. It tells the API which account the request belongs to and deducts credits from your balance accordingly.
To get your API key:
1. Log in to your dashboard.
2. Navigate to **Dashboard → Plans** and open the **API Keys** tab.
3. Generate a new key and copy it immediately — for security reasons, it is only shown once.
Include your key in the `Authorization` header of every API request. Keep it private and do not share it or commit it to version control.
If your API key is compromised, revoke it immediately from the API Keys section in your dashboard and generate a new one.
***
Still have a question that isn't answered here? Email the SphereScout support team at [support@spherescout.io](mailto:support@spherescout.io) and they'll get back to you.
# Get updated contacts with SphereScout data freshness
Source: https://docs.spherescout.io/guides/data-freshness
Use SphereScout's data freshness feature to check for new contacts since your last export and download only the additions as a delta file, saving credits.
SphereScout's database is continuously updated. Businesses are added, contact details are updated, and new records become available on an ongoing basis. If you exported a list weeks ago, there may be contacts that now match your original filters but were not in the database at the time of your export.
The data freshness feature lets you check for new contacts on any saved export and download only the additions — a delta file — without paying to re-export your entire original list.
## Check for new data
Navigate to the [History page](/guides/export-history) from the dashboard navigation.
Locate the row for the original export you want to check. The **New data** column shows the current freshness status for each export.
If you have not checked freshness before — or if it is time to check again — a **Check for updates** button appears in the **New data** column. Click it.
SphereScout compares your original export's filters and baseline date against the current database and reports how many new contacts are available.
The freshness check has a rate limit. Once you run a check, you cannot run another one for that export until the cooldown period has passed. The next available check time is shown in the **New data** column after you hit the limit. If updates were already found in a previous check, you can still download the update file even while the check is rate-limited.
After the check completes, a notification appears confirming whether new contacts are available:
* **No fresh data found** — Your export is already up to date. No new contacts match your original filters since the export date.
* **Updates found** — A count of new contacts is shown as a green badge in the **New data** column, for example: "+124 update".
## Download a delta file
If new contacts are available, you can download just the additions without re-exporting your entire original list.
When updates are available, the Actions column shows a button labeled **Update +**. Click it to open the download confirmation dialog.
The dialog shows the number of new contacts and the credit cost. Delta downloads cost one credit per new contact — the same rate as a regular export, but only for the new records.
Confirm to start generating the delta file.
Delta downloads cost credits equal to the number of new contacts. This is separate from the credits you spent on the original export.
Delta files are generated asynchronously, the same way as regular exports. While the file is being prepared, a badge reading **Update file is being prepared** appears in the History row. Once the file is ready, the download starts automatically.
The new delta file is added as a version under your original export row. Expand the row to see it listed alongside the original file. It is labeled **Update file** to distinguish it from the **Original file**.
## What is in a delta file
A delta file has the same columns as a regular export — name, email, phone, city, country, region, zipcode, website, LinkedIn, Twitter, Instagram, Facebook, first\_seen, last\_seen — but it contains only the contacts that are new since your original export. It does not repeat contacts already in your original file.
## Freshness concepts
You can only run a freshness check once per period per export. After checking, the button shows the next available check time. You can still download any updates already found while waiting for the cooldown to pass.
A delta file contains only new contacts since your original export date. It is cheaper than re-exporting the full list when only a fraction of contacts are new. Use a full re-export when you want a completely fresh snapshot of all current matches.
Delta files expire 30 days after they are created, the same as regular exports. You can re-download them free within that window from the expanded row in History.
The number shown in the update badge is the count of new contacts that will be charged. This is the exact credit cost you will pay if you proceed with the delta download.
# Manage past exports in your SphereScout history
Source: https://docs.spherescout.io/guides/export-history
Find, re-download, rename, and review all your past SphereScout exports from the History page, including file versions and expiry dates.
Every export you create in SphereScout is saved to your History page. From there you can re-download files, rename exports for easier reference, check expiry dates, and see individual file versions. This page explains how to use all of those features.
## Find your History page
In the dashboard navigation, click **History**. This takes you to `/dashboard/history`, which lists all your saved exports in a table.
The summary cards at the top of the page show your total number of saved exports and the total business contacts you have exported across all time.
## What the history table shows
Each row in the table represents one original export. The columns are:
| Column | What it shows |
| - | - |
| **Export** | The categories and location from your original search (or a custom name if you have renamed it) |
| **Business Contacts** | Number of contacts in the latest file for that export |
| **New data** | Whether fresh contacts are available since your last export — see [Data Freshness](/guides/data-freshness) |
| **Latest file** | Date of the most recent file, how many file versions exist, and when the download link expires |
| **Actions** | Download button, or update button if fresh data is available |
## Re-download an existing export
To download a file you have already exported:
1. Find the row in the history table.
2. Click **Download** in the Actions column.
Re-downloading the same file is free. No credits are deducted. The download is available as long as the link has not expired.
Download links expire 30 days after the export was created. Once a link expires, you cannot download that file again. The expiry date is shown in the **Latest file** column. If the link has expired, the Download button is replaced with a dash and the file is marked **Expired**.
## Rename an export
By default, each row is labeled with the categories and location from your original search. You can replace this with a custom name that is easier to scan.
On the row you want to rename, click the pencil icon to the right of the export label. An inline text field appears.
Type a name up to 120 characters. For example: "Q3 Restaurant Campaign — California".
Press **Enter** or click the checkmark button to save. The row now shows your custom name instead of the auto-generated label.
To remove a custom name and go back to the auto-generated label, open the rename field and clear the text, then save.
## Expand a row to see file versions
Each original export can have multiple file versions — the original full file, plus any delta (update) files you have downloaded since. Click anywhere on a row to expand it.
The expanded view shows:
* The date the export was originally created
* The date of the last freshness check (if you have run one)
* All file versions listed individually, each showing:
* File date
* File type: **Original file** or **Update file**
* Number of contacts in that file
* Availability or expiry date
* A download button (if the link has not expired)
Each file version has its own expiry date. An update file created later in the 30-day window will expire later than the original file.
## What happens when a download link expires
After 30 days, the download link for a file becomes inactive. The file entry remains visible in History so you can see what you previously exported, but you cannot download it again.
If you need the contacts again after expiry, you can run a new search with the same filters and download a fresh export — this will cost credits for the new set of contacts.
# Export business contacts to CSV from SphereScout
Source: https://docs.spherescout.io/guides/exporting
How to download your search results as a CSV file, what columns are included, how credits are charged, and how long your download link stays active.
After you have filtered your search to the right set of contacts, you can export the full list as a CSV file. Exports are processed asynchronously — SphereScout queues the job, generates the file, and makes it available for download once it is ready. This page covers the full export process, what the file contains, and what happens to your download link over time.
## Export your contacts
Apply your filters on the dashboard until you have the contact list you want. Check the total count shown above the preview table — this is the number of contacts that will be in your export and the number of credits that will be charged.
Click the **Download** button. A confirmation dialog appears showing the total contact count, credit cost, and available export formats. Review the details and confirm to start the export.
Each export costs credits equal to the number of contacts in your results. Make sure you are satisfied with your filters before confirming — credits are deducted when the export job starts.
Exports are generated asynchronously. After you confirm, the job enters a **Processing** state while SphereScout compiles the file. The status updates to **Completed** when the file is ready.
For most searches this takes a few seconds to a couple of minutes depending on list size. You do not need to stay on the page — the export is saved to your [History](/guides/export-history) automatically.
Once the status shows **Completed**, the download starts automatically or you can click the download button to save the file manually. The file is a CSV you can open in Excel, Google Sheets, or import directly into your CRM or email tool.
## What is in the CSV
Each row in the export represents one business contact. The columns included are:
| Column | Description |
| - | - |
| `name` | Business name |
| `email` | Email address |
| `phone` | Phone number |
| `city` | City |
| `country` | Country |
| `region` | State, region, or department |
| `zipcode` | Postal / zip code |
| `website` | Website URL |
| `linkedin` | LinkedIn profile URL |
| `twitter` | Twitter/X profile URL |
| `instagram` | Instagram profile URL |
| `facebook` | Facebook page URL |
| `first_seen` | Date the contact first appeared in the database |
| `last_seen` | Date the contact was last confirmed in the database |
Columns for social media and contact details are left blank when SphereScout does not have that data for a given business.
## Credits and expiry
Each export costs one credit per contact. An export of 500 contacts costs 500 credits. The exact cost is shown in the confirmation dialog before you proceed.
Download links expire 30 days after the export is created. After that, you can no longer download the file. The expiry date is shown in your [Export History](/guides/export-history).
If you need to download the same file again within the 30-day window, go to your [Export History](/guides/export-history) and click **Download** on that row. Re-downloading an existing file is free — no additional credits are charged.
# Search SphereScout's business contact database
Source: https://docs.spherescout.io/guides/searching
Learn how to use SphereScout's filters to find the exact business contacts you need — by category, location, and contact detail availability.
The SphereScout dashboard gives you real-time access to millions of business contacts. As soon as you adjust a filter, the result count updates instantly so you can gauge list size before you commit to an export. This guide walks you through every filter available and how to combine them effectively.
## Open the dashboard
Navigate to [spherescout.io](https://spherescout.io) and sign in. You land directly on the search dashboard — the main interface for building your contact list.
## Run a search
Click the **Business Categories** field and type to search, or browse the list. The category filter is multi-select, so you can combine related industries in a single search.
**Example:** Select "Restaurant" and "Café" together to find all food and beverage operators in your target area.
Start with a broad category first to see total volume. You can always add more specific categories or apply location filters to narrow results down.
Open the **Country** selector and pick your target market. You can select a single country or multiple countries if your campaign spans borders.
**Example:** Select "United States" for a US-only campaign, or select "United States" and "Canada" for a North American list.
Once you select a country, the **State/Region** and **City** fields become available. Use these to focus on a specific geographic area.
* **State/Region** — Filter to one or more states, counties, or departments depending on the country.
* **City** — Focus on contacts within a specific city.
**Example:** Select "California" as the region, then "San Francisco" as the city to target businesses in that metro only.
More specific locations take priority. If you select a city, results are scoped to that city even if you also have a region selected.
Under **Contact Details**, toggle the filters for the contact information you need. Each filter limits results to businesses that have that specific data point in the database.
| Filter | What it does |
| - | - |
| Has Email | Only contacts with an email address |
| Has Phone | Only contacts with a phone number |
| Has Website | Only contacts with a website |
| Has Facebook | Only contacts with a Facebook page |
| Has Twitter/X | Only contacts with a Twitter/X profile |
| Has LinkedIn | Only contacts with a LinkedIn page |
| Has Instagram | Only contacts with an Instagram profile |
Enable **Has Email** before downloading to ensure every contact in your export is reachable by email. This prevents exporting records you can't use.
Enable **Primary activity only** to exclude secondary or satellite business locations. When this is on, results include only businesses where your selected category is their main line of work — not businesses that also happen to operate in that category.
This is useful when you need tightly focused lists. Keep it off when you want maximum coverage.
The total number of matching contacts appears at the top of the results area as you apply filters. A preview table shows the first few records — business name, email, phone, city, and country — so you can verify data quality before downloading.
When you are satisfied with the count and the sample data, you are ready to export.
## Tips for better searches
Begin with only a category and country. Check the total count, then add region or city filters to bring it to the size you need. This avoids accidentally over-filtering and missing contacts.
Always enable at least "Has Email" or "Has Phone" before exporting. Exporting contacts without the data point you plan to use wastes credits on unreachable records.
Use multi-select categories to build lists that span related industries — for example, combining "Plumber", "Electrician", and "HVAC Contractor" for a home services campaign.
When targeting specialists — like dedicated law firms rather than businesses that occasionally offer legal services — enable "Primary activity only" to keep your list focused.
# SphereScout: B2B Contact Database Overview
Source: https://docs.spherescout.io/introduction
Access 50M+ local business contacts across 20+ countries. Search by industry and location, filter by contact type, and export to CSV instantly.
SphereScout is a B2B contact database built for sales teams, marketers, and agencies that need verified local business contacts without the overhead of expensive data pipelines. You search by business category and location, apply filters to narrow down exactly who has an email address, phone number, or social presence, and download a CSV you can import straight into your CRM or outbound tool.
New accounts get **100 free leads** with no credit card required. You can explore the database and run a real export before committing to a plan.
## What's in the database
* **50M+ local business contacts** across 20+ countries
* Contacts include: business name, email, phone, city, region, postal code, country, website, LinkedIn, Facebook, Instagram, and Twitter/X where available
* Business categories span restaurants, lawyers, dentists, contractors, real estate agents, healthcare providers, and hundreds more
* Data is continuously updated and quality-checked for freshness
## Who SphereScout is for
* **Sales development teams** building outbound prospecting lists by vertical and territory
* **Marketing agencies** sourcing contacts for clients across specific industries and cities
* **Freelancers and solo operators** who need targeted leads without a full data subscription
## Key features
* Search by business category, country, state/region, city, or postal code
* Filter results by contact type: email, phone, website, LinkedIn, Facebook, Instagram, Twitter/X
* Filter by Google Maps rating to focus on established businesses
* Export filtered results to CSV with one click — instant download
* Dashboard with search history, re-download, and data freshness checks
* API access for programmatic queries using personal API keys
* Subscription plans with monthly credits (Starter, Growth, Pro, Scale) or one-time purchases without a subscription
## Where to go next
Sign up, run your first search, and export leads in under five minutes.
Create your account with email or Google, and navigate the dashboard.
Learn how to use category, location, and contact-type filters together.
Export your search results to CSV and understand what each column contains.
Compare subscription plans and the one-time purchase option.
Query the database programmatically using your API key.
# Get started with SphereScout in minutes
Source: https://docs.spherescout.io/quickstart
Sign up for free, run your first search, export contacts to CSV, and import them into your CRM — no credit card required to get started.
SphereScout is designed to get you from zero to a usable lead list quickly. This guide walks you through the full flow: creating an account, searching the database, exporting a CSV, and importing it into your outreach tool. Your free account includes 100 leads with no credit card required.
Go to [spherescout.io](https://www.spherescout.io) and click **Get 100 Free Leads**. You can sign up with your email address and a password, or use **Continue with Google** for one-click access.
After signing up with email, you will be redirected to your dashboard. No email verification step is required before you can start searching.
If you already have an account, go to the login page and enter your credentials or sign in with Google.
From your dashboard, use the search panel to filter the database:
* **Business category** — choose an industry such as Restaurants, Dentists, Lawyers, or Contractors. You can select multiple categories.
* **Country** — required to narrow results to a specific country.
* **State/Region** — optional, narrows results within the selected country.
* **City** — optional, for city-level targeting.
* **Postal code** — optional, for the most granular geographic targeting.
Once you select a category and country, the table below populates with a preview of matching contacts. The preview shows the first results; the full count is displayed above the table.
Free accounts can preview results immediately. Your 100 free credits are deducted when you export, not when you search.
Use the filter panel to include only contacts that have specific data fields:
* **Email** — only include contacts with an email address
* **Phone** — only include contacts with a phone number
* **Website** — only include contacts with a website
* **LinkedIn, Facebook, Instagram, Twitter/X** — filter by social media presence
* **Google Maps rating** — filter by minimum star rating
Combining filters narrows the result set to contacts that match all selected criteria. For cold email campaigns, enabling the **Email** filter ensures every exported row has a deliverable address.
When your filters are set and the result count looks right, click **Export** (or **Download all contacts**) to download a CSV file instantly.
The exported file contains one row per contact with the following columns:
```csv theme={null}
name,email,phone,city,level2_location,zipcode,country,website,linkedin,twitter,instagram,facebook,first_seen,last_seen
"Acme Dental Clinic","contact@acmedental.com","+1-555-0123","Austin","Texas","78701","US","https://acmedental.com","https://linkedin.com/company/acmedental","","https://instagram.com/acmedental","https://facebook.com/acmedental","2024-01-10","2025-03-15"
"City Law Group","info@citylawgroup.com","+1-555-0456","Austin","Texas","78702","US","https://citylawgroup.com","","","","https://facebook.com/citylawgroup","2023-11-05","2025-04-01"
```
Fields that are unavailable for a given contact are left blank — the column is still present in every row so your CRM import mapping stays consistent.
The `level2_location` column contains the state or region name. Use it alongside `city` and `zipcode` for territory segmentation in your CRM.
Open your CRM (HubSpot, Salesforce, Pipedrive, etc.) or email sequencer and use its CSV import feature. Map the columns from the SphereScout export to the corresponding fields in your tool:
| SphereScout column | Typical CRM field |
| - | - |
| `name` | Company name |
| `email` | Email address |
| `phone` | Phone number |
| `city` | City |
| `level2_location` | State / Region |
| `country` | Country |
| `website` | Website |
| `linkedin` | LinkedIn URL |
Most CRM tools accept CSV imports directly from your downloads folder. No transformation or cleaning is needed before importing.
## What happens after your free credits are used
Once you have exported 100 leads, your free credits are exhausted. You can upgrade to a subscription plan to continue:
* **Starter** — paid access for light prospecting and small teams
* **Growth** — for recurring prospecting workflows
* **Pro** — for teams scaling outbound campaigns
* **Scale** — for high-volume sales teams and agencies
You can also make a one-time purchase without subscribing if you need a specific dataset for a single campaign.
See monthly credit amounts and pricing for each subscription tier.
Buy a specific lead list once, with no recurring fee.
# Troubleshoot common SphereScout issues
Source: https://docs.spherescout.io/troubleshooting
Step-by-step solutions for login problems, missing credits, failed exports, CSV issues, data freshness errors, and API authentication failures in SphereScout.
Most issues in SphereScout have a quick fix. This page walks through the problems users run into most often, organized by area, so you can find the right solution without digging through settings. If you work through the steps here and the problem persists, the support team is available at [support@spherescout.io](mailto:support@spherescout.io).
## Login and account
Start with the basics before anything else:
1. **Check your email address** — make sure you're using the same address you signed up with. If you registered with Google, you need to use **Continue with Google** rather than entering your email and password manually.
2. **Check your password** — passwords are case-sensitive. If you're unsure, use the **Forgot password** link on the login page to reset it.
3. **Try Google login** — if you originally signed up with Google, the email/password form won't work for your account. Look for the **Continue with Google** button on the login page.
4. **Clear your browser cache** — a stale session cookie can occasionally prevent login. Clear your cache and cookies, then try again.
If you're not sure whether you signed up with Google or email, try the Google login option first. It won't cause any issues if your account was created differently.
If the reset email hasn't arrived:
1. **Check your spam folder** — password reset emails occasionally land in spam or junk. Search for an email from `spherescout.io`.
2. **Wait five minutes** — email delivery can be delayed, especially through corporate mail servers. Give it a few minutes before requesting another reset.
3. **Request a second reset** — go back to the login page, click **Forgot password**, and submit the form again. Only the most recent reset link is valid.
4. **Check for typos** — confirm you entered the correct email address when you requested the reset.
If you've waited more than 10 minutes and checked your spam folder with no result, contact [support@spherescout.io](mailto:support@spherescout.io) with the email address on your account.
If you see a message that your account is locked or suspended, or if you're being turned away at login without a clear error:
* Do not attempt to create a new account, as this may complicate the resolution.
* Contact the support team directly at [support@spherescout.io](mailto:support@spherescout.io) and include the email address associated with your account.
The team will investigate and respond with next steps.
## Credits and billing
Credits are usually added to your account within a few seconds of a successful payment. If they haven't appeared:
1. **Wait two to three minutes** — payment processing can occasionally take a moment to propagate to your credit balance.
2. **Refresh the dashboard** — a hard refresh (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on Mac) clears the cached balance display.
3. **Check your email** — look for a payment confirmation from Stripe. If no confirmation arrived, the payment may not have completed.
If your credit balance is still incorrect after five minutes and you have a Stripe payment confirmation, contact [support@spherescout.io](mailto:support@spherescout.io) and include the confirmation number from your email.
This error means your credit balance is too low to cover the number of contacts in your export. Here's how to resolve it:
1. **Check your balance** — your current credit balance is shown in the top bar of the dashboard. Confirm how many credits you have available.
2. **Reduce the export size** — apply tighter filters to narrow your results to fewer contacts so the export fits within your remaining balance.
3. **Buy a top-up** — purchase a one-time credit top-up from the billing page to add credits immediately without changing your plan.
4. **Upgrade your plan** — if you're consistently hitting the limit, upgrading to the next plan tier gives you a larger monthly allocation.
Credits are only deducted at the time of export, not when you run a search. You can refine your filters as many times as you need before downloading.
A declined payment is usually a card-level issue rather than a problem with SphereScout. Try the following:
1. **Verify your card details** — check that the card number, expiry date, and CVC are entered correctly, including the billing address if your card requires it.
2. **Try a different card** — if you have another card available, use that to complete the purchase.
3. **Contact your bank** — some banks block unfamiliar online transactions by default. Call the number on the back of your card to authorize the charge, then retry.
4. **Check your spending limit** — some prepaid and virtual cards have per-transaction limits that may be lower than the purchase amount.
If payments continue to fail after trying the above steps, contact [support@spherescout.io](mailto:support@spherescout.io).
## Searches and exports
Zero results usually means the combination of filters is too narrow. Try these steps in order:
1. **Remove one filter at a time** — start by removing the most specific filter (city, then region) and re-run the search after each removal to see where results appear.
2. **Try a broader category** — if you're searching for a narrow specialty, try the parent category. For example, search "Healthcare" instead of a specific subspecialty.
3. **Change the country** — if your target market has low coverage, try a neighboring country or a larger market to confirm the category exists in the database.
4. **Check your spelling** — if you typed in the category search box, verify the term is spelled correctly or choose from the dropdown list instead.
Start broad and add filters progressively. This gives you a better sense of what the database holds for your target segment before you narrow it down.
Exports typically complete within a few seconds for smaller result sets and up to two minutes for very large exports. If the status has been on "processing" for more than five minutes:
1. **Refresh the page** — the export may have completed but the status display didn't update. Check your **Export History** to see if the file is ready.
2. **Check your email** — large exports are also sent to your account email address when they're ready.
3. **Try a smaller export** — if the export is very large, split it into smaller batches by applying tighter location or category filters.
If the export is still stuck after five minutes and doesn't appear in your export history, contact [support@spherescout.io](mailto:support@spherescout.io) with the details of your search.
If the downloaded file won't open or displays garbled characters:
1. **Use Excel or Google Sheets** — double-clicking a CSV on some operating systems opens it in a plain text editor. Right-click the file and choose to open it with Excel, or upload it to [Google Sheets](https://sheets.google.com).
2. **Check the encoding in Excel** — if special characters (accents, non-Latin scripts) appear as symbols, use Excel's **Data > From Text/CSV** import option and select **UTF-8** encoding during import.
3. **Rename the file extension** — if the file downloaded without a `.csv` extension, rename it to `filename.csv` before opening.
SphereScout exports are UTF-8 encoded to support international business names and addresses. Most modern spreadsheet applications handle UTF-8 by default.
Not every business has an email address or phone number in the public record, so some rows in your export will have empty fields for certain contact types. This is expected behavior, not a data error.
To export only contacts with a specific field populated:
1. **Use presence filters before exporting** — in the search filters, enable **Has email**, **Has phone**, **Has website**, or the relevant social platform filter. Only contacts that have that field will appear in your results and export.
2. **Combine presence filters** — you can apply multiple presence filters at once to require, for example, both an email and a phone number.
Using presence filters before exporting means every credit you spend goes toward a contact you can actually reach through that channel.
## Data freshness
If a freshness check reports that no new contacts have been added since your last export, it means the database for that specific category and location segment is up to date — there are genuinely no net-new records to download at this time.
This is not an error. The database is continuously updated, but new businesses are not added at a uniform rate across every segment. Some markets and categories receive new records more frequently than others.
Check back after a few days or a week. If you need contacts now, try widening your search to an adjacent region or a broader category.
Freshness checks have a cooldown period to prevent excessive database queries. If you see a rate limit error, the message will include the date and time when you can run another check.
Wait until the shown date before attempting another freshness check for that segment. Running checks repeatedly in a short window will not speed up the process — each attempt during the cooldown period will return the same rate limit message.
If the cooldown period shown seems unusually long, contact [support@spherescout.io](mailto:support@spherescout.io).
## API
A 401 error means the API could not authenticate your request. Check the following:
1. **Verify your API key** — copy your key directly from the **API Keys** section in your dashboard settings and paste it into your request. Avoid manual typing to prevent invisible character errors.
2. **Check that the key is active** — if you've revoked or regenerated the key, the old value will no longer work. Generate a new key and update your integration.
3. **Check the Authorization header format** — the correct format for an API key is `Authorization: Token YOUR_API_KEY`. Ensure the word `Token` is present with a space before your key, and there are no extra spaces or characters.
4. **Check for whitespace** — keys copied from some text editors or password managers can include a trailing space or newline. Trim the value before using it.
If you suspect your API key has been exposed, revoke it immediately from the API Keys section in your dashboard and generate a new one. Do not use a compromised key even temporarily.
A 429 error means you've exceeded the API rate limit for your plan. SphereScout enforces rate limits to maintain database performance for all users.
To resolve this:
1. **Slow down your request rate** — add a delay between requests in your code. A small pause of even 200–500 milliseconds between calls is usually enough to stay within limits.
2. **Batch your requests** — instead of making many small requests, combine filters to retrieve larger result sets per call.
3. **Implement retry logic with backoff** — when you receive a 429, wait before retrying. Exponential backoff (doubling the wait time on each retry) is a reliable approach.
If your use case requires higher rate limits than your current plan allows, contact [support@spherescout.io](mailto:support@spherescout.io) to discuss options.
***
## Still need help?
If you've worked through the relevant section above and the issue isn't resolved, the SphereScout support team is here to help.
Email **[support@spherescout.io](mailto:support@spherescout.io)** for help with your account, exports, credits, or any issue not covered here. Include as much detail as you can — error messages, the steps you've already tried, and your account email — so the team can respond quickly.
Email **[contact@spherescout.io](mailto:contact@spherescout.io)** for questions about enterprise pricing, high-volume API access, or custom data requirements.