Using the Submission API

This document describes how to submit URLs that you suspect are unsafe to Safe Browsing for analysis, and asynchronously check the results of these submissions. Any URLs that are confirmed to violate the Safe Browsing Policies are added to the Safe Browsing service.

Before you begin

Contact sales or your customer engineer to obtain access to this feature.

Best Practices

Read the Safe Browsing Policies

The Web Risk Submission API validates that the submitted URLs render content violating Safe Browsing policies. API developers must ensure that the submitted URLs have clear evidence of violating these policies. The following examples show evidence of violation of policies:

• Social engineering content that mimics a legitimate online brand (brand name, logo, look and feel), system alerts, uses deceptive URLs, or requests users to enter sensitive credentials such as a username or password.
• A site that is hosting a known malware executable.

Don't submit the following types of URLs because they're unlikely to be added to the Safe Browsing blocklist:

• Fake surveys, shopping sites, or other scams that don't demonstrate phishing (such as cryptocurrency scams).
• Spam containing gambling, violence, or adult content that is not phishing or malware.

Improve detection

We recommend using ThreatInfo and ThreatDiscovery fields to provide additional information about submissions. Doing so might help improve detection. For more information, see Best practices for using the Submission API.

Submit URLs

To submit a URL, send an HTTP POST request to the projects.uris.submit method.

• The Submission API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.

• The URL must be valid but it doesn't need to be canonicalized. For more information, see RFC 2396.

• The HTTP POST response returns a long-running operation. For more information about how to retrieve the submission result and check the status of a submission, see Long-running operations.

Example

HTTP method and URL:

POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit

Request JSON body:

{
  "submission": {
    "uri": "https://www.example.com/login.html"
  }
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/project-number/operations/operation-id",
}

Check the submission status

Use the project-number and operation-id from the response to check the submission status. The status is located in the metadata.state field of the returned operation.

The possible states include RUNNING, SUCCEEDED, and CLOSED. For more information about these states, see Understanding Operation Status in the Long-running Operations guide.