IOC lookup

Query one indicator per request. A successful response contains meta and indicator. To process a list, send individual requests with bounded concurrency.

IOC type	Standard route	Input
File	GET /v1/ioc/files/{ioc_key}	MD5, SHA-1 or SHA-256 hash
Domain	GET /v1/ioc/domains/{ioc_key}	Domain name, without a URL scheme or path
IP	GET /v1/ioc/ips/{ioc_key}	IP address
URL	GET /v1/ioc/urls?q={encoded_url}	Complete URL encoded as a query parameter

Parameter	Suggested usage	Meaning
view	Optional	Omit for the service default. compact requests reduced detail; full requests more context; full+relations also requests related objects and may use more credits. URL-encode the plus sign.
limit	Start with 10; recommended 1–50	Requested page size per relationship, not a combined total across all relationship types. Use the returned cursor to retrieve more items. A larger limit may use more credits under your access plan.

Choose a response view

Most examples omit view and follow the service default. Use view=compact to request reduced detail where supported, for example when reviewing related indicators. The exact fields and size depend on the indicator type and your access. Request full or full+relations only when you need additional context.

cURL · compact domain lookup

curl --get "https://api.virussign.com/v1/ioc/domains/example.com" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "view=compact"

To include relationships in an individual lookup, request them explicitly and start with a small limit:

cURL · file with relationships

curl --get "https://api.virussign.com/v1/ioc/files/YOUR_SHA256" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "view=full+relations" \
  --data-urlencode "limit=10"

Query a complete URL

Encode the complete URL with your HTTP client. Place q last in the query string, as shown below, and preserve the original URL’s case, path and query parameters.

cURL · URL lookup

curl --get "https://api.virussign.com/v1/ioc/urls" \
  --header "x-api-key: $VIRUSSIGN_API_KEY" \
  --data-urlencode "q=https://example.com/path?a=1&b=2"

Python · URL lookup

response = requests.get(
    "https://api.virussign.com/v1/ioc/urls",
    headers={"x-api-key": os.environ["VIRUSSIGN_API_KEY"]},
    params={"q": "https://example.com/path?a=1&b=2"},
    timeout=(5, 30),
)
response.raise_for_status()

For subsequent URL relationship requests, use the opaque URL identifier in indicator.value (or the returned canonical link when available). Do not assume a URL identifier is a file hash or reconstruct it from a different normalization algorithm.

Response conventions

Each successful IOC lookup contains meta and indicator. The references describe public field names, types and meanings. Fields depend on the indicator, access tier and requested view; a full view does not guarantee that every listed field is populated.

Basic provides core indicator intelligence. Pro adds available behavioral, technical and investigation context. Basic Plus has the same permissions as Basic; Pro Plus has the same permissions as Pro. Plus increases monthly credits.

Treat optional fields as potentially absent or null, and tolerate empty collections and additional fields. Missing data is not a safe verdict. Check the type of each signal: Basic analysis.detections is a percentage from 0 to 100 (88 means 88%); Pro uses a detected/total ratio string such as "28/32".

Numeric confidence and risk scores use a 0–100 scale; they are not probabilities. Qualitative confidence levels are text labels. Field references state the applicable unit or range.

Times generally use ISO 8601 with a timezone. Exceptions, such as file signing certificate times in Unix seconds, are stated in the relevant field reference. Observation times describe the record’s coverage; they are not a claim about the exact start or end of an attack.

Choose an IOC reference below for its nested fields and illustrative response.

Fields are conditional unless stated otherwise. Types below describe populated values; optional values may also be null. Access labels describe capability, not guaranteed data for every indicator.

Response metadata

meta

Fields in meta
Field	Type	Meaning
`request_id`	string	Request identifier. Include it when contacting support.
`timestamp`	string	Response time in UTC. ISO 8601 timestamp with timezone.
`quota_remaining`	integer	Remaining credits or cycle query quota when reported.
`took_ms`	integer	Processing duration in milliseconds, when provided.

Shared indicator fields

indicator

Fields in indicator
Field	Type	Meaning
`type`	string	Object type.
`value`	string	Canonical indicator value. File records normally use SHA-256; URL records use an opaque identifier.
`analysis`	object	Threat assessment. Field reference →
`first_seen`	string	First observation time. ISO 8601 timestamp with timezone.
`last_seen`	string	Latest observation time. ISO 8601 timestamp with timezone.
`tags`	array<string>	Descriptive indicator labels.
`crowd_context`	object · Pro	Community and actor context, where available. Field reference →
`relations`	object	Related object groups when requested with full+relations and authorized. See Relationships. Field reference →

indicator.contextobject

Context for an object returned through a relationship.

Fields in indicator.context
Field	Type	Meaning
`relationship`	string	Relationship connecting this object to the source indicator.

indicator.linksobject

Optional navigation links.

Fields in indicator.links
Field	Type	Meaning
`self`	string	Canonical resource link, when provided.

Threat assessment

indicator.analysis

Fields in indicator.analysis
Field	Type	Meaning
`status`	string · Basic	Assessment state: assessed, triaged or unassessed.
`malicious`	boolean	Malicious classification. A false value alone does not establish safety.
`detections`	number / string	Basic: detection percentage, 0–100 (88 means 88%). Pro: detected/total ratio string, such as "28/32".
`crowd_rate`	number · Basic	Community detection signal as a percentage, 0–100.
`confidence`	number	Assessment confidence score when available; higher values indicate stronger confidence. Scale: 0–100; not a probability.
`severity`	string	Severity label when an assessment is available.
`family`	string	Associated malware family.
`family_tags`	array<string> · Basic	Additional family labels.
`type`	string · Pro	Threat category associated with the assessment.
`has_actor`	boolean · Pro	Whether actor context is available.

Community & actor context

indicator.crowd_context

Fields in indicator.crowd_context
Field	Type	Meaning
`tags`	array<string>	Context labels.
`family_tags`	array<string>	Associated family labels.
`misc_tags`	array<string>	Additional context labels, separate from the main assessment and family labels.

indicator.crowd_context.actors[]array<object>

Actor associations with their supporting confidence and family context.

Fields in indicator.crowd_context.actors[]
Field	Type	Meaning
`actor`	string	Associated actor name.
`confidence`	number	Actor-association confidence score; higher values indicate stronger confidence. Scale: 0–100; not a probability.
`confidence_level`	string	Qualitative confidence label, not a numeric percentage.
`crowd_hits`	integer	Supporting matches represented in this context.
`supported_families`	array<string>	Families supporting the association.

Appearance

IOC lookup & assessments

Search results