Lookup

This is the main endpoint of the Threat Intelligence service. It allows you to fetch the risk of a URL, along with more detailed information on the violations that occurred.

Intelligence provided

Risk

The risk is a single number from 0 to 5, where 0 is risk-free and 5 represents a very severe risk of the domain incurring in a violation. It is computed based on the violation map included in the response and a violation weight map. Each violation has an associated weight that will determine its importance in computing the risk. The violation weight map can either be the default provided by AdSecure or be user-defined.

Violation map

AdSecure also provides you with the list of all the violations that occurred on this URL. For each of those violations, we include:

• login: the name of the violation
• lastDetected: the time when it was last detected
• probability: the probability of the violation occurring on this URL directly, or further down the redirection chain. If the probability is 0.8, we estimate that the violation has a 80% risk of occurring

The violations array may be empty. In this case, the domain is known to us but no violations were recorded. This is the safest response possible.

For further information on what the violations mean, see the full list of violations.

Metadata

• lastAnalysed: the time when this domain was last analysed
• expireTime: the time when AdSecure will compute again the data for this domain

Request shape

You need to be authenticated to use this method.

Method: POST

Path: /lookup

Body:

{
  "url": "https://example.com/url"
}

cURL:

curl --request POST \
  -H "Content-Type: application/json" \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{"url":"https://example.com/url"}' \
  -v  https://api.adsecure.com/threat-intelligence/v1/lookup

Response shape

{
  "risk": 2,
  "lastAnalysed": "2019-10-04T13:59:10Z",
  "violations": [
    {
      "login": "ssl-non-compliant",
      "lastDetected": "2019-04-04T13:59:10Z",
      "probability": 0.83
    },
    {
      "login": "ransomware",
      "lastDetected": "2019-04-04T13:59:10Z",
      "probability": 0.2
    }
  ],
  "expireTime": "2019-10-04T15:22:08Z"
}

Response status codes

Status code	Meaning
200	Successful request, response payload with mentioned shape will be attached.
202	Successful request, but the requested URL is still being processed. Another request will have to be made to access the result. Currently the processing time is of a few seconds. Please consider either a delay or exponential backoff for your implementation.
204	Successful request, the URL was not found in our database, no body will be attached. A full analysis on your part is needed for this URL to be added to our database.

Troubleshooting

Status code	Error message	Solution
400	Bad Request	The body of the request is not a valid JSON format.
401	Unauthorized	Either the Authorization header is not sent or it has an incorrect value.
403	Forbidden	API key doesn't have the correct permissions for the endpoint.