{ "openapi": "3.0.3", "info": { "title": "SphereScout API", "version": "1.0.0", "description": "\n# SphereScout API\n\nSphereScout provides B2B lead data — business contacts with emails,\nphone numbers, and location metadata — across multiple countries.\n\n## Authentication\n\nAll endpoints (except `/api/auth/` and `/api/plans`) require a **JWT Bearer token**.\n\n1. **Register** — `POST /api/auth/sign-up/`\n2. **Login** — `POST /api/auth/login/` → returns `access` and `refresh` tokens\n3. **Attach header** — `Authorization: Bearer `\n4. **Refresh** — `POST /api/token/refresh/` with `{ \"refresh\": \"\" }`\n\nAccess tokens expire after 60 minutes. Refresh tokens are long-lived.\n\n## Credits\n\nEvery account has a credit balance. Exporting leads costs **1 credit per lead**.\nCheck your balance via `GET /api/user/profile/`. Credits reset each billing cycle\nfor subscribed users.\n\n## Async Download Workflow\n\nExporting leads is asynchronous:\n\n1. **Search** — `GET /api/companies/` to preview results and get `totalCount`\n2. **Export** — `POST /api/download-csv/` to start generation (credits deducted immediately)\n3. **Poll** — `GET /api/download-status/{search_id}/` until `status = COMPLETED`\n4. **Download** — `GET /api/download-completed-csv/{search_id}/` to get a signed URL\n\n## API Keys (recommended for integrations)\n\nGenerate a persistent API key from your dashboard under **API Keys**.\n\nAttach it to every request:\n```\n Authorization: Token \n```\n\nKeys can be given an expiry date and revoked at any time.\nJWT Bearer tokens (`Authorization: Bearer `) continue to work for browser sessions and Swagger UI testing.\n\n## Rate Limiting\n\nAPI requests are rate-limited. If you receive a `429` response, back off and retry.\n\n## Versioning\n\nThis is **v1** of the API. Breaking changes will be communicated in advance.\n" }, "servers": [ { "url": "https://www.spherescout.io" } ], "paths": { "/api/auth/logout/": { "post": { "operationId": "auth_logout_create", "description": "Logs out the current user", "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/auth/logout/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/auth/logout/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/auth/logout/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/auth/magic/": { "post": { "operationId": "auth_magic_create", "tags": [ "auth" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/auth/magic/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/auth/magic/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/auth/magic/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/auth/request-password-reset/": { "post": { "operationId": "auth_request_password_reset_create", "description": "Send password reset link to email address", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResetLinkRequestRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SendResetLinkRequestRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SendResetLinkRequestRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessageResponse" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessageResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/auth/request-password-reset/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/auth/request-password-reset/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/auth/request-password-reset/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/auth/reset-password/": { "post": { "operationId": "auth_reset_password_create", "description": "Reset password using the token received via email. Returns new JWT tokens on success.", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordResponse" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessageResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/auth/reset-password/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/auth/reset-password/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/auth/reset-password/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/auth/sign-up/": { "post": { "operationId": "auth_sign_up_create", "description": "Register a new user account", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequestRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RegisterRequestRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RegisterRequestRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessageResponse" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessageResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/auth/sign-up/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/auth/sign-up/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/auth/sign-up/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/categories/": { "get": { "operationId": "categories_list", "description": "List or search available business categories (e.g. Restaurant, Bakery, Plumber).\n\nUse the returned `id` values as the `category` parameter in search endpoints. When `q` is provided, results include match metadata for agent disambiguation.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum number of categories to return when q is provided. Defaults to 20; maximum 100." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Optional category search term. Searches English and localized category names plus gcid, returning a capped result set ordered by match quality." } ], "tags": [ "Search" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/categories/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/categories/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/categories/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/cities/{country_alpha2_code}/": { "get": { "operationId": "cities_list", "description": "Get a list of Level 3 Locations (Cities) that have associated companies.", "parameters": [ { "in": "path", "name": "country_alpha2_code", "schema": { "type": "string" }, "required": true } ], "tags": [ "Geography" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommonLocation" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/cities/{country_alpha2_code}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/cities/{country_alpha2_code}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/cities/{country_alpha2_code}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/companies/": { "get": { "operationId": "companies_retrieve", "description": "Search for business leads matching the given filters and return a preview.\n\n**Prerequisites:** Authenticated with a valid JWT.\n\nThe response includes `totalCount` which tells you how many credits an export will cost. Use this endpoint to refine filters before calling `/api/download-csv/`.", "parameters": [ { "in": "query", "name": "category", "schema": { "type": "integer" }, "description": "Filter by category ID (from GET /api/categories/)." }, { "in": "query", "name": "countries", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by country alpha-2 codes (e.g. 'FR', 'AU'). Repeat for multiple." }, { "in": "query", "name": "include_closed_businesses", "schema": { "type": "boolean", "enum": [ false, true ] }, "description": "Set to 'true' to include permanently closed businesses in the preview count. Defaults to 'false'." }, { "in": "query", "name": "level2_locations", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by level-2 location codes (states/departments)." } ], "tags": [ "Search" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesFilterResponse" } } }, "description": "" } }, "x-llm-hint": "Step 1: Search. Use totalCount to estimate credits needed before exporting.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/companies/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/companies/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/companies/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/companies/{company_id}/reveal-contact/": { "post": { "operationId": "companies_reveal_contact_create", "parameters": [ { "in": "path", "name": "company_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "companies" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/companies/{company_id}/reveal-contact/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/companies/{company_id}/reveal-contact/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/companies/{company_id}/reveal-contact/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/download-completed-csv/{search_id}/": { "get": { "operationId": "download_completed_csv_retrieve", "description": "Get a signed download URL for a completed lead export.\n\n**Prerequisites:** Authenticated. The search must have `status=COMPLETED`.\n\nThe returned `download_url` is a time-limited signed URL. Download the file before `expires_at`. Returns `410 Gone` if the link has already expired.", "parameters": [ { "in": "path", "name": "search_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "Download" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri", "description": "Signed URL to download the file. Valid until expires_at." }, "filename": { "type": "string", "description": "Suggested filename for the download." }, "file_size_bytes": { "type": "integer", "description": "File size in bytes." }, "file_size_mb": { "type": "number", "description": "File size in MB." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the download URL expires." } } } } }, "description": "" } }, "x-llm-hint": "Step 4: Get the signed download URL. Use it before expires_at.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/download-completed-csv/{search_id}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/download-completed-csv/{search_id}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/download-completed-csv/{search_id}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/download-csv/": { "get": { "operationId": "download_csv_retrieve", "description": "Initiate an asynchronous lead export.\n\n**Prerequisites:** Authenticated. Sufficient credits (1 per lead).\n\nCredits are deducted immediately. The response contains a `search_id` — use it to poll `/api/download-status/{search_id}/` until the file is ready.", "parameters": [ { "in": "query", "name": "category", "schema": { "type": "integer" }, "description": "Category ID to filter." }, { "in": "query", "name": "countries", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Country alpha-2 codes to export." }, { "in": "query", "name": "export_format", "schema": { "type": "string", "enum": [ "csv", "excel", "xlsx" ] }, "description": "Output format: 'excel' (default), 'csv', or 'xlsx'." }, { "in": "query", "name": "include_additional_fields", "schema": { "type": "boolean", "enum": [ false, true ] }, "description": "Set to 'true' to append coordinates, rating, review count, claimed status, opening hours, and business status to the export. Defaults to 'false'." }, { "in": "query", "name": "include_closed_businesses", "schema": { "type": "boolean", "enum": [ false, true ] }, "description": "Set to 'true' to include permanently closed businesses in the search and export. Defaults to 'false'." } ], "tags": [ "Download" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadCsvResponse" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsResponse" } } }, "description": "" } }, "x-llm-hint": "Step 2: Initiate export. Credits deducted immediately. Returns search_id for polling.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/download-csv/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/download-csv/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/download-csv/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] }, "post": { "operationId": "download_csv_create", "description": "Initiate an asynchronous lead export.\n\n**Prerequisites:** Authenticated. Sufficient credits (1 per lead).\n\nCredits are deducted immediately. The response contains a `search_id` — use it to poll `/api/download-status/{search_id}/` until the file is ready.", "parameters": [ { "in": "query", "name": "category", "schema": { "type": "integer" }, "description": "Category ID to filter." }, { "in": "query", "name": "countries", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Country alpha-2 codes to export." }, { "in": "query", "name": "export_format", "schema": { "type": "string", "enum": [ "csv", "excel", "xlsx" ] }, "description": "Output format: 'excel' (default), 'csv', or 'xlsx'." }, { "in": "query", "name": "include_additional_fields", "schema": { "type": "boolean", "enum": [ false, true ] }, "description": "Set to 'true' to append coordinates, rating, review count, claimed status, opening hours, and business status to the export. Defaults to 'false'." }, { "in": "query", "name": "include_closed_businesses", "schema": { "type": "boolean", "enum": [ false, true ] }, "description": "Set to 'true' to include permanently closed businesses in the search and export. Defaults to 'false'." } ], "tags": [ "Download" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadCsvResponse" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsResponse" } } }, "description": "" } }, "x-llm-hint": "Step 2: Initiate export. Credits deducted immediately. Returns search_id for polling.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/download-csv/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/download-csv/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/download-csv/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/download-status/{search_id}/": { "get": { "operationId": "download_status_retrieve", "description": "Poll the processing status of a lead export.\n\n**Prerequisites:** Authenticated. The `search_id` must belong to the current user.\n\nKeep polling until `status` is `COMPLETED` or `FAILED`. When completed, call `/api/download-completed-csv/{search_id}/` to get the file.", "parameters": [ { "in": "path", "name": "search_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "Download" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Processing status: PENDING, PROCESSING, COMPLETED, or FAILED." }, "validation_code": { "type": "string", "description": "Machine-readable code: processing_pending, processing_in_progress, processing_completed, processing_failed." }, "lead_count": { "type": "integer", "description": "Number of leads in the export." }, "file_size_bytes": { "type": "integer", "description": "File size in bytes (only when COMPLETED)." }, "file_size_mb": { "type": "number", "description": "File size in MB (only when COMPLETED)." }, "processing_started_at": { "type": "string", "format": "date-time" }, "processing_completed_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the download link expires." }, "error_message": { "type": "string", "description": "Human-readable error (only on known business errors)." } } } } }, "description": "" } }, "x-llm-hint": "Step 3: Poll this endpoint until status=COMPLETED, then proceed to download.", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/download-status/{search_id}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/download-status/{search_id}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/download-status/{search_id}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/countries/": { "get": { "operationId": "locations_countries_list", "description": "Get a list of countries that have companies", "tags": [ "Geography" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/countries/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/countries/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/countries/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/level1/": { "get": { "operationId": "locations_level1_list", "description": "ViewSet for Level1 locations (states/regions) with filtering support.\n\nQuery parameters:\n- country: Country alpha2 code (e.g., 'AU', 'FR')\n\nExample: /api/locations/level1/?country=AU", "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Level1Location" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/level1/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/level1/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/level1/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/level1/{id}/": { "get": { "operationId": "locations_level1_retrieve", "description": "ViewSet for Level1 locations (states/regions) with filtering support.\n\nQuery parameters:\n- country: Country alpha2 code (e.g., 'AU', 'FR')\n\nExample: /api/locations/level1/?country=AU", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this level1 location.", "required": true } ], "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Level1Location" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/level1/{id}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/level1/{id}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/level1/{id}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/level2/": { "get": { "operationId": "locations_level2_list", "description": "ViewSet for Level2 locations (counties/departments) with filtering support.\n\nQuery parameters:\n- states: State IDs (repeated parameter format, e.g., 'states=46&states=44&states=51')\n- country: Country alpha2 code (e.g., 'AU', 'FR')\n\nExample: /api/locations/level2/?states=46&states=44&states=51&country=AU", "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Level2Location" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/level2/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/level2/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/level2/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/level2/{id}/": { "get": { "operationId": "locations_level2_retrieve", "description": "ViewSet for Level2 locations (counties/departments) with filtering support.\n\nQuery parameters:\n- states: State IDs (repeated parameter format, e.g., 'states=46&states=44&states=51')\n- country: Country alpha2 code (e.g., 'AU', 'FR')\n\nExample: /api/locations/level2/?states=46&states=44&states=51&country=AU", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this level2 location.", "required": true } ], "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Level2Location" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/level2/{id}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/level2/{id}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/level2/{id}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/level3/": { "get": { "operationId": "locations_level3_list", "description": "ViewSet for Level3 locations (cities) with filtering support.\n\nQuery parameters:\n- counties: County IDs (repeated parameter format, e.g., 'counties=123&counties=456')\n- country: Country alpha2 code (e.g., 'AU', 'FR')\n\nExample: /api/locations/level3/?counties=123&counties=456&country=AU", "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Level3Location" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/level3/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/level3/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/level3/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/level3/{id}/": { "get": { "operationId": "locations_level3_retrieve", "description": "ViewSet for Level3 locations (cities) with filtering support.\n\nQuery parameters:\n- counties: County IDs (repeated parameter format, e.g., 'counties=123&counties=456')\n- country: Country alpha2 code (e.g., 'AU', 'FR')\n\nExample: /api/locations/level3/?counties=123&counties=456&country=AU", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this level3 location.", "required": true } ], "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Level3Location" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/level3/{id}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/level3/{id}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/level3/{id}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/locations/search/": { "get": { "operationId": "locations_search_retrieve", "tags": [ "locations" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/locations/search/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/locations/search/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/locations/search/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/page-snapshots/{alpha2}/": { "get": { "operationId": "page_snapshots_retrieve", "description": "Return the full country page-data payload from DB snapshots.\n\nShape is equivalent to ui/src/data/categoryCheckout/countries/{alpha2}.json\nso Next.js can fetch this instead of reading static JSON files.\nToken-gated via PROFESSION_SUMMARY_TOKEN.", "parameters": [ { "in": "path", "name": "alpha2", "schema": { "type": "string" }, "required": true } ], "tags": [ "page-snapshots" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/page-snapshots/{alpha2}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/page-snapshots/{alpha2}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/page-snapshots/{alpha2}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/plans": { "get": { "operationId": "plans_list", "description": "List all active subscription plans with pricing and credit allowances.\n\nNo authentication required. Use this to display plan options to users.", "tags": [ "Credits & Profile" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlan" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/plans' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/plans\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/plans\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/token/refresh/": { "post": { "operationId": "token_refresh_create", "description": "Refresh access token using refresh token", "tags": [ "Authentication" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequestRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequestRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequestRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusMessageResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/token/refresh/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/token/refresh/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/token/refresh/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/token/|api/auth/login/": { "post": { "operationId": "token_|api_auth_login_create", "description": "Takes a set of user credentials and returns an access and refresh JSON web\ntoken pair to prove the authentication of those credentials.", "tags": [ "token" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomTokenObtainPairRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomTokenObtainPairRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomTokenObtainPairRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/token/|api/auth/login/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/token/|api/auth/login/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/token/|api/auth/login/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/user/api-keys/": { "get": { "operationId": "user_api_keys_retrieve", "summary": "List and create API keys", "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/user/api-keys/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/user/api-keys/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/api-keys/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] }, "post": { "operationId": "user_api_keys_create", "summary": "List and create API keys", "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/user/api-keys/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/user/api-keys/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/api-keys/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/user/api-keys/{key_id}/": { "delete": { "operationId": "user_api_keys_destroy", "summary": "Revoke an API key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string", "pattern": "^[^/]+$" }, "required": true } ], "tags": [ "API Keys" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X DELETE 'https://www.spherescout.io/api/user/api-keys/{key_id}/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.delete(\n \"https://www.spherescout.io/api/user/api-keys/{key_id}/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/api-keys/{key_id}/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/user/profile/": { "get": { "operationId": "user_profile_retrieve", "description": "Get the authenticated user's profile, including remaining credits, subscription plan, and billing period dates.\n\n**Prerequisites:** Authenticated with a valid JWT.", "tags": [ "Credits & Profile" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomUser" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/user/profile/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/user/profile/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/profile/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] }, "patch": { "operationId": "user_profile_partial_update", "description": "Get the authenticated user's profile, including remaining credits, subscription plan, and billing period dates.\n\n**Prerequisites:** Authenticated with a valid JWT.", "tags": [ "Credits & Profile" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomUser" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X PATCH 'https://www.spherescout.io/api/user/profile/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.patch(\n \"https://www.spherescout.io/api/user/profile/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/profile/\", {\n method: \"PATCH\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/user/search-history/": { "get": { "operationId": "user_search_history_list", "description": "List all past lead searches for the authenticated user.\n\nEach 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.", "tags": [ "History" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHistoryItem" } } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X GET 'https://www.spherescout.io/api/user/search-history/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.get(\n \"https://www.spherescout.io/api/user/search-history/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/search-history/\", {\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n});\nconst data = await response.json();" } ] } }, "/api/user/search-history/{search_id}/download-delta/": { "post": { "operationId": "user_search_history_download_delta_create", "description": "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.", "parameters": [ { "in": "path", "name": "search_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "History" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeltaDownloadResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/user/search-history/{search_id}/download-delta/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/user/search-history/{search_id}/download-delta/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/search-history/{search_id}/download-delta/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/user/search-history/{search_id}/freshness/": { "post": { "operationId": "user_search_history_freshness_create", "description": "Check and cache fresh data availability for a previous search.", "parameters": [ { "in": "path", "name": "search_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "History" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshnessCheckResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/user/search-history/{search_id}/freshness/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/user/search-history/{search_id}/freshness/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/search-history/{search_id}/freshness/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/user/search-history/{search_id}/rename/": { "patch": { "operationId": "user_search_history_rename_partial_update", "description": "Rename a saved search history export.", "parameters": [ { "in": "path", "name": "search_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "History" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "nullable": true, "maxLength": 120 } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchHistoryRenameResponse" } } }, "description": "" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X PATCH 'https://www.spherescout.io/api/user/search-history/{search_id}/rename/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.patch(\n \"https://www.spherescout.io/api/user/search-history/{search_id}/rename/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/search-history/{search_id}/rename/\", {\n method: \"PATCH\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } }, "/api/user/search-history/{search_id}/retry/": { "post": { "operationId": "user_search_history_retry_create", "parameters": [ { "in": "path", "name": "search_id", "schema": { "type": "integer" }, "required": true } ], "tags": [ "user" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "No response body" } }, "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST 'https://www.spherescout.io/api/user/search-history/{search_id}/retry/' \\\n -H 'Authorization: Token YOUR_API_KEY' \\\n -H 'User-Agent: SphereScout/1.0' \\\n -H 'Content-Type: application/json' \\\n -d '{}'" }, { "lang": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://www.spherescout.io/api/user/search-history/{search_id}/retry/\",\n headers={\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n },\n json={},\n)\nprint(response.json())" }, { "lang": "JavaScript", "source": "const response = await fetch(\"https://www.spherescout.io/api/user/search-history/{search_id}/retry/\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Token YOUR_API_KEY\",\n \"User-Agent\": \"SphereScout/1.0\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({}),\n});\nconst data = await response.json();" } ] } } }, "components": { "schemas": { "Category": { "type": "object", "properties": { "id": { "type": "integer", "description": "Category ID, used in search filters." }, "name": { "type": "string", "description": "Category name in English." }, "name_fr": { "type": "string", "nullable": true, "description": "Category name in French." }, "name_pt": { "type": "string", "nullable": true, "description": "Category name in Portuguese." }, "name_es": { "type": "string", "nullable": true, "description": "Category name in Spanish." }, "name_it": { "type": "string", "nullable": true, "description": "Category name in Italian." }, "name_de": { "type": "string", "nullable": true, "description": "Category name in German." }, "gcid": { "type": "string", "nullable": true, "description": "Google Category ID (internal reference)." }, "kind": { "type": "string", "description": "Category classification kind." }, "is_business_category": { "type": "boolean", "description": "Whether this category should be treated as a business category in product logic." } }, "required": [ "gcid", "id", "is_business_category", "kind", "name", "name_de", "name_es", "name_fr", "name_it", "name_pt" ] }, "CommonLocation": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "code", "id", "name" ] }, "CompaniesFilterResponse": { "type": "object", "properties": { "preview": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyPreview" }, "description": "Paginated list of matching companies (preview only, no full contact data)." }, "totalCount": { "type": "integer", "description": "Total number of leads matching the filters. Use this to estimate credit cost before exporting." }, "cities": { "type": "array", "items": { "type": "string" }, "description": "Distinct cities in the result set." }, "zipCodes": { "type": "array", "items": { "type": "string" }, "description": "Distinct zip/postal codes in the result set." }, "categories": { "type": "array", "items": { "type": "array", "items": {} }, "description": "Categories represented in the result set." } }, "required": [ "preview", "totalCount" ] }, "CompanyPreview": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique company identifier." }, "name": { "type": "string", "description": "Business name." }, "email": { "type": "array", "items": { "type": "string" }, "description": "List of email addresses." }, "phone": { "type": "string", "description": "Primary phone number." }, "city": { "type": "string", "description": "City where the business is located." }, "country": { "type": "string", "description": "Country name." }, "level2_location": { "type": "string", "description": "State, region, or department name." } }, "required": [ "city", "country", "email", "id", "level2_location", "name", "phone" ] }, "Country": { "type": "object", "properties": { "name": { "type": "string", "description": "Country name in English." }, "name_fr": { "type": "string", "description": "Country name in French." }, "name_he": { "type": "string", "description": "Country name in Hebrew." }, "code": { "type": "string", "description": "ISO 3166-1 numeric or alpha-3 code." }, "alpha2": { "type": "string", "description": "ISO 3166-1 alpha-2 code (e.g. 'FR', 'AU')." }, "id": { "type": "string", "description": "Alias for alpha2, used as unique identifier." } }, "required": [ "alpha2", "code", "id", "name", "name_fr", "name_he" ] }, "CustomTokenObtainPairRequest": { "type": "object", "properties": { "username": { "type": "string", "writeOnly": true, "minLength": 1 }, "password": { "type": "string", "writeOnly": true, "minLength": 1 } }, "required": [ "password", "username" ] }, "CustomUser": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "email": { "type": "string", "format": "email", "title": "Email address", "maxLength": 254 }, "first_name": { "type": "string", "maxLength": 150 }, "last_name": { "type": "string", "maxLength": 150 }, "subscription_plan": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionPlan" } ], "readOnly": true, "description": "Current subscription plan details, or null." }, "total_credits": { "type": "integer", "readOnly": true, "description": "Total credits per billing cycle (from subscription plan). 0 if no plan." }, "remaining_credits": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648, "nullable": true, "description": "Subscription credits available right now." }, "purchased_credits_available": { "type": "integer", "readOnly": true, "description": "Purchased credits currently available and not expired." }, "purchased_credits_expiring_soon": { "type": "integer", "readOnly": true, "description": "Purchased credits expiring in the next 7 days." }, "current_period_start": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648, "nullable": true, "description": "Start of the current billing period (ISO 8601)." }, "current_period_end": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648, "nullable": true, "description": "End of the current billing period (ISO 8601)." }, "can_download_fresh_exports": { "type": "boolean", "readOnly": true }, "preferred_language": { "allOf": [ { "$ref": "#/components/schemas/CustomUserPreferredLanguageEnum" } ], "description": "Two-letter UI language preference.\n\n* `bg` - Bulgarian\n* `cs` - Czech\n* `da` - Danish\n* `de` - German\n* `el` - Greek\n* `fr` - French\n* `en` - English\n* `es` - Spanish\n* `et` - Estonian\n* `fi` - Finnish\n* `he` - Hebrew\n* `hr` - Croatian\n* `hu` - Hungarian\n* `it` - Italian\n* `lt` - Lithuanian\n* `lv` - Latvian\n* `nb` - Norwegian\n* `nl` - Dutch\n* `pl` - Polish\n* `pt` - Portuguese\n* `ro` - Romanian\n* `sk` - Slovak\n* `sl` - Slovenian\n* `sr` - Serbian\n* `sv` - Swedish\n* `th` - Thai\n* `tr` - Turkish" } }, "required": [ "can_download_fresh_exports", "id", "purchased_credits_available", "purchased_credits_expiring_soon", "subscription_plan", "total_credits" ] }, "CustomUserPreferredLanguageEnum": { "enum": [ "bg", "cs", "da", "de", "el", "fr", "en", "es", "et", "fi", "he", "hr", "hu", "it", "lt", "lv", "nb", "nl", "pl", "pt", "ro", "sk", "sl", "sr", "sv", "th", "tr" ], "type": "string", "description": "* `bg` - Bulgarian\n* `cs` - Czech\n* `da` - Danish\n* `de` - German\n* `el` - Greek\n* `fr` - French\n* `en` - English\n* `es` - Spanish\n* `et` - Estonian\n* `fi` - Finnish\n* `he` - Hebrew\n* `hr` - Croatian\n* `hu` - Hungarian\n* `it` - Italian\n* `lt` - Lithuanian\n* `lv` - Latvian\n* `nb` - Norwegian\n* `nl` - Dutch\n* `pl` - Polish\n* `pt` - Portuguese\n* `ro` - Romanian\n* `sk` - Slovak\n* `sl` - Slovenian\n* `sr` - Serbian\n* `sv` - Swedish\n* `th` - Thai\n* `tr` - Turkish" }, "DeltaDownloadResponse": { "type": "object", "properties": { "status": { "type": "string" }, "validation_code": { "type": "string" }, "search_id": { "type": "integer" }, "lead_count": { "type": "integer" }, "required_credits": { "type": "integer" }, "available_credits": { "type": "integer" }, "freshness": { "type": "object", "additionalProperties": {} }, "freshness_checked_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "validation_code" ] }, "DownloadCsvResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "'processing' on success, 'error' on failure." }, "validation_code": { "type": "string", "description": "Machine-readable status code: 'processing_started', 'no_leads_found', 'insufficient_credits'." }, "search_id": { "type": "integer", "description": "ID to poll download status. Only present when status='processing'." }, "lead_count": { "type": "integer", "description": "Number of leads being exported (= credits deducted). Present on success and no_leads_found." } }, "required": [ "status", "validation_code" ] }, "FreshnessCheckResponse": { "type": "object", "properties": { "status": { "type": "string" }, "validation_code": { "type": "string" }, "freshness": { "type": "object", "additionalProperties": {} }, "freshness_checked_at": { "type": "string", "format": "date-time" }, "freshness_check_available": { "type": "boolean" }, "freshness_next_check_at": { "type": "string", "format": "date-time", "nullable": true }, "fresh_export_in_progress": { "type": "boolean" } }, "required": [ "fresh_export_in_progress", "freshness", "freshness_check_available", "freshness_checked_at", "freshness_next_check_at", "status", "validation_code" ] }, "InsufficientCreditsResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Always 'error'." }, "validation_code": { "type": "string", "description": "Always 'insufficient_credits'." }, "required_credits": { "type": "integer", "description": "Number of credits needed for this export." }, "available_credits": { "type": "integer", "description": "Credits currently available on the account." } }, "required": [ "available_credits", "required_credits", "status", "validation_code" ] }, "Level1Location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "code", "id", "name" ] }, "Level2Location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" }, "level1_id": { "type": "integer" }, "level1_name": { "type": "string" } }, "required": [ "code", "id", "name" ] }, "Level3Location": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" }, "level1_id": { "type": "integer" }, "level2_id": { "type": "integer" }, "level1_name": { "type": "string" }, "level2_name": { "type": "string" } }, "required": [ "code", "id", "name" ] }, "LogoutResponse": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "message", "status" ] }, "RefreshTokenRequestRequest": { "type": "object", "properties": { "refresh": { "type": "string", "minLength": 1, "description": "The refresh token obtained at login." } }, "required": [ "refresh" ] }, "RefreshTokenResponse": { "type": "object", "properties": { "access": { "type": "string", "description": "New JWT access token." } }, "required": [ "access" ] }, "RegisterRequestPreferredLanguageEnum": { "enum": [ "bg", "cs", "da", "de", "el", "fr", "en", "es", "et", "fi", "he", "hr", "hu", "it", "lt", "lv", "nb", "nl", "pl", "pt", "ro", "sk", "sl", "sr", "sv", "th", "tr" ], "type": "string", "description": "* `bg` - bg\n* `cs` - cs\n* `da` - da\n* `de` - de\n* `el` - el\n* `fr` - fr\n* `en` - en\n* `es` - es\n* `et` - et\n* `fi` - fi\n* `he` - he\n* `hr` - hr\n* `hu` - hu\n* `it` - it\n* `lt` - lt\n* `lv` - lv\n* `nb` - nb\n* `nl` - nl\n* `pl` - pl\n* `pt` - pt\n* `ro` - ro\n* `sk` - sk\n* `sl` - sl\n* `sr` - sr\n* `sv` - sv\n* `th` - th\n* `tr` - tr" }, "RegisterRequestRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "description": "Account email address." }, "password1": { "type": "string", "writeOnly": true, "minLength": 1, "description": "Password." }, "password2": { "type": "string", "writeOnly": true, "minLength": 1, "description": "Password confirmation (must match password1)." }, "fingerprint": { "type": "string", "description": "Optional device fingerprint identifier used for signup fraud prevention." }, "fingerprint_request_id": { "type": "string", "description": "FingerprintJS request ID used for server-side fingerprint verification." }, "attribution": { "description": "Optional traffic attribution payload captured on the frontend." }, "preferred_language": { "allOf": [ { "$ref": "#/components/schemas/RegisterRequestPreferredLanguageEnum" } ], "default": "en", "description": "Two-letter UI language preference.\n\n* `bg` - bg\n* `cs` - cs\n* `da` - da\n* `de` - de\n* `el` - el\n* `fr` - fr\n* `en` - en\n* `es` - es\n* `et` - et\n* `fi` - fi\n* `he` - he\n* `hr` - hr\n* `hu` - hu\n* `it` - it\n* `lt` - lt\n* `lv` - lv\n* `nb` - nb\n* `nl` - nl\n* `pl` - pl\n* `pt` - pt\n* `ro` - ro\n* `sk` - sk\n* `sl` - sl\n* `sr` - sr\n* `sv` - sv\n* `th` - th\n* `tr` - tr" } }, "required": [ "email", "password1", "password2" ] }, "ResetPasswordRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "password": { "type": "string", "writeOnly": true, "minLength": 1 }, "password_confirmation": { "type": "string", "writeOnly": true, "minLength": 1 } }, "required": [ "password", "password_confirmation", "token" ] }, "ResetPasswordResponse": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "access": { "type": "string" }, "refresh": { "type": "string" } }, "required": [ "access", "message", "refresh", "status" ] }, "SearchHistoryItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "Search ID. Use this to check download status." }, "display_name": { "type": "string", "nullable": true }, "credits": { "type": "integer", "description": "Number of leads (= credits consumed)." }, "lead_count": { "type": "integer", "description": "Number of leads in the exported file." }, "created_at": { "type": "string", "format": "date-time", "description": "When the search was initiated (ISO 8601)." }, "status": { "type": "string", "description": "Processing status: PENDING, PROCESSING, COMPLETED, or FAILED." }, "link_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the download link expires (ISO 8601). Null if not yet available." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Search filters used (countries, categories, locations)." }, "export_kind": { "type": "string", "description": "Export type: full or delta." }, "baseline_search_id": { "type": "integer", "nullable": true }, "is_limited_by_credits": { "type": "boolean" }, "freshness": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Last checked fresh data report for this search." }, "freshness_checked_at": { "type": "string", "format": "date-time", "nullable": true }, "freshness_check_available": { "type": "boolean" }, "freshness_next_check_at": { "type": "string", "format": "date-time", "nullable": true }, "fresh_export_in_progress": { "type": "boolean" } }, "required": [ "baseline_search_id", "created_at", "credits", "display_name", "export_kind", "fresh_export_in_progress", "freshness", "freshness_check_available", "freshness_checked_at", "freshness_next_check_at", "id", "is_limited_by_credits", "lead_count", "link_expires_at", "metadata", "status" ] }, "SearchHistoryRenameResponse": { "type": "object", "properties": { "status": { "type": "string" }, "validation_code": { "type": "string" }, "id": { "type": "integer" }, "display_name": { "type": "string", "nullable": true } }, "required": [ "display_name", "id", "status", "validation_code" ] }, "SendResetLinkRequestRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "minLength": 1 } }, "required": [ "email" ] }, "StatusMessageResponse": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "message", "status" ] }, "SubscriptionPlan": { "type": "object", "properties": { "plan_type": { "type": "string", "description": "Plan tier name (e.g. 'starter', 'pro', 'enterprise').", "maxLength": 20 }, "monthly_credits": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648, "description": "Number of credits allocated per billing cycle." }, "price_per_month": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Monthly price in USD." }, "link_expiration_days": { "type": "integer", "maximum": 2147483647, "minimum": -2147483648, "description": "How many days download links remain valid." }, "product_id": { "type": "string", "maxLength": 100 }, "price_id": { "type": "string", "maxLength": 100 }, "is_active": { "type": "boolean", "description": "Whether this plan is currently available for purchase." }, "is_sellable": { "type": "boolean" }, "allows_fresh_exports": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "link_expiration_days", "monthly_credits", "plan_type", "price_id", "price_per_month", "product_id", "updated_at" ] } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key. Format: Token " }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token obtained from /api/auth/login/" } } }, "tags": [ { "name": "Authentication", "description": "Register, login, refresh tokens, and reset passwords." }, { "name": "Search", "description": "Search and preview business leads by country, category, and location." }, { "name": "Download", "description": "Export leads to CSV/Excel. Async workflow: initiate → poll → download." }, { "name": "History", "description": "View past searches and their download status." }, { "name": "Credits & Profile", "description": "Check credit balance, subscription plan, and user profile." }, { "name": "Geography", "description": "Countries, states/regions, counties, and cities for search filters." }, { "name": "API Keys", "description": "Create, list, and revoke persistent API keys for integrations." } ] }