{"__v":0,"_id":"581a0dadfe3a8e0f00ba358d","category":{"__v":19,"_id":"5615790d0f5ed00d00483dd5","pages":["5615790e0f5ed00d00483dd7","561d48e46386060d00e06003","561d48fe31d9630d001eb5bd","561d49b657165b0d00aa5d8b","561d4a879463520d00cd11e2","561d67f48ca8b90d00210234","561d6a0bf0cff80d00ca22c3","561d6c5b071cd60d000d3221","562f9c2543c5570d001fe6bd","56311c99eae7ef0d00270e3d","56311d6702aff217007dba23","56311f96f1c0580d00fac719","563120b7242cda1900198b79","5631229bf1c0580d00fac721","563131559ead230d00a188f6","563134a324014b0d00bd9a4f","5631392082d96a0d00b0fb1d","56313c584b36120d00fdebfb","5642658ef424a10d00118360"],"project":"5615790c0f5ed00d00483dd1","version":"5615790d0f5ed00d00483dd4","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-07T19:57:01.871Z","from_sync":false,"order":0,"slug":"opendns-investigate-rest-api","title":"Umbrella Investigate REST API"},"parentDoc":null,"project":"5615790c0f5ed00d00483dd1","user":"560b40145148ba0d009bd0b5","version":{"__v":6,"_id":"5615790d0f5ed00d00483dd4","project":"5615790c0f5ed00d00483dd1","createdAt":"2015-10-07T19:57:01.307Z","releaseDate":"2015-10-07T19:57:01.307Z","categories":["5615790d0f5ed00d00483dd5","56157b2af432910d0000f9fe","56157cfb0f5ed00d00483ddb","562684d95db46b1700fd4f48","573b7ea9ef164e2900a2b8ff","582e285d8373c20f00810608"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-02T16:00:45.114Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"examples":{"codes":[{"name":"","code":"","language":"text"}]},"auth":"required","params":[],"url":"/domains/categorization/amazon.com"},"isReference":false,"order":5,"body":"This API method returns the domain status, which the quickest and easiest way to know whether a domain has been flagged as malicious by the Cisco Security Labs team (score of -1 for status), if it is believed to be safe (score of 1), or if it has yet to be given a status (score of 0). __When looking to determine whether or not a domain is malicious, the domain status should be considered authoritative over all other Investigate scores.__\n\nThis method will also return the security categories and content categories of a domain. Categories are the labels or tags Umbrella has given to a domain for the purposes of filtering against that type of domain. The GET request can be returned with numerical or human readable labels for the domains, but a bulk domain lookup with a POST request can only return the numerical label.\n\nA domain can have multiple, overlapping security categories and content categories. For instance, a domain could be both 'Botnet' and 'Malware' if it is deemed to serve malware and also be a command and control. For content, a site could be both 'Dating' and 'Sexuality'.\n\nA list of the numerical identifiers for the categories can be obtained with the following query:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\"\\n\\\"https://investigate.api.umbrella.com/domains/categories/\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nTo query for more than one domain at a time, use the POST example below and post a list of domains as an array. This method will accept up to 1000 domains in a single request.\n\nSample query for a single domain:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" \\\"https://investigate.api.umbrella.com/domains/categorization/example.com\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSample query for a single domain with human-readable labels:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" \\\"https://investigate.api.umbrella.com/domains/categorization/example.com?showLabels\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSample query for multiple domains:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer %YourToken%\\\" --request POST \\\"https://investigate.api.umbrella.com/domains/categorization/\\\" -d '[\\\"example.net\\\",\\\"example.org,\\\",\\\"example.com\\\"]'\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n### Parameter for input\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"name\",\n    \"0-1\": \"string\",\n    \"0-2\": \"Domain name\",\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n### Returned value for output if Success 200\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"status\",\n    \"1-0\": \"security_categories\",\n    \"2-0\": \"content_categories\",\n    \"0-1\": \"integer\",\n    \"0-2\": \"The status will be \\\"-1\\\" if the domain is believed to be malicious, \\\"1\\\" if the domain is believed to be benign, \\\"0\\\" if it hasn't been classified yet.\",\n    \"1-2\": \"The Umbrella security category, or categories, that match this domain or that this domain is associated with. If none match, the return will be blank.\",\n    \"2-2\": \"The Umbrella content category or categories that match this domain. If none match, the return will be blank.\",\n    \"1-1\": \"array of strings\",\n    \"2-1\": \"array of strings\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/domains/categorization/amazon.com\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n    --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\n    https://investigate.api.umbrella.com/domains/categorization/amazon.com\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em></em>\\n    </div>\\n    <pre>\\n{\\n  \\\"amazon.com\\\": {\\n    \\\"status\\\": 1,\\n    \\\"security_categories\\\": [],\\n    \\\"content_categories\\\": [\\n      \\\"8\\\"\\n    ]\\n  }\\n}\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">POST</span> https://investigate.api.umbrella.com/domains/categorization/\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\    \\n    --request POST \\\\    \\n    --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\n    --data-binary \\\"[\\\\\\\"google.com\\\\\\\",\\\\\\\"yahoo.com\\\\\\\"]\\\" \\\\\\n    https://investigate.api.umbrella.com/domains/categorization\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n{\\n  \\\"google.com\\\": {\\n    \\\"status\\\": 1,\\n    \\\"security_categories\\\": [],\\n    \\\"content_categories\\\": [\\n      \\\"23\\\"\\n    ]\\n  },\\n  \\\"yahoo.com\\\": {\\n    \\\"status\\\": 1,\\n    \\\"security_categories\\\": [],\\n    \\\"content_categories\\\": [\\n      \\\"23\\\"\\n    ]\\n  }\\n}\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/domains/categorization/amazon.com?showlabels\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n    --header \\\"Authorization: Bearer %YourToken%\\\" \\\\\\n    https://investigate.api.umbrella.com/domains/categorization/amazon.com?showLabels\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n{\\n  \\\"amazon.com\\\": {\\n    \\\"status\\\": 1,\\n    \\\"security_categories\\\": [],\\n    \\\"content_categories\\\": [\\n      \\\"Ecommerce/Shopping\\\"\\n    ]\\n  }\\n}\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<div class=\\\"api-code-block\\\">\\n  <div class=\\\"api-code-block__header\\\">\\n    <span class=\\\"api-code-block__header__label\\\">GET</span> https://investigate.api.umbrella.com/domains/categories/\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">REQUEST</div>\\n    <pre>curl --include \\\\\\n    --header \\\"Authorization: Bearer %YourToken%\\\"\\n    https://investigate.api.umbrella.com/domains/categories/\\n    </pre>\\n  </div>\\n  <div class=\\\"api-code-block__section\\\">\\n    <div class=\\\"api-code-block__section__header\\\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\\n    </div>\\n    <pre>\\n{\\n    ...\\n    8: \\\"Ecommerce/Shopping\\\",\\n    9: \\\"File storage\\\",\\n    ...\\n}\\n--\\n    </pre>\\n  </div>\\n</div>\"\n}\n[/block]\n---\n[Error Handling](https://docs.umbrella.com/developer/investigate-api/error-handling-1/) < **Domain Status and Categorization** > [Domain Scores](https://docs.umbrella.com/developer/investigate-api/domain-scores-1/)","excerpt":"","slug":"domain-status-and-categorization-1","type":"basic","title":"Domain Status and Categorization"}

Domain Status and Categorization


This API method returns the domain status, which the quickest and easiest way to know whether a domain has been flagged as malicious by the Cisco Security Labs team (score of -1 for status), if it is believed to be safe (score of 1), or if it has yet to be given a status (score of 0). __When looking to determine whether or not a domain is malicious, the domain status should be considered authoritative over all other Investigate scores.__ This method will also return the security categories and content categories of a domain. Categories are the labels or tags Umbrella has given to a domain for the purposes of filtering against that type of domain. The GET request can be returned with numerical or human readable labels for the domains, but a bulk domain lookup with a POST request can only return the numerical label. A domain can have multiple, overlapping security categories and content categories. For instance, a domain could be both 'Botnet' and 'Malware' if it is deemed to serve malware and also be a command and control. For content, a site could be both 'Dating' and 'Sexuality'. A list of the numerical identifiers for the categories can be obtained with the following query: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\"\n\"https://investigate.api.umbrella.com/domains/categories/\"", "language": "text" } ] } [/block] To query for more than one domain at a time, use the POST example below and post a list of domains as an array. This method will accept up to 1000 domains in a single request. Sample query for a single domain: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" \"https://investigate.api.umbrella.com/domains/categorization/example.com\"", "language": "text" } ] } [/block] Sample query for a single domain with human-readable labels: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" \"https://investigate.api.umbrella.com/domains/categorization/example.com?showLabels\"", "language": "text" } ] } [/block] Sample query for multiple domains: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer %YourToken%\" --request POST \"https://investigate.api.umbrella.com/domains/categorization/\" -d '[\"example.net\",\"example.org,\",\"example.com\"]'", "language": "text" } ] } [/block] ### Parameter for input [block:parameters] { "data": { "0-0": "name", "0-1": "string", "0-2": "Domain name", "h-0": "Field", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 1 } [/block] ### Returned value for output if Success 200 [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "status", "1-0": "security_categories", "2-0": "content_categories", "0-1": "integer", "0-2": "The status will be \"-1\" if the domain is believed to be malicious, \"1\" if the domain is believed to be benign, \"0\" if it hasn't been classified yet.", "1-2": "The Umbrella security category, or categories, that match this domain or that this domain is associated with. If none match, the return will be blank.", "2-2": "The Umbrella content category or categories that match this domain. If none match, the return will be blank.", "1-1": "array of strings", "2-1": "array of strings" }, "cols": 3, "rows": 3 } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/domains/categorization/amazon.com\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\n https://investigate.api.umbrella.com/domains/categorization/amazon.com\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em></em>\n </div>\n <pre>\n{\n \"amazon.com\": {\n \"status\": 1,\n \"security_categories\": [],\n \"content_categories\": [\n \"8\"\n ]\n }\n}\n </pre>\n </div>\n</div>" } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">POST</span> https://investigate.api.umbrella.com/domains/categorization/\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\ \n --request POST \\ \n --header \"Authorization: Bearer %YourToken%\" \\\n --data-binary \"[\\\"google.com\\\",\\\"yahoo.com\\\"]\" \\\n https://investigate.api.umbrella.com/domains/categorization\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n{\n \"google.com\": {\n \"status\": 1,\n \"security_categories\": [],\n \"content_categories\": [\n \"23\"\n ]\n },\n \"yahoo.com\": {\n \"status\": 1,\n \"security_categories\": [],\n \"content_categories\": [\n \"23\"\n ]\n }\n}\n </pre>\n </div>\n</div>" } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/domains/categorization/amazon.com?showlabels\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\" \\\n https://investigate.api.umbrella.com/domains/categorization/amazon.com?showLabels\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n{\n \"amazon.com\": {\n \"status\": 1,\n \"security_categories\": [],\n \"content_categories\": [\n \"Ecommerce/Shopping\"\n ]\n }\n}\n </pre>\n </div>\n</div>" } [/block] [block:html] { "html": "<div class=\"api-code-block\">\n <div class=\"api-code-block__header\">\n <span class=\"api-code-block__header__label\">GET</span> https://investigate.api.umbrella.com/domains/categories/\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">REQUEST</div>\n <pre>curl --include \\\n --header \"Authorization: Bearer %YourToken%\"\n https://investigate.api.umbrella.com/domains/categories/\n </pre>\n </div>\n <div class=\"api-code-block__section\">\n <div class=\"api-code-block__section__header\">RESPONSE <em>(HTTP 200, Content-Type: application/json)</em>\n </div>\n <pre>\n{\n ...\n 8: \"Ecommerce/Shopping\",\n 9: \"File storage\",\n ...\n}\n--\n </pre>\n </div>\n</div>" } [/block] --- [Error Handling](https://docs.umbrella.com/developer/investigate-api/error-handling-1/) < **Domain Status and Categorization** > [Domain Scores](https://docs.umbrella.com/developer/investigate-api/domain-scores-1/)