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 asynchronous. Preview the result set, start an export with the same filters, poll its search_id, then request the completed file.

Run a search

Call GET /api/companies with the filters that describe the contacts you want (country, category, contact method, etc.). The response includes a totalCount and a paginated preview of results. Previewing does not create a search ID.Permanently closed businesses are excluded by default. Set include_closed_businesses=true here and on the export request if you want to include them. Using the same value on both requests keeps the preview count and export credit cost aligned.

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

Response

{
  "totalCount": 12480,
  "preview": []
}

Initiate the CSV export

Call GET /api/download-csv with the same filters to enqueue the export. This endpoint returns a numeric search_id. That value is the only identifier used for the rest of the export workflow.

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

Response

{
  "status": "processing",
  "validation_code": "processing_started",
  "search_id": 12345,
  "lead_count": 12480
}

Poll for completion

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

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

Completed response

{
  "status": "completed",
  "validation_code": "processing_completed",
  "lead_count": 12480,
  "file_size_bytes": 845220,
  "expires_at": "2026-06-04T12:00:00Z"
}

Download the CSV

Call GET /api/download-completed-csv/{search_id} with the same search_id. The response contains a time-limited download_url; fetch that URL to download the file.

Response

{
  "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:

curl -G "https://www.spherescout.io/api/download-csv" \
  -H "Authorization: Bearer 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 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

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

Optional export fields

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

​Optional export fields

​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

Optional export fields

Rate limits

Endpoint reference

Authentication

Account

API key management

Contact search

Reference data

Exports

Export history

Next steps