SphereScout REST API overview

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

Base URL

All API endpoints are served from a single origin:

https://www.spherescout.io

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

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

Authentication methods

The API supports two ways to authenticate requests. Both use the same Authorization: Bearer header format.

API keys (recommended)
JWT bearer tokens

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.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

See 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:

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

import requests

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

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

Search and export flow

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

Run a search

Call GET /api/companies with the filters that describe the contacts you want (country, category, contact method, etc.). The response includes a totalCount, a paginated preview of results, and a search_id that uniquely identifies this query.Use the search_id to drive the export — there is no need to re-send the filters.

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

Response

{
  "search_id": "srch_01HZ...",
  "totalCount": 12480,
  "preview": [ /* first page of contacts */ ]
}

Initiate the CSV export

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

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

Response

{
  "task_id": "task_01HZ...",
  "status": "pending"
}

Poll for completion

Call GET /api/download-status/{task_id} periodically until status becomes ready. We recommend polling every 2–5 seconds with exponential backoff; most exports complete in under a minute, but large result sets can take longer.Possible status values:

Status	Meaning
`pending`	Job is queued, not yet started. Keep polling.
`processing`	Job is running. Keep polling.
`ready`	CSV is ready. Response includes a `download_url`.
`failed`	Job failed. Response includes an `error` message; do not retry without investigating.

Ready response

{
  "task_id": "task_01HZ...",
  "status": "ready",
  "download_url": "https://www.spherescout.io/exports/...csv",
  "expires_at": "2026-06-04T12:00:00Z"
}

Download the CSV

Fetch the file from the download_url returned in the previous step. Links remain valid for 30 days; after that, regenerate the export from your search history.

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

Rate limits

The API enforces rate limits to ensure availability for all users. Specific thresholds depend on your plan. Contact support for rate limit details relevant to your account.

Endpoint reference

The table below groups the public API surface by category.

Authentication

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

Account

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

API key management

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

Contact search

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

Reference data

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

Exports

Method	Path	Description
`GET`	`/api/download-csv`	Initiate an async CSV export for a given `search_id`; returns a `task_id`
`GET`	`/api/download-status/{task_id}`	Poll the status of an export job and retrieve the download URL when ready

Export history

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

Get Started

Core Concepts

Using SphereScout

Plans & Billing

API Access

Help

SphereScout REST API overview

Base URL

Authentication methods

Request format

Quick example

Search and export flow

Rate limits

Endpoint reference

Authentication

Account

API key management

Contact search

Reference data

Exports

Export history

Next steps

API keys

Authentication

​Base URL

​Authentication methods

​Request format

​Quick example

​Search and export flow

​Rate limits

​Endpoint reference

​Authentication

​Account

​API key management

​Contact search

​Reference data

​Exports

​Export history

​Next steps

API keys

Authentication

Base URL

Authentication methods

Request format

Quick example

Search and export flow

Rate limits

Endpoint reference

Authentication

Account

API key management

Contact search

Reference data

Exports

Export history

Next steps