Skip to navigation
BotBye APIAnti-PhishingReport Phishing

report

View as Markdown

Report a domain that impersonates your brand.

The whole report is one multipart/form-data request — nothing has to be uploaded anywhere first:

  • report — required JSON part carrying the reported domain and, optionally, a short title and description of what you saw.
  • attachments — every other part, sent as a file: screenshots of the clone, a saved copy of the page. Each part must carry a file name; the part’s own name is up to you. At most 5 files, 5 MB each and 9 MB in total. The type is read from the file content, not from the part’s Content-Type — an image, a PDF or an HTML page is accepted.
curl -X POST https://api.botbye.com/api/v1/phishing/{account_id}/projects/{project_id}/phishing-domains \
  -H "X-Api-Key: $BOTBYE_TOKEN" \
  -F 'report={"domain":"clone-example.com","title":"Cloned login page","description":"Same markup as our sign-in page, the form posts to another host"}' \
  -F 'files=@clone-login.png'

The report fields and the attachments together become the evidence stored with the report; a report carrying neither is filed as a bare domain.

The reported domain is collapsed to its registrable domain, so a host and its parent never become two reports: login.clone-example.com is filed as clone-example.com. Where that boundary sits is decided by the Public Suffix List, so multi-label suffixes and shared hosting suffixes keep their own label — shop.clone-example.co.uk is filed as clone-example.co.uk, and clone.github.io stays clone.github.io. The resulting phishing domain is queued for manual review before any takedown action is taken.

The endpoint answers an empty 200 whether or not a new entry was created: a domain the project already tracks, a domain the account itself owns (in this or any of its other projects) and a reserved / special-use TLD are all skipped rather than rejected, so re-sending the same report is safe. A malformed request answers 400 with an error code naming the fault, and a project the token’s account does not own answers 404.

Before a project can report anything it must have proven that it controls its site — the registrable domain of the project’s domain: the verification token is published either as a DNS TXT record on that registrable domain or as a <meta> tag on its home page. Ownership is proven from your BotBye account — the API carries no endpoint for it. Until that proof is on file every report answers 403 protection_phishing_domain_verification.project_domain_not_verified.

Accepted permissions Account → Phishing Projects → Create

Token scope Account Phishing Projects Action

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Path parameters

account_idstringRequired
project_idstringRequired

Request

This endpoint expects a multipart form with multiple files.
reportobjectRequired
filesfilesOptional

Response

success — the response has no body