# Best practices for using the Submission API

This document describes the recommended implementation for the Submission API:

- **Submit complete URLs**: Provide the full, direct URL to the malicious content, not just the domain.
- **Submit only active URLs**: Submit live URLs only. Offline or unreachable sites can't be processed.
- **Include policy violations** : Only submit URLs that you have reason to
  believe are unsafe and violate [Google Safe Browsing
  Policies](https://safebrowsing.google.com/#policies).

- **Programmatic submission** : Use the [Submission API](https://docs.cloud.google.com/web-risk/docs/submission-api.md.txt)
  to automate high-volume reports from external sources like Security
  Operations Center teams or end-user reports.

- **Include additional metadata** : To help improve the speed and accuracy of threat
  detection, provide metadata with your submissions. For more
  information, see [Improve detection with `ThreatInfo` and
  `ThreatDiscovery`](https://docs.cloud.google.com/web-risk/docs/best-practices-submission#threat-info-and-discovery).

## Improve detection with `ThreatInfo` and `ThreatDiscovery`

We recommend using the following [`ThreatInfo`](https://docs.cloud.google.com/web-risk/docs/reference/rest/v1/projects.uris/submit.md.txt#threatinfo) and [`ThreatDiscovery`](https://docs.cloud.google.com/web-risk/docs/reference/rest/v1/projects.uris/submit.md.txt#threatdiscovery) fields to provide additional information about submissions, which can improve detection and increase the chances of a submission being blocked.

- Use `ThreatInfo` to provide more information about why the URI is being submitted.
- Use `ThreatDiscovery` to provide more information about how the threat was found.

### Example

An attacker launches a credential phishing site targeting clients of a bank based in Italy. Targeted clients begin receiving deceptive text messages from that attacker with a link to a fake login page. The bank receives reports from clients that received the texts, launches an investigation, and confirms that the site is phishing for credentials.

To help protect their clients, the bank submits the phishing site to
Web Risk with the following request body:

    {
      "submission": {
        "uri": "http://example.com/login.html"
      },
      "threatDiscovery": {
        "platform": "ANDROID",
        "regionCodes": "IT"
      },
      "threatInfo": {
        "abuseType": "SOCIAL_ENGINEERING",
        "abuseSubtype": "BANK_PHISHING",
        "threatJustification": {
          "labels": ["USER_REPORT", "MANUAL_VERIFICATION"],
          "comments": "Site is impersonating a bank and phishing for login credentials"
        },
        "threatConfidence": {
          "level": "HIGH"
        },
        "targetedBrand": {
          "brandName": "Altostrat",
          "domain": "altostrat.com"
        }
      }
    }

> [!NOTE]
> **Note:** `abuseSubtype` and `targetedBrand` are available in [Preview](https://cloud.google.com/products#product-launch-stages).

When the bank checks the status of the submission with the operation name returned by the Submission API, the status is `SUCCEEDED`. This status indicates that the submitted URL was added to the Safe Browsing block list.

## What's next

- View the API reference for `ThreatInfo` and `ThreatDiscovery` ([RPC](https://docs.cloud.google.com/web-risk/docs/reference/rpc/google.cloud.webrisk.v1.md.txt#submiturirequest), [REST](https://docs.cloud.google.com/web-risk/docs/reference/rest/v1/projects.uris/submit.md.txt)).