Quickstart using the Submission API

This quickstart walks you through using the Phishing Protection Submission API to submit URLs that you suspect are unsafe to Safe Browsing. Any URLs that are confirmed to match the Safe Browsing Policies will be added to the Safe Browsing list.

Before you begin

Phishing Protection is not yet generally available, so you must be whitelisted in order to gain access. To sign up for the beta, complete the Phishing Protection Beta Program form. When you're approved, you will receive an email from the Phishing Protection team.

Before you use the Phishing Protection Submission API, review and understand the Usage Limits.

Setting up the Phishing Protection API

Step 1: Enable the Phishing Protection API

After you get confirmation that you have been whitelisted, enable the Phishing Protection API.

  • Enable the Phishing Protection API.

    Enable the API

  • Step 2: Create an API key

    To access the Phishing Protection API, you need an API key. An API key authenticates you as an API user and allows you to interact with the APIs. You pass this key as a URL parameter in your HTTP requests to the Phishing Protection server. To create an API key:

    1. Go to the APIs & Services Credentials page in the Google Cloud Console.
      Go to the Credentials page
    2. On the project selector drop-down list, select the project you want to use with the Phishing Protection API.
    3. Click Create credentials, and then select API key.

    You can now use the project in which you created the API key to use the Phishing Protection API. The Phishing Protection API methods require you to specify the Google Cloud project that you used to create your API key. To learn how to find your project number, see Identifying projects

    Using the Phishing Protection API

    Reporting Phishing URIs

    To report a phishing URL, send a request to the phishing.report method:

    • The request includes the URI that is being reported for serving phishing content.
    • The response returns just the status code with an empty body.

    Example: phishing.report

    Request

    In the following example, the reported URI is https://www.phishingsite.com/. For more details, see the phishing.report request body

    curl \
      -X POST \
      -H "Content-Type: application/json" \
      "https://phishingprotection.googleapis.com/v1beta1/projects/PROJECT_NUMBER/phishing:report?key=YOUR_API_KEY" \
      -d "{'uri': 'https://www.phishingsite.com/'}"
    

    URI

    The uri field holds the URI that is being reported for serving phishing content. After it's reported, it will be reviewed asynchronously.

    Response

    In this example, the response just contains the HTTP/200 OK status code header and an empty message in the body. The OK status indicates that the report was accepted and enqueued for review. After the review is completed, its result will be available in the Phishing Protection findings on the Security Command Center dashboard. If the result confirms the presence of phishing content, the URI will be added to Google's Social Engineering lists.

    What's next