Skip to content
POST/api/v2/ioc/verdict

IOC Verdict

Query threat intelligence for a single indicator of compromise (IOC). Returns risk score, signals, and evidence. **Requires API key with `verdict` permission.**

EnrichmentView OpenAPI spec ↗

Request body

  • indicatorobjectrequired
    • typeenumipdomainip_blockfile_hash_sha256asn
      Indicator type
    • valuestringrequired
      Indicator value
    • action_takenenumblockallow
      Optional, log-only. The action the caller's own control already took for this indicator. Does not affect the verdict or the cache key; recorded only for coverage analysis. Empty means not provided.
    • action_sourcestring
      Optional, log-only. Free text name of the control that produced action_taken (no fixed list). Trimmed and lowercased before it is logged ('Firewall' / 'firewall ' -> 'firewall'); the normalized value must be at most 64 characters, otherwise 400 INVALID_ACTION_SOURCE. Does not affect the verdict or the cache key. Empty means not provided.
  • contextobject
    • flagsany
      Optional context flags
  • sourceobject
    Caller identification for audit logging
    • channelstring
      Source channel (e.g. portal, api, siem, soar)
    • productstring
      Product name
    • integration_idstring
      Integration identifier (e.g. SIEM rule ID)
    • event_typestring
      Event type triggering the enrichment
    • severity_hintstring
      Caller-suggested severity level
  • signal_detailsenumnonetopall
    Level of signal detail in response
  • evidence_detailsenumnonesummaryfull
    Level of evidence detail in response. When `none`, the `evidence` field is omitted from each signal object entirely.

Example

json
{
  "indicator": {
    "type": "domain",
    "value": "example.com"
  }
}

Responses

IOC Verdict result

  • indicatorobject
    • typeenumipdomainip_blockfile_hash_sha256asn
    • valuestring
    • normalizedstring
      Normalized form of the indicator value
  • riskobject
    • scoreinteger
      Risk score (0 = no risk, 100 = critical). 50 = neutral threshold.
    • strengthenumweakmediumstrongvery_strong
    • categorystring
      Risk category signal
    • evidence_saturationenumnonesparselimitedmoderatestrongfull
      How much of the expected evidence was observed for this IOC, as a keyword band (none < sparse < limited < moderate < strong < full; `none` = no evidence / undefined). Higher = more complete evidence, so the score is more reliable. Omitted on documents written before the field shipped. Replaces the former `risk.direction` field.
  • signalsThreatSignal[]
    • signal_idstring
    • directionenumsafemalicious
    • signal_subgroupstring
    • signal_groupstring
    • signal_namestring
    • evidenceobject
  • signal_countinteger
    Total number of signals returned
  • scoresobject
    Breakdown of risk scores by signal_group and signal_subgroup
    • signal_groupsobject
    • signal_subgroupsobject
  • threat_contextobject
    • flagsstring[]
  • recommended_actionsobject[]
    • actionstring
    • orderinteger
  • metaobject
    • engine_versionstring
    • data_timestampstring
    • cache_hitboolean
    • query_time_msinteger
    • request_idstring
    • warningsstring[]
    • errorsstring[]
    • detail_levelsobject

Code samples

bash
curl -X POST 'https://api.verdictiq.io/api/v2/ioc/verdict' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_<your-api-key>' \
  -d '{
  "indicator": {
    "type": "domain",
    "value": "example.com"
  }
}'