Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherescout.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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.
1

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 */ ]
}
2

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"
}
3

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:
StatusMeaning
pendingJob is queued, not yet started. Keep polling.
processingJob is running. Keep polling.
readyCSV is ready. Response includes a download_url.
failedJob 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"
}
4

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

MethodPathDescription
POST/api/auth/loginObtain JWT access and refresh tokens
POST/api/token/refreshExchange a refresh token for a new access token

​
Account

MethodPathDescription
GET/api/user/profileRetrieve account details and remaining credit balance

​
API key management

MethodPathDescription
GET/api/user/api-keysList all API keys on your account
POST/api/user/api-keysCreate a new API key
DELETE/api/user/api-keys/{key_id}Permanently revoke an API key
MethodPathDescription
GET/api/companiesSearch and filter business contacts (authenticated)
GET/api/public/companiesPreview contacts without authentication (limited results)

​
Reference data

MethodPathDescription
GET/api/categoriesList all business categories and their IDs
GET/api/locations/countriesList available countries
GET/api/locations/searchSearch for locations by query string
GET/api/professions/summaryRetrieve profession and subcategory data

​
Exports

MethodPathDescription
GET/api/download-csvInitiate 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

MethodPathDescription
GET/api/user/search-historyList all past exports on your account
GET/api/user/search-history/{id}/freshnessCheck whether new contacts match a past search
GET/api/user/search-history/{id}/download-deltaDownload only the new contacts since a previous export

​
Next steps

API keys

Generate and manage long-lived API credentials for server integrations.

Authentication

Learn the full JWT login flow and token-refresh cycle.