Stay organized with collections
Save and categorize content based on your preferences.
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 in order to obtain access to
this feature.
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 evidences 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.
API developers should not submit these types of URLs, as they most likely will not be added to Safe Browsing blocklists:
Fake surveys, shopping sites, or other scams that do not demonstrate phishing (such as cryptocurrency scams).
Spam containing gambling, violence, or adult content that is not phishing or malware.
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
SUCCEEDED indicates that the submitted URL was added to the Safe Browsing
Blocklist.
CLOSED indicates that the submitted URL was not detected to violate the Safe
Browsing Policies and was not added to the Safe Browsing Blocklist in the last
24 hours.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[],[],null,["# Using the Submission API\n========================\n\nThis document describes how to submit URLs that you suspect are unsafe to\nSafe Browsing for analysis, and asynchronously check the results of these\nsubmissions. Any URLs that are confirmed to violate the [Safe Browsing Policies](https://safebrowsing.google.com/#policies)\nare added to the Safe Browsing service.\n\nBefore you begin\n----------------\n\n[Contact sales](https://cloud.google.com/contact) or your customer engineer in order to obtain access to\nthis feature.\n\nBest Practices\n--------------\n\n### Read the [Safe Browsing Policies](https://safebrowsing.google.com/#policies)\n\nThe Web Risk Submission API validates that the submitted URLs render content violating Safe Browsing [policies](https://safebrowsing.google.com/#policies). API developers must ensure that the submitted URLs have clear evidence of violating these policies. The following examples show evidences of violation of policies:\n\n- 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.\n- A site that is hosting a known Malware executable.\n\nAPI developers should not submit these types of URLs, as they most likely will not be added to Safe Browsing blocklists:\n\n- Fake surveys, shopping sites, or other scams that do not demonstrate phishing (such as cryptocurrency scams).\n- Spam containing gambling, violence, or adult content that is not phishing or malware.\n\nSubmit URLs\n-----------\n\nTo submit a URL, send an HTTP `POST` request to\nthe [`projects.uris.submit`](/web-risk/docs/reference/rest/v1/projects.uris/submit)\nmethod.\n\n- The Submission API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.\n- The URL must be valid but it doesn't need to be canonicalized. For more\n information, see [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt).\n\n- The HTTP `POST` response returns a [`long-running operation`](/web-risk/docs/reference/rpc/google.longrunning).\n For more information about how to retrieve the submission result and check\n the status of a submission, see [Long-running operations](/web-risk/docs/long-running-operations).\n\nExample\n-------\n\n\nHTTP method and URL:\n\n```\nPOST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit\n```\n\n\nRequest JSON body:\n\n```\n{\n \"submission\": {\n \"uri\": \"https://www.example.com/login.html\"\n }\n}\n```\n\nTo send your request, choose one of these options: \n\n#### curl\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`,\nand execute the following command:\n\n```\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://webrisk.googleapis.com/v1/projects/project-id/uris:submit\"\n```\n\n#### PowerShell\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`,\nand execute the following command:\n\n```\n$cred = gcloud auth print-access-token\n$headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\nInvoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://webrisk.googleapis.com/v1/projects/project-id/uris:submit\" | Select-Object -Expand Content\n```\n\nYou should receive a JSON response similar to the following:\n\n```\n{\n \"name\": \"projects/project-number/operations/operation-id\",\n}\n```\n\n### Check the submission status\n\nYou can [check the status of the submission](/web-risk/docs/long-running-operations#get)\nby using the `project-number` and `operation-id` values from the response.\n\n`SUCCEEDED` indicates that the submitted URL was added to the Safe Browsing\nBlocklist.\n\n`CLOSED` indicates that the submitted URL was not detected to violate the Safe\nBrowsing Policies and was not added to the Safe Browsing Blocklist in the last\n24 hours."]]