Reference

Create a new collection

post
https://www.virustotal.com/api/v3/collections

Use this endpoint to create new threat object such as Threat Actor, Campaign, Malware Family, Software or Toolkit and IoC Collection.

❗️

This endpoint currently supports IoC Collections only. All other object types are in Private Preview.

🚧

Note that Country and Industry Profiles cannot be created by users.

Include the data object in the request body. By default, all threat objects are created as private and are accessible only to the owner, with one exception. By default, IoC Collections created by standard users are public. To make an IoC Collection private, set the private attribute to true.

The following request body templates include all available attributes. Before using them, please remove any mutually exclusive fields.

{
  "data": {
    "type": "collection",
    "attributes": {
      "collection_type": "threat-actor",
      "name": "The name of your threat actor",
      "description": "The description of your threat actor",
      "link": "http://test.com",
      "alt_names": [
        "alternative_name_1",
        "alternative_name_2"
      ],
      "tlp": "GREEN",
      "tags": [
        "tag_a",
        "tag_b"
      ],
      "capabilities": [
        {
          "value": "capability_a",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "detection_names": [
        {
          "value": "detection_name_a",
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "operating_systems": [
        {
          "value": "your os",
          "confidence": "possible",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "malware_roles": [
        {
          "value": "Sniffer",
          "confidence": "suspected",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "motivations": [
        {
          "value": "Hacktivism",
          "confidence": "blocklisted",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "sponsor_region": "ES",
      "source_region": "UK",
      "source_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "country": "US",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "targeted_regions": [
        "JP",
        "DE"
      ],
      "targeted_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "JP"
        },
        {
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "FR"
        }
      ],
      "targeted_industries": [
        "Agriculture",
        "Mining"
      ],
      "targeted_industries_tree": [
        {
          "industry_group": "Agriculture",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        },
        {
          "industry_group": "Mining",
          "confidence": "confirmed"
        }
      ],
      "first_seen_details": [
        {
          "value": "946684800",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ],
      "last_seen_details": [
        {
          "value": "1262304000",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ]
    },
    "relationships": {
      "associations": {
        "data": [
          {
            "type": "collection",
            "id": "threat-actor--9e6b1b9c-bc43-5c7b-a70e-23cbfe4b5bcf"
          },
          {
            "type": "collection",
            "id": "malware--5bd89727-4a3f-541f-9f64-044b87eb66e5"
          },
          {
            "type": "collection",
            "id": "malware--f872b3e0-c277-5716-baae-885a9c410398"
          },
          {
            "type": "collection",
            "id": "campaign--a84b13cd-886c-5597-816d-dd813b71417b"
          },
          {
            "type": "collection",
            "id": "fbb2387395df252e007ae0856ed4dc2ca6d5de734be2bc55707f93b13393756e"
          },
          {
            "type": "collection",
            "id": "vulnerability--mve-2026-9380"
          }
        ]
      },
      "files": {
        "data": [
          {
            "type": "file",
            "id": "d3efbfd26f392c1a87c95d26a79ff92911b1b58c84c72215e0c28929b07e2ae4"
          }
        ]
      },
      "domains": {
        "data": [
          {
            "type": "domain",
            "id": "google.com"
          }
        ]
      },
      "ip_addresses": {
        "data": [
          {
            "type": "ip_address",
            "id": "173.194.199.113"
          }
        ]
      },
      "urls": {
        "data": [
          {
            "type": "url",
            "url": "https://www.realhostx.com/Cloud/Socket/Adb.zip"
          },
          {
            "type": "url",
            "id": "d685d65bf7b7c5d736017d3f85e2617f326ac6651e4cb1ac594b66eeff6e9b8b"
          }
        ]
      },
      "reports": {
        "data": [
          {
            "type": "collection",
            "id": "report--26-10013924"
          }
        ]
      },
      "attack_techniques": {
        "data": [
          {
            "type": "attack_technique", 
            "id": "T1087"
          }
        ]
      }
    }
  }
}
{
  "data": {
    "type": "collection",
    "attributes": {
      "collection_type": "campaign",
      "name": "The name of your campaign",
      "description": "The description of your campaign",
      "link": "http://test.com",
      "alt_names": [
        "alternative_name_1",
        "alternative_name_2"
      ],
      "tlp": "GREEN",
      "tags": [
        "tag_a",
        "tag_b"
      ],
      "capabilities": [
        {
          "value": "capability_a",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "detection_names": [
        {
          "value": "detection_name_a",
          "confidence": "unconfirmed",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "operating_systems": [
        {
          "value": "your os",
          "confidence": "possible",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "malware_roles": [
        {
          "value": "Sniffer",
          "confidence": "suspected",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "motivations": [
        {
          "value": "Hacktivism",
          "confidence": "blocklisted",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "sponsor_region": "ES",
      "source_region": "UK",
      "source_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "country": "US",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "targeted_regions": [
        "JP",
        "DE"
      ],
      "targeted_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "JP"
        },
        {
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "FR"
        }
      ],
      "targeted_industries": [
        "Agriculture",
        "Mining"
      ],
      "targeted_industries_tree": [
        {
          "industry_group": "Agriculture",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        },
        {
          "industry_group": "Mining",
          "confidence": "confirmed"
        }
      ],
      "first_seen_details": [
        {
          "value": "946684800",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ],
      "last_seen_details": [
        {
          "value": "1262304000",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ]
    },
    "relationships": {
      "associations": {
        "data": [
          {
            "type": "collection",
            "id": "threat-actor--9e6b1b9c-bc43-5c7b-a70e-23cbfe4b5bcf"
          },
          {
            "type": "collection",
            "id": "malware--5bd89727-4a3f-541f-9f64-044b87eb66e5"
          },
          {
            "type": "collection",
            "id": "malware--f872b3e0-c277-5716-baae-885a9c410398"
          },
          {
            "type": "collection",
            "id": "campaign--a84b13cd-886c-5597-816d-dd813b71417b"
          },
          {
            "type": "collection",
            "id": "fbb2387395df252e007ae0856ed4dc2ca6d5de734be2bc55707f93b13393756e"
          },
          {
            "type": "collection",
            "id": "vulnerability--mve-2026-9380"
          }
        ]
      },
      "files": {
        "data": [
          {
            "type": "file",
            "id": "d3efbfd26f392c1a87c95d26a79ff92911b1b58c84c72215e0c28929b07e2ae4"
          }
        ]
      },
      "domains": {
        "data": [
          {
            "type": "domain",
            "id": "google.com"
          }
        ]
      },
      "ip_addresses": {
        "data": [
          {
            "type": "ip_address",
            "id": "173.194.199.113"
          }
        ]
      },
      "urls": {
        "data": [
          {
            "type": "url",
            "url": "https://www.realhostx.com/Cloud/Socket/Adb.zip"
          },
          {
            "type": "url",
            "id": "d685d65bf7b7c5d736017d3f85e2617f326ac6651e4cb1ac594b66eeff6e9b8b"
          }
        ]
      },
      "reports": {
        "data": [
          {
            "type": "collection",
            "id": "report--26-10013924"
          }
        ]
      },
      "attack_techniques": {
        "data": [
          {
            "type": "attack_technique", 
            "id": "T1087"
          }
        ]
      }
    }
  }
}
{
  "data": {
    "type": "collection",
    "attributes": {
      "collection_type": "malware-family",
      "name": "The name of your malware family",
      "description": "The description of your malware-family",
      "link": "http://test.com",
      "alt_names": [
        "alternative_name_1",
        "alternative_name_2"
      ],
      "tlp": "GREEN",
      "tags": [
        "tag_a",
        "tag_b"
      ],
      "capabilities": [
        {
          "value": "capability_a",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "detection_names": [
        {
          "value": "detection_name_a",
          "confidence": "unconfirmed",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "operating_systems": [
        {
          "value": "your os",
          "confidence": "possible",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "malware_roles": [
        {
          "value": "Sniffer",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "motivations": [
        {
          "value": "Hacktivism",
          "confidence": "blocklisted",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "sponsor_region": "ES",
      "source_region": "UK",
      "source_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "country": "US",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "targeted_regions": [
        "JP",
        "DE"
      ],
      "targeted_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "JP"
        },
        {
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "FR"
        }
      ],
      "targeted_industries": [
        "Agriculture",
        "Mining"
      ],
      "targeted_industries_tree": [
        {
          "industry_group": "Agriculture",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        },
        {
          "industry_group": "Mining",
          "confidence": "confirmed"
        }
      ],
      "first_seen_details": [
        {
          "value": "946684800",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ],
      "last_seen_details": [
        {
          "value": "1262304000",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ]
    },
    "relationships": {
      "associations": {
        "data": [
          {
            "type": "collection",
            "id": "threat-actor--9e6b1b9c-bc43-5c7b-a70e-23cbfe4b5bcf"
          },
          {
            "type": "collection",
            "id": "malware--5bd89727-4a3f-541f-9f64-044b87eb66e5"
          },
          {
            "type": "collection",
            "id": "malware--f872b3e0-c277-5716-baae-885a9c410398"
          },
          {
            "type": "collection",
            "id": "campaign--a84b13cd-886c-5597-816d-dd813b71417b"
          },
          {
            "type": "collection",
            "id": "fbb2387395df252e007ae0856ed4dc2ca6d5de734be2bc55707f93b13393756e"
          },
          {
            "type": "collection",
            "id": "vulnerability--mve-2026-9380"
          }
        ]
      },
      "files": {
        "data": [
          {
            "type": "file",
            "id": "d3efbfd26f392c1a87c95d26a79ff92911b1b58c84c72215e0c28929b07e2ae4"
          }
        ]
      },
      "domains": {
        "data": [
          {
            "type": "domain",
            "id": "google.com"
          }
        ]
      },
      "ip_addresses": {
        "data": [
          {
            "type": "ip_address",
            "id": "173.194.199.113"
          }
        ]
      },
      "urls": {
        "data": [
          {
            "type": "url",
            "url": "https://www.realhostx.com/Cloud/Socket/Adb.zip"
          },
          {
            "type": "url",
            "id": "d685d65bf7b7c5d736017d3f85e2617f326ac6651e4cb1ac594b66eeff6e9b8b"
          }
        ]
      },
      "reports": {
        "data": [
          {
            "type": "collection",
            "id": "report--26-10013924"
          }
        ]
      },
      "attack_techniques": {
        "data": [
          {
            "type": "attack_technique", 
            "id": "T1087"
          }
        ]
      }
    }
  }
}
{
  "data": {
    "type": "collection",
    "attributes": {
      "collection_type": "software-toolkit",
      "name": "The name of your software/toolkit",
      "description": "The description of your software/toolkit",
      "link": "http://test.com",
      "alt_names": [
        "alternative_name_1",
        "alternative_name_2"
      ],
      "tlp": "GREEN",
      "tags": [
        "tag_a",
        "tag_b"
      ],
      "capabilities": [
        {
          "value": "capability_a",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "detection_names": [
        {
          "value": "detection_name_a",
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "operating_systems": [
        {
          "value": "your os",
          "confidence": "possible",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "malware_roles": [
        {
          "value": "Sniffer",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "motivations": [
        {
          "value": "Hacktivism",
          "confidence": "blocklisted",
					"first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "sponsor_region": "ES",
      "source_region": "UK",
      "source_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "country": "US",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "targeted_regions": [
        "JP",
        "DE"
      ],
      "targeted_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "JP"
        },
        {
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "FR"
        }
      ],
      "targeted_industries": [
        "Agriculture",
        "Mining"
      ],
      "targeted_industries_tree": [
        {
          "industry_group": "Agriculture",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        },
        {
          "industry_group": "Mining",
          "confidence": "confirmed"
        }
      ],
      "first_seen_details": [
        {
          "value": "946684800",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ],
      "last_seen_details": [
        {
          "value": "1262304000",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ]
    },
    "relationships": {
      "associations": {
        "data": [
          {
            "type": "collection",
            "id": "threat-actor--9e6b1b9c-bc43-5c7b-a70e-23cbfe4b5bcf"
          },
          {
            "type": "collection",
            "id": "malware--5bd89727-4a3f-541f-9f64-044b87eb66e5"
          },
          {
            "type": "collection",
            "id": "malware--f872b3e0-c277-5716-baae-885a9c410398"
          },
          {
            "type": "collection",
            "id": "campaign--a84b13cd-886c-5597-816d-dd813b71417b"
          },
          {
            "type": "collection",
            "id": "fbb2387395df252e007ae0856ed4dc2ca6d5de734be2bc55707f93b13393756e"
          },
          {
            "type": "collection",
            "id": "vulnerability--mve-2026-9380"
          }
        ]
      },
      "files": {
        "data": [
          {
            "type": "file",
            "id": "d3efbfd26f392c1a87c95d26a79ff92911b1b58c84c72215e0c28929b07e2ae4"
          }
        ]
      },
      "domains": {
        "data": [
          {
            "type": "domain",
            "id": "google.com"
          }
        ]
      },
      "ip_addresses": {
        "data": [
          {
            "type": "ip_address",
            "id": "173.194.199.113"
          }
        ]
      },
      "urls": {
        "data": [
          {
            "type": "url",
            "url": "https://www.realhostx.com/Cloud/Socket/Adb.zip"
          },
          {
            "type": "url",
            "id": "d685d65bf7b7c5d736017d3f85e2617f326ac6651e4cb1ac594b66eeff6e9b8b"
          }
        ]
      },
      "reports": {
        "data": [
          {
            "type": "collection",
            "id": "report--26-10013924"
          }
        ]
      },
      "attack_techniques": {
        "data": [
          {
            "type": "attack_technique", 
            "id": "T1087"
          }
        ]
      }
    }
  }
}
{
  "data": {
    "type": "collection",
    "attributes": {
      "collection_type": "collection",
      "name": "The name of your collection",
      "description": "The description of your collection",
      "private": false,
      "link": "http://test.com",
      "alt_names": [
        "alternative_name_1",
        "alternative_name_2"
      ],
      "tlp": "GREEN",
      "tags": [
        "tag_a",
        "tag_b"
      ],
      "capabilities": [
        {
          "value": "capability_a",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "detection_names": [
        {
          "value": "detection_name_a",
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "operating_systems": [
        {
          "value": "your os",
          "confidence": "possible",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "malware_roles": [
        {
          "value": "Sniffer",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "motivations": [
        {
          "value": "Hacktivism",
          "confidence": "blocklisted",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "sponsor_region": "ES",
      "source_region": "UK",
      "source_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "country": "US",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "targeted_regions": [
        "JP",
        "DE"
      ],
      "targeted_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "JP"
        },
        {
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "FR"
        }
      ],
      "targeted_industries": [
        "Agriculture",
        "Mining"
      ],
      "targeted_industries_tree": [
        {
          "industry_group": "Agriculture",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        },
        {
          "industry_group": "Mining",
          "confidence": "confirmed"
        }
      ],
      "first_seen_details": [
        {
          "value": "946684800",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ],
      "last_seen_details": [
        {
          "value": "1262304000",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ]
    },
    "relationships": {
      "associations": {
        "data": [
          {
            "type": "collection",
            "id": "threat-actor--9e6b1b9c-bc43-5c7b-a70e-23cbfe4b5bcf"
          },
          {
            "type": "collection",
            "id": "malware--5bd89727-4a3f-541f-9f64-044b87eb66e5"
          },
          {
            "type": "collection",
            "id": "malware--f872b3e0-c277-5716-baae-885a9c410398"
          },
          {
            "type": "collection",
            "id": "campaign--a84b13cd-886c-5597-816d-dd813b71417b"
          },
          {
            "type": "collection",
            "id": "fbb2387395df252e007ae0856ed4dc2ca6d5de734be2bc55707f93b13393756e"
          },
          {
            "type": "collection",
            "id": "vulnerability--mve-2026-9380"
          }
        ]
      },
      "files": {
        "data": [
          {
            "type": "file",
            "id": "d3efbfd26f392c1a87c95d26a79ff92911b1b58c84c72215e0c28929b07e2ae4"
          }
        ]
      },
      "domains": {
        "data": [
          {
            "type": "domain",
            "id": "google.com"
          }
        ]
      },
      "ip_addresses": {
        "data": [
          {
            "type": "ip_address",
            "id": "173.194.199.113"
          }
        ]
      },
      "urls": {
        "data": [
          {
            "type": "url",
            "url": "https://www.realhostx.com/Cloud/Socket/Adb.zip"
          },
          {
            "type": "url",
            "id": "d685d65bf7b7c5d736017d3f85e2617f326ac6651e4cb1ac594b66eeff6e9b8b"
          }
        ]
      },
      "reports": {
        "data": [
          {
            "type": "collection",
            "id": "report--26-10013924"
          }
        ]
      },
      "attack_techniques": {
        "data": [
          {
            "type": "attack_technique", 
            "id": "T1087"
          }
        ]
      }
    }
  }
}
{
  "data": {
    "type": "collection",
    "attributes": {
      "collection_type": "collection",
      "name": "The name of your collection",
      "description": "The description of your collection",
      "private": false,
      "link": "http://test.com",
      "alt_names": [
        "alternative_name_1",
        "alternative_name_2"
      ],
      "tlp": "GREEN",
      "tags": [
        "tag_a",
        "tag_b"
      ],
      "capabilities": [
        {
          "value": "capability_a",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "detection_names": [
        {
          "value": "detection_name_a",
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "operating_systems": [
        {
          "value": "your os",
          "confidence": "possible",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "malware_roles": [
        {
          "value": "Sniffer",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "motivations": [
        {
          "value": "Hacktivism",
          "confidence": "blocklisted",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "sponsor_region": "ES",
      "source_region": "UK",
      "source_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "country": "US",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        }
      ],
      "targeted_regions": [
        "JP",
        "DE"
      ],
      "targeted_regions_hierarchy": [
        {
          "confidence": "unconfirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "JP"
        },
        {
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context",
          "country": "FR"
        }
      ],
      "targeted_industries": [
        "Agriculture",
        "Mining"
      ],
      "targeted_industries_tree": [
        {
          "industry_group": "Agriculture",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000,
          "description": "Some more context"
        },
        {
          "industry_group": "Mining",
          "confidence": "confirmed"
        }
      ],
      "first_seen_details": [
        {
          "value": "946684800",
          "confidence": "suspected",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ],
      "last_seen_details": [
        {
          "value": "1262304000",
          "confidence": "confirmed",
          "first_seen": 946684800,
          "last_seen": 1262304000
        }
      ]
    },
    "raw_items": "Text containing IoCs as www.virustotal.com, 8.8.8.8"
  }
}
🚧

Some regions and industries related attributes, require you to choose between a Simple or Complex (with extra context) format. Please note that these formats are mutually exclusive for each category; you must use either the simple field (e.g., source_region) or the complex field (e.g., source_regions_hierarchy), but never both.

  • Source: source_region OR source_regions_hierarchy (if you want to add extra context)
  • Targeted Regions: targeted_regions OR targeted_regions_hierarchy (if you want to add extra context)
  • Targeted Industries: targeted_industries OR targeted_industries_tree (if you want to add extra context)

Special attributes

Required attributes are:

  • collection_type: threat-actor, campaign, malware-family, software-toolkit or collection for IoC Collections.
  • name: The name of the threat object
  • description: The description of the threat object
  • For IoC Collections only, at least one IoC relationship is required. This must be provided via one of the following fields:raw_items, relationships.files, relationships.urls, relationships.ip_addresses, orrelationships.urls

Attributes with fixed values (enums):

  • tlp: Valid values are CLEAR, GREEN, AMBER and RED.
  • x.confidence: Valid values are confirmed, unconfirmed, possible, suspected, crowdsourced and blocklisted.
  • x.country: This field can be set to any ISO country code or country name.
  • targeted_industries_tree.industry_group: Valid values are listed here as targeted_industry_group.
  • malware_roles.value: Valid values are listed here as malware_role.
  • motivations.value: Valid values are listed here as motivation.
  • source_region, sponsor_region and targeted_regions: Valid values are listed here as source_region or targeted_region.

Other attributes:

  • x.first_seen and x.last_seen: Valid values are numerical UTC timestamps.
  • relationships.urls[x]: Each object must contain either a url field (the full URL string) or an id field (URL the hash identifier).

For other dictionary-based attributes, simply omit any fields you do not wish to explicitly set. For example, if first_seen or last_seen data is unavailable, you can exclude them from the request entirely as follows:

"targeted_regions_hierarchy": [
  {
    "confidence": "unconfirmed",
    "country": "US"
  }
]

Use the first option instead of:

"targeted_regions_hierarchy": [
  {
    "confidence": "unconfirmed",
    "country": "US",
    "first_seen": null,
    "last_seen": null
  }
]

To modify a threat object attributes or add more elements to an IoC collection using a raw text, refer to the PATCH/collections/{id} endpoint.
To add new elements or relationships to threat objects refer to the POST /collections/{id}/{relationship} endpoint.
To remove elements or relationships from threat objects refer to the DELETE /collections/{id}/{relationship} endpoint.

Examples

Create a new private IoC collection with 2 IoCs which are google.com and virustotal.com domains.

import requests

url = "https://www.virustotal.com/api/v3/collections"
payload = {
    "data":
    {
        "type": "collection",
        "attributes":
        {
            "name": "Test IoC collection",
            "description": "This is how to create a new collection via API.",
            "private": True
        },
        "raw_items": "google.com, google.com"
    }
}
headers = {
    "accept": "application/json","x-apikey": <api-key>,"content-type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
Body Params
json
required

Collection object

Headers
string
required

Your API key

Responses

Updated 3 months ago

Did this page help you?
Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 3 months ago

Did this page help you?