{
"openapi" : "3.1.0",
"components" : {
"schemas" : {
"ConversionResponse" : {
"type" : "object",
"required" : [ "opticksId", "conversionDate", "threats", "riskLevel" ],
"properties" : {
"opticksId" : {
"type" : "string"
},
"sessionId" : {
"type" : [ "string", "null" ]
},
"externalId" : {
"type" : [ "string", "null" ]
},
"transactionId" : {
"type" : [ "string", "null" ]
},
"conversionDate" : {
"type" : "string"
},
"threats" : {
"type" : "array",
"uniqueItems" : true,
"items" : {
"type" : "string"
}
},
"riskLevel" : {
"type" : "string"
},
"sensorName" : {
"type" : [ "string", "null" ]
},
"vars" : {
"type" : [ "object", "null" ],
"additionalProperties" : {
"type" : "string"
}
}
}
},
"Dimension" : {
"type" : "string",
"enum" : [ "browser", "sensor", "country", "isp", "referer", "os", "device", "day", "hour", "month", "year", "riskLevel", "var1", "var2", "var3", "var4", "trafficType", "utm_source", "utm_campaign", "utm_medium", "utm_content", "utm_term", "googleCampaignId", "googleCampaignName", "googleAccountId", "googleAccountName", "googleCampaignType" ]
},
"DimensionSaving" : {
"type" : "string",
"enum" : [ "day", "month", "hour", "googleCampaignId", "googleAccountId", "googleCampaignName", "googleAccountName", "googleCampaignType" ]
},
"ExclusionStatsApiRequest" : {
"type" : "object",
"properties" : {
"metrics" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/MetricExclusion"
},
"examples" : [ [ "googleExclusionEvents", "tiktokExclusionEvents", "metaExclusionEvents", "microsoftExclusionEvents" ] ]
},
"dimensions" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Dimension"
},
"examples" : [ [ "day", "country" ] ]
},
"filters" : {
"type" : "object",
"additionalProperties" : {
"type" : "array",
"items" : {
"type" : "string"
}
},
"description" : "A map where keys are Dimensions and values are a list of values to filter stats",
"examples" : [ {
"country" : [ "US", "UK", "DE" ],
"os" : [ "Android" ]
} ]
},
"order" : {
"$ref" : "#/components/schemas/MetricExclusion",
"type" : "string",
"examples" : [ "googleExclusionEvents" ]
},
"sort" : {
"type" : "string",
"examples" : [ "DESC" ],
"enum" : [ "ASC", "DESC" ]
},
"startDate" : {
"type" : "string",
"description" : "Start date in format YYYY-MM-dd HH:mm:ss. Account timezone will be automatically applied",
"examples" : [ "2026-03-18 00:00:00" ]
},
"endDate" : {
"type" : "string",
"description" : "End date in format YYYY-MM-dd HH:mm:ss. Account timezone will be automatically applied",
"examples" : [ "2026-03-18 23:59:59" ]
}
},
"required" : [ "order", "startDate", "endDate" ]
},
"ExclusionStatsApiResponse" : {
"type" : "object",
"properties" : {
"dimensions" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"metrics" : {
"type" : "object",
"additionalProperties" : {
"type" : "number",
"format" : "double"
}
}
}
},
"GoogleAccountInfo" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"format" : "int64"
},
"descriptiveName" : {
"type" : [ "string", "null" ]
},
"timezone" : {
"type" : [ "string", "null" ]
},
"currencyCode" : {
"type" : [ "string", "null" ]
},
"trackingTemplate" : {
"type" : [ "string", "null" ]
},
"finalURLSuffix" : {
"type" : [ "string", "null" ]
},
"manager" : {
"type" : "boolean"
},
"integrationStatus" : {
"type" : [ "string", "null" ]
},
"childAccounts" : {
"type" : [ "array", "null" ],
"items" : {
"$ref" : "#/components/schemas/GoogleAccountInfo"
}
},
"prevention" : {
"type" : "boolean"
}
}
},
"LeadApiAnalysis" : {
"type" : "object",
"properties" : {
"ipRisks" : {
"type" : "array",
"items" : {
"type" : "string"
}
},
"detections" : {
"type" : "object",
"additionalProperties" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}
},
"LeadApiDevice" : {
"type" : "object",
"properties" : {
"model" : {
"type" : [ "string", "null" ]
},
"os" : {
"type" : [ "string", "null" ]
},
"browser" : {
"type" : [ "string", "null" ]
},
"app" : {
"type" : [ "string", "null" ]
},
"languages" : {
"type" : [ "string", "null" ]
}
}
},
"LeadApiLocation" : {
"type" : "object",
"properties" : {
"country" : {
"type" : [ "string", "null" ]
},
"lat" : {
"type" : [ "number", "null" ],
"format" : "double"
},
"lon" : {
"type" : [ "number", "null" ],
"format" : "double"
},
"ip" : {
"type" : [ "string", "null" ]
},
"isp" : {
"type" : [ "string", "null" ]
},
"timezone" : {
"type" : [ "string", "null" ]
},
"timezoneMatch" : {
"type" : "boolean"
}
}
},
"LeadApiResponse" : {
"type" : "object",
"required" : [ "id", "sessionId", "hitId", "formId", "email", "quality", "date", "page", "fullUrl", "analysis", "device", "location", "params" ],
"properties" : {
"id" : {
"type" : "string"
},
"sessionId" : {
"type" : "string"
},
"hitId" : {
"type" : "string"
},
"formId" : {
"type" : [ "string", "null" ]
},
"email" : {
"type" : "string"
},
"quality" : {
"anyOf" : [ {
"$ref" : "#/components/schemas/LeadVeracity"
}, {
"type" : "null"
} ]
},
"date" : {
"type" : "string"
},
"page" : {
"type" : "string"
},
"fullUrl" : {
"type" : "string"
},
"analysis" : {
"$ref" : "#/components/schemas/LeadApiAnalysis"
},
"device" : {
"$ref" : "#/components/schemas/LeadApiDevice"
},
"location" : {
"$ref" : "#/components/schemas/LeadApiLocation"
},
"params" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
}
}
},
"LeadVeracity" : {
"type" : "string",
"enum" : [ "Legitimate", "Suspicious", "Invalid" ]
},
"Metric" : {
"type" : "string",
"enum" : [ "pageviews", "conversions", "sessions", "conversionRate", "lowRiskSessions", "mediumRiskSessions", "highRiskSessions", "lowRiskPageviews", "mediumRiskPageviews", "highRiskPageviews", "lowRiskConversions", "mediumRiskConversions", "highRiskConversions", "BadBotPageviews", "BadBotConversions", "DataTamperingPageviews", "DataTamperingConversions", "NonCompliantTrafficPageviews", "NonCompliantTrafficConversions", "TelemetryMissingPageviews", "TelemetryMissingConversions", "StatisticalAnomaliesPageviews", "StatisticalAnomaliesConversions", "goodBotsConversions", "goodBotsPageviews", "adultKeywordsInHeadersPageviews", "adultKeywordsInHeadersConversions", "nonPlayStoreAPKPageviews", "nonPlayStoreAPKConversions", "offerNotRenderedPageviews", "offerNotRenderedConversions", "automatedSoftwarePageviews", "automatedSoftwareConversions", "userAgentTamperingPageviews", "userAgentTamperingConversions", "regularIframeHits", "regularIframeConversions", "IPFlaggedForAbusePageviews", "IPFlaggedForAbuseConversions", "IPFlaggedAsMalwarePageviews", "IPFlaggedAsMalwareConversions", "VPNProxyPageviews", "VPNProxyConversions", "hostingDatacenterHits", "hostingDatacenterConversions", "requestTamperingPageviews", "requestTamperingConversions", "MSISDNInjectionPageviews", "MSISDNInjectionConversions", "invalidAppNamePageviews", "invalidAppNameConversions", "bypassAttemptPageviews", "bypassAttemptConversions", "browserWithoutJavascriptPageviews", "browserWithoutJavascriptConversions", "oldGenerationBrowserPageviews", "oldGenerationBrowserConversions", "facebookBotPageviews", "facebookBotConversions", "googleBotPageviews", "googleBotConversions", "bingBotPageviews", "bingBotConversions", "genericGoodBotPageviews", "genericGoodBotConversions", "metaExclusionEvents", "microsoftExclusionEvents", "tiktokExclusionEvents", "googleAdsAudienceExclusionEvents" ]
},
"MetricExclusion" : {
"type" : "string",
"enum" : [ "metaExclusionEvents", "microsoftExclusionEvents", "tiktokExclusionEvents", "googleExclusionEvents" ]
},
"MetricSaving" : {
"type" : "string",
"enum" : [ "googleIpExclusions", "googleCost", "googleClicks", "googleIpExclusionSavings", "pmaxAudienceSavings", "searchDisplayAudienceSavings", "shoppingAudienceSavings", "pmaxExclusionEvents", "searchDisplayExclusionEvents", "shoppingExclusionEvents" ]
},
"SavingsStatsApiRequest" : {
"type" : "object",
"properties" : {
"metrics" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/MetricSaving"
},
"examples" : [ [ "googleIpExclusions", "googleClicks", "googleIpExclusionSavings", "searchDisplayExclusionEvents" ] ]
},
"dimensions" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/DimensionSaving"
},
"examples" : [ [ "googleCampaignType", "googleCampaignName" ] ]
},
"filters" : {
"type" : "object",
"additionalProperties" : {
"type" : "array",
"items" : {
"type" : "string"
}
},
"description" : "A map where keys are Google Savings Dimensions and values are a list of values to filter stats",
"examples" : [ {
"googleCampaignType" : [ "SEARCH", "DISPLAY" ],
"googleAccountId" : [ "1581096992" ]
} ]
},
"order" : {
"$ref" : "#/components/schemas/MetricSaving",
"type" : "string",
"examples" : [ "googleIpExclusions" ]
},
"sort" : {
"type" : "string",
"examples" : [ "DESC" ],
"enum" : [ "ASC", "DESC" ]
},
"startDate" : {
"type" : "string",
"description" : "Start date in format YYYY-MM-dd HH:mm:ss. Account timezone will be automatically applied",
"examples" : [ "2026-03-18 00:00:00" ]
},
"endDate" : {
"type" : "string",
"description" : "End date in format YYYY-MM-dd HH:mm:ss. Account timezone will be automatically applied",
"examples" : [ "2026-03-18 23:59:59" ]
}
},
"required" : [ "order", "startDate", "endDate" ]
},
"SavingsStatsApiResponse" : {
"type" : "object",
"properties" : {
"dimensions" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"metrics" : {
"type" : "object",
"additionalProperties" : {
"type" : "number",
"format" : "double"
}
}
}
},
"SecurityConfigurationAPIRequest" : {
"type" : "object",
"properties" : {
"blockAdultAcquisitionTraffic" : {
"type" : "boolean"
},
"blockAutomatedSoftware" : {
"type" : "boolean"
},
"blockOfferNotRendered" : {
"type" : "boolean"
},
"blockAbuseIps" : {
"type" : "boolean"
},
"blockMalwareIps" : {
"type" : "boolean"
},
"blockVPNProxies" : {
"type" : "boolean"
},
"blockHostingProxies" : {
"type" : "boolean"
},
"blockUATampering" : {
"type" : "boolean"
},
"blockBypassAttempts" : {
"type" : "boolean"
},
"blockMSISDNInjection" : {
"type" : "boolean"
},
"blockInvalidAppName" : {
"type" : "boolean"
},
"blockBrowsersWithoutJavascript" : {
"type" : "boolean"
},
"blockOldGenerationBrowsers" : {
"type" : "boolean"
},
"blockInvalidRequests" : {
"type" : "boolean"
},
"blockRegularIframeTraffic" : {
"type" : "boolean"
},
"blockNonPlayStoreApk" : {
"type" : "boolean"
}
}
},
"SecurityConfigurationAPIResponse" : {
"type" : "object",
"properties" : {
"blockAdultAcquisitionTraffic" : {
"type" : "boolean"
},
"blockAutomatedSoftware" : {
"type" : "boolean"
},
"blockOfferNotRendered" : {
"type" : "boolean"
},
"blockAbuseIps" : {
"type" : "boolean"
},
"blockMalwareIps" : {
"type" : "boolean"
},
"blockVPNProxies" : {
"type" : "boolean"
},
"blockHostingProxies" : {
"type" : "boolean"
},
"blockUATampering" : {
"type" : "boolean"
},
"blockBypassAttempts" : {
"type" : "boolean"
},
"blockMSISDNInjection" : {
"type" : "boolean"
},
"blockInvalidAppName" : {
"type" : "boolean"
},
"blockBrowsersWithoutJavascript" : {
"type" : "boolean"
},
"blockOldGenerationBrowsers" : {
"type" : "boolean"
},
"blockInvalidRequests" : {
"type" : "boolean"
},
"blockRegularIframeTraffic" : {
"type" : "boolean"
},
"blockNonPlayStoreApk" : {
"type" : "boolean"
}
}
},
"SensorJSAPIRequest" : {
"type" : "object",
"properties" : {
"name" : {
"type" : [ "string", "null" ],
"examples" : [ "My Opticks Sensor" ],
"default" : "Opticks JS Sensor"
},
"securityConfiguration" : {
"type" : [ "object", "null" ],
"default" : {
"blockAdultAcquisitionTraffic" : false,
"blockAutomatedSoftware" : true,
"blockOfferNotRendered" : true,
"blockAbuseIps" : false,
"blockMalwareIps" : true,
"blockVPNProxies" : false,
"blockHostingProxies" : true,
"blockUATampering" : true,
"blockBypassAttempts" : true,
"blockMSISDNInjection" : false,
"blockInvalidAppName" : true,
"blockBrowsersWithoutJavascript" : false,
"blockOldGenerationBrowsers" : false,
"blockInvalidRequests" : true,
"blockRegularIframeTraffic" : false,
"blockNonPlayStoreApk" : true
},
"anyOf" : [ {
"$ref" : "#/components/schemas/SecurityConfigurationAPIRequest"
}, {
"type" : "null"
} ]
},
"paused" : {
"type" : [ "boolean", "null" ]
}
}
},
"SensorJSAPIResponse" : {
"type" : "object",
"required" : [ "id", "name", "hash", "tag" ],
"properties" : {
"id" : {
"type" : "integer",
"format" : "int32"
},
"name" : {
"type" : "string"
},
"hash" : {
"type" : "string"
},
"tag" : {
"type" : "string"
},
"securityConfiguration" : {
"anyOf" : [ {
"$ref" : "#/components/schemas/SecurityConfigurationAPIResponse"
}, {
"type" : "null"
} ]
}
}
},
"Session forensic detection" : {
"type" : "object",
"required" : [ "threat", "descriptions" ],
"properties" : {
"threat" : {
"type" : "string"
},
"descriptions" : {
"type" : "array",
"uniqueItems" : true,
"items" : {
"type" : "string"
}
}
}
},
"Session forensic device" : {
"type" : "object",
"required" : [ "deviceName", "deviceType", "osName", "osVersion", "browserName", "browserVersion", "appPackage" ],
"properties" : {
"deviceName" : {
"type" : "string"
},
"deviceType" : {
"type" : "string"
},
"osName" : {
"type" : "string"
},
"osVersion" : {
"type" : "string"
},
"browserName" : {
"type" : "string"
},
"browserVersion" : {
"type" : "string"
},
"appPackage" : {
"type" : [ "string", "null" ]
}
}
},
"Session forensic event" : {
"type" : "object",
"required" : [ "type", "timestamp" ],
"properties" : {
"type" : {
"type" : "string"
},
"timestamp" : {
"type" : "integer",
"format" : "int64"
}
}
},
"Session forensic location" : {
"type" : "object",
"required" : [ "country", "ip", "isp", "connectionType" ],
"properties" : {
"country" : {
"type" : "string"
},
"ip" : {
"type" : "string"
},
"isp" : {
"type" : "string"
},
"connectionType" : {
"type" : "string"
}
}
},
"Session forensic visitor" : {
"type" : "object",
"required" : [ "params", "location", "device" ],
"properties" : {
"params" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"location" : {
"$ref" : "#/components/schemas/Session forensic location"
},
"device" : {
"$ref" : "#/components/schemas/Session forensic device"
}
}
},
"SessionForensicResponse" : {
"type" : "object",
"required" : [ "opticksId", "sessionId", "externalId", "sensor", "sensorName", "landingPage", "riskLevel", "analysis", "timeline", "visitor" ],
"properties" : {
"opticksId" : {
"type" : "string"
},
"sessionId" : {
"type" : "string"
},
"externalId" : {
"type" : [ "string", "null" ]
},
"sensor" : {
"type" : "string"
},
"sensorName" : {
"type" : "string"
},
"landingPage" : {
"type" : "string"
},
"riskLevel" : {
"type" : "string"
},
"analysis" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Session forensic detection"
}
},
"timeline" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Session forensic event"
}
},
"visitor" : {
"$ref" : "#/components/schemas/Session forensic visitor"
}
}
},
"StatsApiRequest" : {
"type" : "object",
"properties" : {
"metrics" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Metric"
},
"examples" : [ [ "sessions", "pageviews", "highRiskSessions", "BadBotPageviews" ] ]
},
"dimensions" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Dimension"
},
"examples" : [ [ "day", "country" ] ]
},
"filters" : {
"type" : "object",
"additionalProperties" : {
"type" : "array",
"items" : {
"type" : "string"
}
},
"description" : "A map where keys are Dimensions and values are a list of values to filter stats",
"examples" : [ {
"country" : [ "US", "UK", "DE" ],
"os" : [ "Android" ]
} ]
},
"order" : {
"$ref" : "#/components/schemas/Metric",
"type" : "string",
"examples" : [ "sessions" ]
},
"sort" : {
"type" : "string",
"examples" : [ "DESC" ],
"enum" : [ "ASC", "DESC" ]
},
"limit" : {
"type" : "integer",
"format" : "int32",
"examples" : [ 200000 ],
"default" : 200000
},
"page" : {
"type" : "integer",
"format" : "int32",
"examples" : [ 1 ],
"default" : 1
},
"startDate" : {
"type" : "string",
"description" : "Start date in format YYYY-MM-dd HH:mm:ss. Account timezone will be automatically applied",
"examples" : [ "2026-03-18 00:00:00" ]
},
"endDate" : {
"type" : "string",
"description" : "End date in format YYYY-MM-dd HH:mm:ss. Account timezone will be automatically applied",
"examples" : [ "2026-03-18 23:59:59" ]
}
},
"required" : [ "order", "page", "startDate", "endDate" ]
},
"StatsApiResponse" : {
"type" : "object",
"properties" : {
"dimensions" : {
"type" : "object",
"additionalProperties" : {
"type" : "string"
}
},
"metrics" : {
"type" : "object",
"additionalProperties" : {
"type" : "number",
"format" : "double"
}
}
}
}
},
"responses" : {
"BadRequestWithErrors" : {
"content" : { }
},
"InternalError" : { }
},
"securitySchemes" : {
"ApiAuth" : {
"type" : "apiKey",
"description" : "There is only one way to authenticate through Opticks API, and it is `Authorization` header. Requests that require authentication will return `401 Unauthorized` in case of invalid token.\n\nYou can create an API key in the Developers Settings in your Opticks dashboard.\n\nAuthorization: {api_key}",
"name" : "Authorization",
"in" : "header"
}
}
},
"info" : {
"contact" : {
"email" : "tech@optickssecurity.com",
"name" : "Engineering Team",
"url" : "https://www.optickssecurity.com"
},
"description" : "\n # Overview\n This website describes the resources that make up the official Opticks REST API. If you have any problems or requests please contact [support](mailto:tech@opticks.io).\n # Current Version\n The current version is **v1.0** and the base URL is `https://api.optickssecurity.com`.\n # Schema\n All API access is over **HTTPS**, and accessed from `https://api.optickssecurity.com`. All data is sent and received as JSON.\n",
"license" : {
"name" : "Apache 2.0",
"url" : "https://www.apache.org/licenses/LICENSE-2.0"
},
"title" : "Opticks API",
"version" : "v1.0"
},
"security" : [ {
"ApiAuth" : [ ]
} ],
"tags" : [ {
"name" : "Forensics"
}, {
"name" : "Leads"
}, {
"name" : "Sensors"
}, {
"name" : "Stats"
} ],
"paths" : {
"/public/v1/audience-exclusion-stats" : {
"post" : {
"summary" : "Get Audience Exclusion Stats",
"description" : "Get stats for audience exclusions generated by Opticks",
"operationId" : "get-audience-exclusion-stats",
"tags" : [ "Stats" ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExclusionStatsApiRequest"
}
}
},
"required" : true
},
"responses" : {
"400" : {
"description" : "Bad Request. See attached message for details."
},
"500" : {
"description" : "Failed to get Stats. Please contact support."
},
"200" : {
"description" : "Audience exclusion found",
"content" : {
"application/json" : {
"example" : [ {
"dimensions" : {
"day" : "2026-03-18"
},
"metrics" : {
"tiktokExclusionEvents" : 122,
"microsoftExclusionEvents" : 38,
"metaExclusionEvents" : 2942,
"googleAdsAudienceExclusionEvents" : 745
}
} ],
"schema" : {
"$ref" : "#/components/schemas/ExclusionStatsApiResponse"
}
}
}
}
}
}
},
"/public/v1/find" : {
"get" : {
"summary" : "Find Session",
"description" : "Find all details from a Session. You can also use a hit id or your custom external id (i.e. gclid)",
"operationId" : "find-session",
"tags" : [ "Forensics" ],
"parameters" : [ {
"name" : "externalId",
"in" : "query",
"schema" : {
"type" : [ "string", "null" ]
},
"required" : true
}, {
"name" : "hitId",
"in" : "query",
"schema" : {
"type" : [ "string", "null" ]
},
"required" : true
}, {
"name" : "sessionId",
"in" : "query",
"schema" : {
"type" : [ "string", "null" ]
},
"required" : true
} ],
"responses" : {
"400" : {
"description" : "Missing any id parameter"
},
"404" : {
"description" : "Session not found"
},
"200" : {
"description" : "Session found",
"content" : {
"application/json" : {
"example" : {
"opticksId" : "track_20260313000651_929c95e9_84b5_4b8a_bbcb_de8b04a17e2d",
"sessionId" : "84b54b8abbcbde8b69b3551b929c95e904a17e2d",
"sensor" : "d78b09660e61c733",
"sensorName" : "Opticks JS Sensor",
"landingPage" : "https://example.org",
"riskLevel" : "high",
"analysis" : [ {
"threat" : "NonCompliantTraffic",
"descriptions" : [ "IP flagged for Abuse", "Hosting/CDN proxy" ]
}, {
"threat" : "BadBot",
"descriptions" : [ "Automated Software" ]
}, {
"threat" : "DataTampering",
"descriptions" : [ "Bypass attempt" ]
} ],
"timeline" : [ {
"type" : "visit",
"timestamp" : 1773356811000
} ],
"visitor" : {
"params" : { },
"location" : {
"country" : "SG",
"ip" : "43.173.181.177",
"isp" : "Tencent cloud computing",
"connectionType" : "WiFi"
},
"device" : {
"deviceName" : "Unknown",
"deviceType" : "Desktop",
"osName" : "Windows",
"osVersion" : "10",
"browserName" : "Chrome",
"browserVersion" : "107.0.0.0"
}
}
},
"schema" : {
"$ref" : "#/components/schemas/SessionForensicResponse"
}
}
}
}
}
}
},
"/public/v1/google-savings-stats" : {
"post" : {
"summary" : "Get Google Savings Stats",
"description" : "Get Savings Stats about the economic impact of invalid traffic in your Google Ads account",
"operationId" : "get-google-savings-stats",
"tags" : [ "Stats" ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SavingsStatsApiRequest"
}
}
},
"required" : true
},
"responses" : {
"400" : {
"description" : "Bad Request. See attached message for details."
},
"500" : {
"description" : "Failed to get Google Savings Stats. Please contact support."
},
"200" : {
"description" : "Stats found",
"content" : {
"application/json" : {
"example" : [ {
"dimensions" : {
"googleCampaignName" : "Branding",
"googleCampaignType" : "SEARCH"
},
"metrics" : {
"googleIpExclusionSavings" : 38.22,
"googleClicks" : 611,
"searchDisplayExclusionEvents" : 12,
"googleIpExclusions" : 25
}
}, {
"dimensions" : {
"googleCampaignName" : "Corporate_Search",
"googleCampaignType" : "SEARCH"
},
"metrics" : {
"googleIpExclusionSavings" : 18.08,
"googleClicks" : 852,
"searchDisplayExclusionEvents" : 3,
"googleIpExclusions" : 12
}
}, {
"dimensions" : {
"googleCampaignName" : "Remarketing",
"googleCampaignType" : "DISPLAY"
},
"metrics" : {
"googleIpExclusionSavings" : 4.17,
"googleClicks" : 45,
"searchDisplayExclusionEvents" : 0,
"googleIpExclusions" : 6
}
} ],
"schema" : {
"$ref" : "#/components/schemas/SavingsStatsApiResponse"
}
}
}
}
}
}
},
"/public/v1/latest-conversions" : {
"get" : {
"summary" : "Latest Conversions",
"description" : "Get information about your latest conversions. You can bound by date and filter by sensor",
"operationId" : "latest-conversions",
"tags" : [ "Forensics" ],
"parameters" : [ {
"description" : "end timestamp",
"example" : 1774370797,
"name" : "endTime",
"in" : "query",
"schema" : {
"type" : [ "integer", "null" ],
"format" : "int64"
},
"required" : true
}, {
"description" : "Number of conversions, defaults to 1000",
"example" : 1000,
"name" : "limit",
"in" : "query",
"schema" : {
"maximum" : 1000,
"minimum" : 1,
"format" : "int32",
"type" : [ "integer", "null" ]
}
}, {
"description" : "Opticks Sensor id",
"example" : "33",
"name" : "sensorId",
"in" : "query",
"schema" : {
"type" : [ "string", "null" ]
},
"required" : true
}, {
"description" : "starting timestamp",
"example" : 1774197997,
"name" : "startTime",
"in" : "query",
"schema" : {
"type" : [ "integer", "null" ],
"format" : "int64"
},
"required" : true
} ],
"responses" : {
"500" : {
"description" : "Error searching conversions. Please contact support."
},
"400" : {
"description" : "Invalid limit. Use a number between 1 and 1000."
},
"200" : {
"description" : "Conversions found",
"content" : {
"application/json" : {
"example" : [ {
"opticksId" : "track_20260324095235_05f4c99e_986a_4bf5_86b3_f0381ed4038b",
"sessionId" : "986a4bf586b3f03869c25ee305f4c99e1ed4040b",
"externalId" : "customid1",
"transactionId" : "",
"conversionDate" : "2026-03-24 09:52:36",
"threats" : [ "Bad bot" ],
"riskLevel" : "high",
"sensorName" : "Sensor 1",
"vars" : {
"var2" : "desktop",
"var1" : "nb"
}
}, {
"opticksId" : "track_20260306121731_414c0210_99b5_43ce_bd21_32140cef8c45",
"sessionId" : "99b544cebd14321469aac5db414c02100cef8c87",
"externalId" : "customid2",
"transactionId" : "tx1",
"conversionDate" : "2026-03-06 12:17:51",
"threats" : [ "Statistical anomalies", "Non Compliant Traffic" ],
"riskLevel" : "high",
"sensorName" : "Sensor 1",
"vars" : { }
}, {
"opticksId" : "track_20260306121731_414c0210_99b5_44ce_bd14_32140cef8c45",
"sessionId" : "99b544cebd14321469aac5db414c02100cef8d74",
"transactionId" : "tx2",
"conversionDate" : "2026-03-06 12:18:00",
"threats" : [ ],
"riskLevel" : "low",
"sensorName" : "Sensor 2",
"vars" : {
"param1" : "value1"
}
} ],
"schema" : {
"$ref" : "#/components/schemas/ConversionResponse"
}
}
}
}
}
}
},
"/public/v1/lead" : {
"get" : {
"summary" : "Find Lead",
"description" : "Get information about a Lead",
"operationId" : "find-lead",
"tags" : [ "Leads" ],
"parameters" : [ {
"description" : "MD5 encoded or plain email",
"example" : "55502f40dc8b7c769880b10874abc9d0",
"required" : true,
"name" : "email",
"in" : "query",
"schema" : {
"type" : [ "string", "null" ]
}
} ],
"responses" : {
"404" : {
"description" : "Lead not found"
},
"400" : {
"description" : "Bad Request. Email was not provided."
},
"200" : {
"description" : "Lead found",
"content" : {
"application/json" : {
"example" : {
"id" : "330c547054b5c6407510e770",
"sessionId" : "0e5e4493849dfe55a0c7451112a11c0305b6a987",
"hitId" : "track_20260519143145_312a11c0_fe0d_3392_8732_dfe3305b5a33",
"formId" : "UnnamedForm1",
"email" : "te******ds@gm****.com",
"quality" : "Invalid",
"date" : "2026-05-19 14:32:00",
"page" : "/crm-sales",
"fullUrl" : "https://example.com/crm-sales",
"analysis" : {
"ipRisks" : [ ],
"detections" : {
"DataTampering" : [ "Bypass attempt" ],
"NonCompliantTraffic" : [ "Hosting/CDN proxy" ]
}
},
"device" : {
"model" : "iPhone",
"os" : "iOS",
"browser" : "Firefox",
"app" : null,
"languages" : "es-ES;es;en-US;en"
},
"location" : {
"country" : "NL",
"lat" : 52.38240051269531,
"lon" : 4.899499893188477,
"ip" : "62.212.87.223",
"isp" : "LeaseWeb Netherlands B.V.",
"timezone" : "America/Los_Angeles",
"timezoneMatch" : false
},
"params" : {
"utm_source" : "example_source",
"utm_campaign" : "example_campaign"
}
},
"schema" : {
"$ref" : "#/components/schemas/LeadApiResponse"
}
}
}
}
}
}
},
"/public/v1/leads" : {
"get" : {
"summary" : "List Leads",
"description" : "List your Leads",
"operationId" : "list-leads",
"tags" : [ "Leads" ],
"parameters" : [ {
"description" : "end timestamp",
"example" : 1774370797,
"name" : "endTime",
"in" : "query",
"schema" : {
"type" : [ "integer", "null" ],
"format" : "int64"
},
"required" : true
}, {
"description" : "optional form id to filter",
"example" : "form-id-1",
"name" : "formId",
"in" : "query",
"schema" : {
"type" : [ "string", "null" ]
},
"required" : true
}, {
"description" : "Number of leads, defaults to 1000",
"example" : 1000,
"name" : "limit",
"in" : "query",
"schema" : {
"maximum" : 1000,
"minimum" : 1,
"format" : "int32",
"type" : [ "integer", "null" ]
},
"required" : true
}, {
"description" : "Page number, offsets the limit and defaults to one",
"example" : 1,
"name" : "page",
"in" : "query",
"schema" : {
"maximum" : 1000,
"minimum" : 1,
"format" : "int32",
"type" : [ "integer", "null" ]
},
"required" : true
}, {
"description" : "starting timestamp",
"example" : 1774197997,
"name" : "startTime",
"in" : "query",
"schema" : {
"type" : [ "integer", "null" ],
"format" : "int64"
},
"required" : true
} ],
"responses" : {
"500" : {
"description" : "Failed to get Leads. Please contact support."
},
"200" : {
"description" : "Lead found",
"content" : {
"application/json" : {
"example" : [ {
"id" : "330c547054b5c6407510e770",
"sessionId" : "0e5e4493849dfe55a0c7451112a11c0305b6a987",
"hitId" : "track_20260519143145_312a11c0_fe0d_3392_8732_dfe3305b5a33",
"formId" : "UnnamedForm1",
"email" : "te******ds@gm****.com",
"quality" : "Invalid",
"date" : "2026-05-19 14:32:00",
"page" : "/crm-sales",
"fullUrl" : "https://example.com/crm-sales",
"analysis" : {
"ipRisks" : [ ],
"detections" : {
"BadBot" : [ "Automated Software" ],
"NonCompliantTraffic" : [ "VPN proxy" ]
}
},
"device" : {
"model" : "iPhone",
"os" : "iOS",
"browser" : "Firefox",
"app" : null,
"languages" : "es-ES;es;en-US;en"
},
"location" : {
"country" : "NL",
"lat" : 52.38240051269531,
"lon" : 4.899499893188477,
"ip" : "62.212.87.223",
"isp" : "LeaseWeb Netherlands B.V.",
"timezone" : "America/Los_Angeles",
"timezoneMatch" : false
},
"params" : {
"utm_source" : "example_source",
"utm_campaign" : "example_campaign"
}
}, {
"id" : "5b0d79a254b5c6407510e332",
"sessionId" : "4e152b4f8f438d336a0d8092410b7aa5cc5f0bdd",
"hitId" : "track_20260520093621_330a7dc5_6a51_3a4d_ff47_8d92ee5f0bda",
"formId" : "UnnamedForm2",
"email" : "ju********de@yah**.es",
"quality" : "Valid",
"date" : "2026-05-20 09:36:34",
"page" : "/b2b-offer",
"fullUrl" : "https://example.com/b2b-offer",
"analysis" : {
"ipRisks" : [ ],
"detections" : {
"NonCompliantTraffic" : [ "IP flagged for Abuse" ]
}
},
"device" : {
"model" : "Samsung Galaxy 23",
"os" : "Android",
"browser" : "Chrome Mobile",
"app" : null,
"languages" : "en-US;en"
},
"location" : {
"country" : "US",
"lat" : 36.55214095511966,
"lon" : -121.9195156615916,
"ip" : "132.197.12.123",
"isp" : "Verizon",
"timezone" : "America/Los_Angeles",
"timezoneMatch" : true
},
"params" : {
"utm_source" : "example_source",
"utm_campaign" : "example_campaign"
}
} ],
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/LeadApiResponse"
}
}
}
}
}
}
}
},
"/public/v1/sensors" : {
"get" : {
"summary" : "List Sensors",
"description" : "List your Opticks JS Sensors",
"operationId" : "list-sensors",
"tags" : [ "Sensors" ],
"responses" : {
"200" : {
"description" : "Opticks JS sensor list",
"content" : {
"application/json" : {
"example" : [ {
"id" : 33,
"name" : "Opticks JS Sensor",
"hash" : "1281cba01bf681726",
"tag" : "",
"securityConfiguration" : {
"blockAdultAcquisitionTraffic" : false,
"blockAutomatedSoftware" : true,
"blockOfferNotRendered" : true,
"blockAbuseIps" : false,
"blockMalwareIps" : true,
"blockVPNProxies" : false,
"blockHostingProxies" : true,
"blockUATampering" : true,
"blockBypassAttempts" : true,
"blockMSISDNInjection" : false,
"blockInvalidAppName" : true,
"blockBrowsersWithoutJavascript" : false,
"blockOldGenerationBrowsers" : false,
"blockInvalidRequests" : true,
"blockRegularIframeTraffic" : false,
"blockNonPlayStoreApk" : true
}
}, {
"id" : 34,
"name" : "Opticks Second JS Sensor",
"tag" : "",
"securityConfiguration" : {
"blockAdultAcquisitionTraffic" : false,
"blockAutomatedSoftware" : true,
"blockOfferNotRendered" : true,
"blockAbuseIps" : false,
"blockMalwareIps" : true,
"blockVPNProxies" : false,
"blockHostingProxies" : true,
"blockUATampering" : true,
"blockBypassAttempts" : true,
"blockMSISDNInjection" : false,
"blockInvalidAppName" : true,
"blockBrowsersWithoutJavascript" : false,
"blockOldGenerationBrowsers" : false,
"blockInvalidRequests" : true,
"blockRegularIframeTraffic" : false,
"blockNonPlayStoreApk" : true
}
} ],
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/SensorJSAPIResponse"
}
}
}
}
}
}
},
"post" : {
"summary" : "Create Sensor",
"description" : "Create a new Opticks JS Sensor",
"operationId" : "create-sensor",
"tags" : [ "Sensors" ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SensorJSAPIRequest"
}
}
},
"required" : true
},
"responses" : {
"429" : {
"description" : "Reached maximum number of sensors. Please contact support@optickssecurity.com"
},
"200" : {
"description" : "Sensor created",
"content" : {
"application/json" : {
"example" : {
"id" : 33,
"name" : "Opticks JS Sensor",
"hash" : "1281cba01bf681726",
"tag" : "",
"securityConfiguration" : {
"blockAdultAcquisitionTraffic" : false,
"blockAutomatedSoftware" : true,
"blockOfferNotRendered" : true,
"blockAbuseIps" : false,
"blockMalwareIps" : true,
"blockVPNProxies" : false,
"blockHostingProxies" : true,
"blockUATampering" : true,
"blockBypassAttempts" : true,
"blockMSISDNInjection" : false,
"blockInvalidAppName" : true,
"blockBrowsersWithoutJavascript" : false,
"blockOldGenerationBrowsers" : false,
"blockInvalidRequests" : true,
"blockRegularIframeTraffic" : false,
"blockNonPlayStoreApk" : true
}
},
"schema" : {
"$ref" : "#/components/schemas/SensorJSAPIResponse"
}
}
}
},
"400" : {
"description" : "Bad Request"
}
}
}
},
"/public/v1/sensors/{id}" : {
"patch" : {
"summary" : "Edit Sensor",
"description" : "Modify an Opticks JS Sensor",
"operationId" : "edit-sensor",
"tags" : [ "Sensors" ],
"parameters" : [ {
"name" : "id",
"in" : "path",
"required" : true,
"schema" : {
"type" : "integer",
"format" : "int32"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/SensorJSAPIRequest"
}
}
},
"required" : true
},
"responses" : {
"404" : {
"description" : "Opticks JS sensor not found"
},
"200" : {
"description" : "Opticks JS sensor",
"content" : {
"application/json" : {
"example" : {
"id" : 33,
"name" : "Opticks JS Sensor",
"hash" : "1281cba01bf681726",
"tag" : "",
"securityConfiguration" : {
"blockAdultAcquisitionTraffic" : false,
"blockAutomatedSoftware" : true,
"blockOfferNotRendered" : true,
"blockAbuseIps" : false,
"blockMalwareIps" : true,
"blockVPNProxies" : false,
"blockHostingProxies" : true,
"blockUATampering" : true,
"blockBypassAttempts" : true,
"blockMSISDNInjection" : false,
"blockInvalidAppName" : true,
"blockBrowsersWithoutJavascript" : false,
"blockOldGenerationBrowsers" : false,
"blockInvalidRequests" : true,
"blockRegularIframeTraffic" : false,
"blockNonPlayStoreApk" : true
}
},
"schema" : {
"$ref" : "#/components/schemas/SensorJSAPIResponse"
}
}
}
}
}
}
},
"/public/v1/stats" : {
"post" : {
"summary" : "Get Stats",
"description" : "Get general Stats regarding Sessions, PageViews, Conversions and invalid traffic metrics",
"operationId" : "get-stats",
"tags" : [ "Stats" ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/StatsApiRequest"
}
}
},
"required" : true
},
"responses" : {
"400" : {
"description" : "Bad Request. See attached message for details."
},
"500" : {
"description" : "Failed to get Stats. Please contact support."
},
"200" : {
"description" : "Stats found",
"content" : {
"application/json" : {
"example" : [ {
"dimensions" : {
"country" : "US",
"day" : "2026-03-18"
},
"metrics" : {
"sessions" : 94,
"pageviews" : 177,
"BadBotPageviews" : 42,
"highRiskSessions" : 35
}
}, {
"dimensions" : {
"country" : "DE",
"day" : "2026-03-18"
},
"metrics" : {
"sessions" : 76,
"pageviews" : 155,
"BadBotPageviews" : 54,
"highRiskSessions" : 33
}
} ],
"schema" : {
"$ref" : "#/components/schemas/StatsApiResponse"
}
}
}
}
}
}
},
"/public/v1/stats/export" : {
"post" : {
"summary" : "Export Stats (CSV)",
"operationId" : "get-stats-export",
"tags" : [ "Stats" ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/StatsApiRequest"
}
}
},
"required" : true
},
"responses" : {
"400" : {
"description" : "Bad Request. See attached message for details."
},
"500" : {
"description" : "Failed to get Stats. Please contact support."
},
"200" : {
"description" : "Stats found",
"content" : {
"text/csv" : {
"example" : "month,day,country,highRiskSessions,sessions,pageviews,BadBotPageviews\n2026-03,2026-03-18,US,35.0,94.0,177.0,42.0\n2026-03,2026-03-18,DE,0.0,6.0,15.0,0.0\n",
"schema" : {
"format" : "binary",
"type" : "string"
}
}
}
}
}
}
}
},
"servers" : [ {
"url" : "https://api.optickssecurity.com"
} ]
}