{ "openapi": "3.0.0", "info": { "title": "Radar API", "description": "", "contact": { "email": "info@snitcher.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.snitcher.com", "description": "Production API" } ], "paths": { "/radar/operator/v1/tracking-scripts/{trackingScriptId}/company/find": { "post": { "tags": [ "Company" ], "summary": "Identify company for a session", "description": "Returns company information for the current visitor's session when available. Provide a session UUID when you want to restrict lookup to a specific session.", "operationId": "73808f0078864d0751c33cd0e9a5c1dd", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "Tracking script ID", "required": true, "schema": { "type": "string", "example": "12345" } } ], "requestBody": { "description": "Session context", "required": true, "content": { "application/json": { "schema": { "properties": { "session_uuid": { "description": "Lookup will be performed for this session UUID", "type": "string", "format": "uuid", "example": "42b7c5e0-76c0-4f8d-9b7c-6b8e1a2d3f45", "nullable": false }, "since": { "description": "Optional anchor date (ISO 8601, UTC). When provided, the session lookup is scoped to events on that single calendar day instead of the default last-2-days window — use it to identify sessions older than 2 days. The date must not be in the future or more than 30 days ago. Omit it to use the default window.", "type": "string", "format": "date", "example": "2026-05-11", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Company identified", "content": { "application/json": { "schema": { "required": [ "ip", "domain", "type", "company", "geoIP" ], "properties": { "ip": { "type": "string", "example": "203.0.113.42" }, "domain": { "type": "string", "example": "acme.com" }, "type": { "type": "string", "enum": [ "business", "educational", "government" ], "example": "business" }, "company": { "required": [ "name", "domain", "website", "industry", "founded_year", "employee_range", "annual_revenue", "total_funding", "location", "description", "phone", "geo", "profiles" ], "properties": { "name": { "type": "string", "example": "Acme Inc" }, "domain": { "type": "string", "example": "acme.com" }, "website": { "type": "string", "example": "https://www.acme.com" }, "industry": { "type": "string", "example": "Software" }, "founded_year": { "type": "string", "example": "2012", "nullable": true }, "employee_range": { "type": "string", "example": "51-200", "nullable": true }, "annual_revenue": { "type": "string", "example": "$10M-$50M", "nullable": true }, "total_funding": { "type": "string", "example": "$25M", "nullable": true }, "location": { "type": "string", "example": "San Francisco, CA", "nullable": true }, "description": { "type": "string", "example": "Acme builds widgets for modern teams.", "nullable": true }, "phone": { "type": "string", "example": "+1 415 555 0100", "nullable": true }, "geo": { "properties": { "country": { "type": "string", "example": "United States", "nullable": true }, "country_code": { "type": "string", "example": "US", "nullable": true }, "state": { "type": "string", "example": "California", "nullable": true }, "state_code": { "type": "string", "example": "CA", "nullable": true }, "postal_code": { "type": "string", "example": "94107", "nullable": true }, "city": { "type": "string", "example": "San Francisco", "nullable": true }, "street": { "type": "string", "example": null, "nullable": true }, "street_number": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "geoIP": { "properties": { "country": { "type": "string", "example": "United States", "nullable": true }, "country_code": { "type": "string", "example": "US", "nullable": true }, "city": { "type": "string", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "example": "California", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not found or ISP identified", "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "ip", "fuzzy", "domain", "type", "geoIP" ], "properties": { "ip": { "type": "string", "example": "203.0.113.42" }, "fuzzy": { "type": "boolean", "example": false }, "domain": { "type": "string", "example": "example-isp.net" }, "type": { "type": "string", "example": "isp" }, "geoIP": { "properties": { "country": { "type": "string", "example": "United States" }, "country_code": { "type": "string", "example": "US" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "New York" } }, "type": "object" } }, "type": "object" }, { "properties": { "error": { "type": "string", "example": "not found" } }, "type": "object" }, { "description": "Session not yet ingested — poll again after retry_after seconds", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Session not found" }, "retry_after": { "type": "integer", "example": 5 } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Your subscription does not allow access to this endpoint. Please contact support." } }, "type": "object" } } } } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/tracking-scripts": { "get": { "tags": [ "Tracking scripts" ], "summary": "List tracking scripts", "description": "Returns a paginated list of tracking scripts for the given workspace. Filtering by description or internal identifier is supported.", "operationId": "1481129ca2be03190a5cf9840f5c88ad", "parameters": [ { "name": "description", "in": "query", "description": "Optional description filter", "required": false, "schema": { "type": "string", "example": "Homepage tracker" } }, { "name": "internal_identifier", "in": "query", "description": "Optional internal identifier filter", "required": false, "schema": { "type": "string", "example": "homepage-tracker" } }, { "name": "page", "in": "query", "description": "The page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "size", "in": "query", "description": "The number of trackingscripts per page (1-1000)", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "example": 10 } } ], "responses": { "200": { "description": "Tracking scripts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScript" } } }, "type": "object" } ] } } } }, "403": { "description": "You don't have permission to do this" } }, "security": [ { "Snitcher bearer token": [] } ] }, "post": { "tags": [ "Tracking scripts" ], "summary": "Generate a tracking script", "operationId": "8846ecf4073b2d61f30f8a2e54b6db25", "requestBody": { "description": "Tracking script generation parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "internal_identifier" ], "properties": { "internal_identifier": { "description": "The identifier for the tracking script as used in your system. Should be unique for every generated tracking script", "type": "string", "example": "my-tracking-script" }, "description": { "description": "A description for the tracking script", "type": "string", "example": "This is a tracking script for my website" }, "domains": { "description": "Domains to whitelist for this tracking script. Only traffic from these domains (and their subdomains) is accepted.", "type": "array", "items": { "type": "string", "example": "example.com" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Tracking script generated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScript" } } }, "type": "object" } } } }, "422": { "description": "The identifier is already in use" } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/tracking-scripts/{trackingScriptId}": { "get": { "tags": [ "Tracking scripts" ], "summary": "Get a single tracking script", "description": "Returns a single tracking script by ID", "operationId": "05691107840483c3e446df53f382f982", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "ID of the tracking script to retrieve", "required": true, "schema": { "type": "string", "example": "ro123abc" } } ], "responses": { "200": { "description": "Tracking script retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TrackingScript_TrackingScript" }, { "properties": { "filters": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptFilter" } } }, "type": "object" } ] } }, "type": "object" } } } }, "403": { "description": "You don't have permission to do this" }, "404": { "description": "Tracking script not found" } }, "security": [ { "Snitcher bearer token": [] } ] }, "patch": { "tags": [ "Tracking scripts" ], "summary": "Update a tracking script", "operationId": "1e50fc0ce822553556979db1ec0122e5", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "The ID of the tracking script to update", "required": true, "schema": { "type": "string", "example": "12345" } } ], "requestBody": { "description": "Tracking script update parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "active" ], "properties": { "active": { "description": "Boolean to deactivate or reactivate the tracking script", "type": "boolean", "example": "false" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tracking script updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScript" } } }, "type": "object" } } } } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/tracking-scripts/{trackingScriptId}/filters": { "get": { "tags": [ "Tracking scripts" ], "summary": "List tracking script filters", "operationId": "c9234c990873007f19faf362cc6b8fb8", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "The ID of the tracking script to list filters for", "required": true, "schema": { "type": "string", "example": "12345" } } ], "responses": { "200": { "description": "Tracking script filters retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptFilter" } } }, "type": "object" } } } }, "404": { "description": "Tracking script not found" } }, "security": [ { "Snitcher bearer token": [] } ] }, "put": { "tags": [ "Tracking scripts" ], "summary": "Replace tracking script filters", "operationId": "9805f05bb01c96b56aced1ae23bfc97a", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "The ID of the tracking script to replace filters for", "required": true, "schema": { "type": "string", "example": "12345" } } ], "requestBody": { "description": "New set of tracking script filters to replace existing ones", "required": true, "content": { "application/json": { "schema": { "properties": { "filters": { "type": "array", "items": { "required": [ "tracking_script_filter_field", "tracking_script_filter_type", "filter_value" ], "properties": { "tracking_script_filter_field": { "description": "Must be one of the TrackingScriptFilterField enum values", "type": "string", "enum": [ "country", "url" ] }, "tracking_script_filter_type": { "description": "Type of filter", "type": "string", "enum": [ "blacklist", "whitelist" ] }, "filter_value": { "description": "Value for the filter", "type": "string", "maxLength": 255 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Tracking script filters replaced successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptFilter" } } }, "type": "object" } } } } }, "security": [ { "Snitcher bearer token": [] } ] }, "post": { "tags": [ "Tracking scripts" ], "summary": "Create a tracking script filter", "operationId": "6b2c460d3a5fbc9b07b0fe990f10dc05", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "The ID of the tracking script to create a filter for", "required": true, "schema": { "type": "string", "example": "12345" } } ], "requestBody": { "description": "Tracking script filter parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "tracking_script_filter_type", "tracking_script_filter_field", "filter_value" ], "properties": { "tracking_script_filter_type": { "description": "The type of the filter (blacklist or whitelist)", "type": "string", "enum": [ "blacklist", "whitelist" ], "example": "blacklist" }, "tracking_script_filter_field": { "description": "The field to filter on (country or url)", "type": "string", "enum": [ "country", "url" ], "example": "country" }, "filter_value": { "description": "The value to filter on, e.g. 'US' for country or a URL for url field", "type": "string", "example": "US" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tracking script filter created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptFilter" } }, "type": "object" } } } } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/tracking-scripts/{trackingScriptId}/filters/{filterUuid}": { "delete": { "tags": [ "Tracking scripts" ], "summary": "Delete a tracking script filter", "operationId": "c8a179586b309214b001a0d5cef22b41", "parameters": [ { "name": "trackingScriptId", "in": "path", "description": "The ID of the tracking script to delete a filter from", "required": true, "schema": { "type": "string", "example": "12345" } }, { "name": "filterUuid", "in": "path", "description": "The UUID of the filter to delete", "required": true, "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Tracking script filter deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Tracking script filter deleted successfully" } }, "type": "object" } } } } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get tracking script usage", "description": "Returns usage data for tracking scripts in the workspace", "operationId": "85826461a124aa9e3380bcc85a1d0bcf", "parameters": [ { "name": "date", "in": "query", "description": "Optional date (Y-m-d) to get usage for the cycle active on that date. If not provided, returns usage for the current cycle.", "required": false, "schema": { "type": "string", "format": "date", "example": "2025-10-15" } } ], "responses": { "200": { "description": "Usage data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "usageCycleFrom": { "description": "Start date of the usage cycle", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00+00:00" }, "usageCycleTo": { "description": "End date of the usage cycle", "type": "string", "format": "date-time", "example": "2023-01-31T23:59:59+00:00" }, "eventUsage": { "description": "Total number of events used", "type": "integer", "example": 12345 }, "trackingScriptUsages": { "description": "Usage data for each tracking script", "type": "array", "items": { "properties": { "trackingScriptId": { "description": "ID of the tracking script", "type": "string", "example": "12345" }, "eventUsage": { "description": "Number of events used by this tracking script", "type": "integer", "example": 5678 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "You don't have permission to do this" }, "422": { "description": "Invalid date format" } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/company/usage": { "get": { "tags": [ "Usage" ], "summary": "Get IP-to-Company (Reveal API) credit usage", "description": "Returns billable IP-to-Company usage for the current billing cycle, per tracking script. A unit is a distinct successful (HTTP 200) de-anonymisation deduped per (tracking script, monthly window) — the exact figure billing charges a credit for. Operators reconcile this per cycle to know which lookups were billed.", "operationId": "d090c9837ca90404efd04f45a188deff", "responses": { "200": { "description": "Usage data retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "usageCycleFrom": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00+00:00" }, "usageCycleTo": { "type": "string", "format": "date-time", "example": "2023-12-31T23:59:59+00:00" }, "revealUsage": { "description": "Total billed IP-to-Company credits this cycle", "type": "integer", "example": 12345 }, "trackingScriptUsages": { "description": "Billed IP-to-Company credits per tracking script", "type": "array", "items": { "properties": { "trackingScriptId": { "type": "string", "example": "ro_abc123" }, "revealUsage": { "type": "integer", "example": 5678 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Workspace has no active Reveal API plan" } }, "security": [ { "Snitcher bearer token": [] } ] } }, "/radar/operator/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook configuration", "operationId": "dd7040c4fa7fd5e99f0bc189ff93c326", "responses": { "200": { "description": "Webhook configuration retrieved successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IngestPipelineConfiguration_PipelineConfiguration" } } }, "type": "object" } } } }, "403": { "description": "You don't have permission to do this" } }, "security": [ { "Snitcher bearer token": [] } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook configuration", "operationId": "2ec6db4c3a09373a53157dbe557580e3", "requestBody": { "description": "Webhook configuration parameters", "required": true, "content": { "application/json": { "schema": { "properties": { "delivery": { "description": "Webhook delivery configuration", "properties": { "webhook_url": { "description": "URL to send webhook events to", "type": "string", "example": "https://example.com/webhook" }, "webhook_secret": { "description": "Secret used to sign webhook payloads", "type": "string", "example": "my-little-secret" } }, "type": "object" }, "event_aggregation": { "description": "Delivery mode. `per_session` (recommended) groups all events of a session into one payload sent after the session ends. `per_event` pushes each event in near real-time. `per_event` is not available while identifications are enabled.", "type": "string", "enum": [ "per_event", "per_session" ], "example": "per_session" } }, "type": "object" } } } }, "responses": { "200": { "description": "Webhook configuration updated successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IngestPipelineConfiguration_PipelineConfiguration" } }, "message": { "type": "string", "example": "Webhook configuration updated successfully" } }, "type": "object" } } } }, "403": { "description": "You don't have permission to do this" }, "422": { "description": "Validation error" } }, "security": [ { "Snitcher bearer token": [] } ] } } }, "components": { "schemas": { "IngestPipelineConfiguration_Delivery": { "required": [ "webhook_url" ], "properties": { "webhook_url": { "type": "string" }, "signature": { "type": "string", "nullable": true } }, "type": "object" }, "IngestPipelineConfiguration_PipelineConfiguration": { "properties": { "delivery": { "$ref": "#/components/schemas/IngestPipelineConfiguration_Delivery" }, "event_aggregation": { "description": "Delivery mode. `per_session` groups all events of a session into one payload sent after the session ends; `per_event` pushes each event in near real-time.", "type": "string", "enum": [ "per_event", "per_session" ], "example": "per_session" } }, "type": "object" }, "Organisation_Organisation": { "required": [ "uuid", "name", "website", "first_seen", "last_seen", "profiles", "tags", "segments" ], "properties": { "uuid": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Pirate Inc." }, "website": { "type": "string", "example": "https://pirateinc.com" }, "first_seen": { "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00Z" }, "last_seen": { "type": "string", "format": "date-time", "example": "2021-01-01T00:00:00Z" }, "logo": { "type": "string", "example": "https://pirateinc.com/logo.png", "nullable": true }, "address": { "$ref": "#/components/schemas/Value_Address" }, "founded": { "type": "number", "example": "2000", "nullable": true }, "size": { "$ref": "#/components/schemas/Organisation_EmployeeRange" }, "industry": { "type": "string", "example": "Piracy", "nullable": true }, "phone": { "type": "string", "example": "+49 123 4567890", "nullable": true }, "email": { "type": "string", "example": "john@example.org", "nullable": true }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Organisation_SocialProfile" } }, "tags": { "type": "array", "items": { "type": "string" } }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Organisation_Segment" } }, "total_pageviews": { "type": "integer", "example": 42, "nullable": true }, "total_time_on_site": { "type": "string", "example": "1:02:05", "nullable": true }, "visitor_locations": { "type": "array", "items": { "type": "string" }, "example": [ "Amsterdam, NL" ] } }, "type": "object" }, "Organisation_OrganisationContact": { "required": [ "uuid", "first_name", "last_name", "email", "position", "department", "seniority", "country", "profiles" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "position": { "type": "string" }, "department": { "type": "string" }, "seniority": { "type": "string" }, "country": { "type": "string" }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Organisation_SocialProfile" } } }, "type": "object" }, "Organisation_Segment": { "required": [ "uuid", "name" ], "properties": { "uuid": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Hot leads" } }, "type": "object" }, "Organisation_SocialProfile": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Twitter" }, "handle": { "type": "string", "example": "@pirateinc", "nullable": true }, "url": { "type": "string", "example": "https://twitter.com/pirateinc", "nullable": true } }, "type": "object" }, "TrackingScript_TrackingScript": { "required": [ "tracking_script_id", "internal_identifier", "active" ], "properties": { "tracking_script_id": { "type": "string" }, "internal_identifier": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "domains": { "type": "array", "items": { "type": "string", "example": "example.com" } } }, "type": "object" }, "TrackingScript_TrackingScriptFilter": { "required": [ "uuid", "filter_value" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "tracking_script_filter_field": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptFilterField" }, "tracking_script_filter_type": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptFilterType" }, "filter_value": { "type": "string" } }, "type": "object" }, "TrackingScript_TrackingScriptUsage": { "required": [ "tracking_script_id", "event_usage" ], "properties": { "tracking_script_id": { "type": "string" }, "event_usage": { "type": "number" } }, "type": "object" }, "TrackingScript_Usage": { "required": [ "event_usage", "usage_cycle_from", "usage_cycle_to", "tracking_script_usages" ], "properties": { "event_usage": { "type": "number" }, "usage_cycle_from": { "type": "string", "format": "date-time" }, "usage_cycle_to": { "type": "string", "format": "date-time" }, "tracking_script_usages": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingScript_TrackingScriptUsage" } } }, "type": "object" }, "Value_Address": { "required": [ "street", "address", "full_address", "city", "state" ], "properties": { "street": { "type": "string", "example": "Hollywood Blvd" }, "street_number": { "type": "string", "example": "123", "nullable": true }, "postal_code": { "type": "string", "example": "90028", "nullable": true }, "address": { "type": "string", "example": "Hollywood Blvd 123" }, "full_address": { "type": "string", "example": "Hollywood Blvd 123, Los Angeles, California, US" }, "city": { "type": "string", "example": "Los Angeles" }, "state": { "type": "string", "example": "California" }, "country": { "type": "string", "example": "US", "nullable": true }, "latitude": { "type": "number", "example": "34.0522", "nullable": true }, "longitude": { "type": "number", "example": "-118.2437", "nullable": true } }, "type": "object" }, "Value_Location": { "required": [ "city", "state" ], "properties": { "city": { "type": "string", "example": "Los Angeles" }, "state": { "type": "string", "example": "California" }, "country": { "type": "string", "example": "US", "nullable": true }, "latitude": { "type": "number", "example": "34.0522", "nullable": true }, "longitude": { "type": "number", "example": "-118.2437", "nullable": true } }, "type": "object" }, "Workspace_Workspace": { "required": [ "uuid", "name", "url", "tracking_script_id", "tracking_script_snippet", "available_tags" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "ACME Inc." }, "url": { "type": "string", "example": "https://acme.com" }, "tracking_script_id": { "type": "string", "example": "s123456789" }, "tracking_script_snippet": { "type": "string", "example": "" }, "available_tags": { "type": "array", "items": { "type": "string" }, "example": [ "marketing", "design" ] }, "status": { "$ref": "#/components/schemas/Workspace_Status" }, "usage_limit": { "type": "number", "example": "1000", "nullable": true } }, "type": "object" }, "Organisation_EmployeeRange": { "type": "string", "enum": [ "1-10 employees", "11-50 employees", "51-200 employees", "201-500 employees", "501-1000 employees", "1001-5000 employees", "5001-10,000 employees", "10,001+ employees" ] }, "TrackingScript_TrackingScriptFilterField": { "type": "string", "enum": [ "country", "url" ] }, "TrackingScript_TrackingScriptFilterType": { "type": "string", "enum": [ "blacklist", "whitelist" ] }, "Workspace_Status": { "type": "string", "enum": [ "active", "inactive", "on_trial" ] }, "CustomField": { "title": "Custom Field", "description": "A custom field definition for organisations", "properties": { "identifier": { "description": "The unique identifier of the field", "type": "string", "example": "industry" }, "key": { "description": "The machine-readable key of the field", "type": "string", "example": "industry" }, "name": { "description": "The human-readable name of the field", "type": "string", "example": "Industry" }, "entity_type": { "description": "The entity type the field belongs to", "type": "string", "example": "organisation" }, "type": { "description": "The data type of the field", "type": "string", "example": "text" }, "description": { "type": "string", "example": "The primary industry of the company.", "nullable": true }, "group": { "description": "The group the field belongs to", "type": "string", "example": "custom" }, "is_visible": { "type": "boolean", "example": true }, "source": { "description": "The source of the field", "type": "string", "example": "manual" }, "rules": { "type": "array", "items": { "type": "object" } }, "is_system": { "type": "boolean", "example": false }, "options": { "type": "array", "items": { "type": "object" } }, "visible_in_spotter": { "description": "Whether this field's values are exposed in the Spotter API response", "type": "boolean", "example": false } }, "type": "object" }, "CustomFieldValue": { "title": "Custom Field Value", "description": "A custom field value set on an organisation", "properties": { "field_identifier": { "description": "The identifier of the field", "type": "string", "example": "industry" }, "field_key": { "description": "The machine-readable key of the field", "type": "string", "example": "industry" }, "field_type": { "description": "The data type of the field", "type": "string", "example": "text" }, "value": { "description": "The value of the field", "example": "Technology" }, "source": { "description": "The source of the value", "type": "string", "example": "manual" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true } }, "type": "object" }, "Pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 10 }, "per_page": { "type": "integer", "example": 15 }, "total": { "type": "integer", "example": 150 }, "next_page_url": { "type": "string", "example": "https://api.example.com/v1/workspaces?page=2", "nullable": true }, "prev_page_url": { "type": "string", "example": null, "nullable": true }, "first_page_url": { "type": "string", "example": "https://api.example.com/v1/workspaces?page=1", "nullable": true }, "last_page_url": { "type": "string", "example": "https://api.example.com/v1/workspaces?page=10", "nullable": true }, "path": { "type": "string", "example": "https://api.example.com/v1/workspaces", "nullable": true }, "from": { "type": "integer", "example": 1, "nullable": true }, "to": { "type": "integer", "example": 15, "nullable": true }, "data": { "type": "array", "items": {} } }, "type": "object" }, "FilterCondition": { "required": [ "field", "comparison" ], "properties": { "field": { "description": "The field to filter on.", "type": "string" }, "comparison": { "description": "The comparison operator to use. The relative date comparisons (`less_than_x_units_ago`, `more_than_x_units_ago`) require a numeric `value` and a `unit`.", "type": "string", "enum": [ "equal", "not_equal", "contains", "not_contains", "starts_with", "ends_with", "doesnt_start_with", "doesnt_end_with", "in", "not_in", "between", "not_between", "greater_than", "less_than", "greater_than_or_equal", "less_than_or_equal", "less_than_x_units_ago", "more_than_x_units_ago", "set", "not_set", "is_true", "is_false" ] }, "value": { "description": "The value(s) for the comparison. Not required for `set` and `not_set`.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "number" } } ] }, "unit": { "description": "The date unit. Required for the relative date comparisons (`less_than_x_units_ago`, `more_than_x_units_ago`), not allowed otherwise.", "type": "string", "enum": [ "second", "minute", "hour", "day", "week", "month", "year" ] } }, "type": "object" }, "FilterGroup": { "required": [ "operator", "conditions" ], "properties": { "operator": { "description": "The logical operator for the group. 'AND' means all conditions must match, 'OR' means at least one condition must match.", "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "description": "A list of filter conditions or nested filter groups.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FilterCondition" }, { "$ref": "#/components/schemas/FilterGroup" } ] } } }, "type": "object" }, "SetOrganisationCustomFieldValuesRequest": { "title": "Set Organisation Custom Field Values Request", "required": [ "custom_fields" ], "properties": { "custom_fields": { "description": "Map of field key to value (at most 50 keys per request). Unknown keys are created automatically, with their type inferred from the value. Every value must be non-empty — sending an empty array does not clear a multi-select; use the DELETE custom-fields/{key} endpoint to remove a value.", "type": "object", "example": { "deal_size": 50000, "account_tier": "enterprise" } } }, "type": "object" }, "StoreCustomFieldRequest": { "title": "Store Custom Field Request", "description": "Request body for creating a custom field definition", "required": [ "name", "type" ], "properties": { "name": { "description": "The human-readable name of the field", "type": "string", "maxLength": 255, "example": "Industry" }, "type": { "description": "The data type of the field", "type": "string", "example": "text" }, "key": { "description": "The machine-readable key. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Generated from the name when omitted.", "type": "string", "maxLength": 255, "example": "industry", "nullable": true }, "description": { "type": "string", "maxLength": 1000, "example": "The primary industry of the company.", "nullable": true }, "visible_in_spotter": { "description": "Expose this field's values in the Spotter API response. Off by default: exposed values become readable on your website by any script that can access the Spotter response.", "type": "boolean", "example": false, "nullable": true }, "field_rules": { "type": "array", "items": { "required": [ "type" ], "properties": { "type": { "description": "The rule type", "type": "string" }, "config": { "type": "object", "nullable": true } }, "type": "object" }, "nullable": true }, "options": { "type": "array", "items": { "required": [ "key", "label" ], "properties": { "key": { "type": "string", "maxLength": 255, "example": "technology" }, "label": { "type": "string", "maxLength": 255, "example": "Technology" }, "color": { "type": "string", "maxLength": 50, "example": "#FF0000", "nullable": true } }, "type": "object" }, "nullable": true } }, "type": "object" }, "TagRequest": { "title": "Tag Request", "description": "Request parameters for creating a tag", "properties": { "tag_name": { "description": "The name of the tag", "type": "string", "example": "Tag Name" } }, "type": "object" }, "UpdateCustomFieldRequest": { "title": "Update Custom Field Request", "description": "Request body for updating a custom field definition", "properties": { "name": { "description": "The human-readable name of the field", "type": "string", "maxLength": 255, "example": "Industry", "nullable": true }, "description": { "type": "string", "maxLength": 1000, "example": "The primary industry of the company.", "nullable": true }, "visible_in_spotter": { "description": "Expose this field's values in the Spotter API response. Omitted or null leaves the current setting unchanged; exposed values become readable on your website by any script that can access the Spotter response.", "type": "boolean", "example": false, "nullable": true }, "field_rules": { "type": "array", "items": { "required": [ "type" ], "properties": { "type": { "description": "The rule type", "type": "string" }, "config": { "type": "object", "nullable": true } }, "type": "object" }, "nullable": true }, "options": { "type": "array", "items": { "required": [ "key", "label" ], "properties": { "key": { "type": "string", "maxLength": 255, "example": "technology" }, "label": { "type": "string", "maxLength": 255, "example": "Technology" }, "color": { "type": "string", "maxLength": 50, "example": "#FF0000", "nullable": true } }, "type": "object" }, "nullable": true } }, "type": "object" } }, "securitySchemes": { "Snitcher bearer token": { "type": "http", "description": "Enter your personal access token (PAT) to authenticate", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Tracking scripts", "description": "Endpoints for tracking scripts" }, { "name": "Company", "description": "Endpoints for companies" }, { "name": "Usage", "description": "Endpoints for tracking script usage" }, { "name": "Webhooks", "description": "Endpoints for webhook settings" } ] }