Getting Started

Requesting API access

While Phisherman is still development access is granted on a per-person basis while we work to ensure overall stability, performance and gather user feedback.

To request access, please join our Discord serveropen in new window and send a direct message to ModMail to request access.

ModMail

NOTE

Phisherman is still development and there may be breaking bugs or unplanned outages. Please keep this in mind if you are planning to integrate this into a live bot.

🚫 The following will not be eligible for access to Phisherman:

  • iOS, Google Play Store or Kindle apps
  • College or University projects/assignments
  • Private bots for testing or development purposes only

Endpoints

The API is accessed by making HTTPS requests to a specific version endpoint URL, in which GET, POST and PUT methods dictate how your interact with the endpoint.

The stable base URL for all Version 1 endpoints is:

https://api.phisherman.gg/v1/

Requests

Requests must be sent over HTTPS with any payload formatted in JSON. Depending on if a request required authentication you will also need to include your API token in the appropriate header.

API Key

API keys provide a way to authenticate with the Phisherman API. They allow for scoped and permissioned access to resources and use the Authorization Bearer Token Headeropen in new window.

API Permissions

Some API endpoints require additional permissions to be enabled for your account as well as an API token to be sent via headers. You can view your current API permissions on your settings pageopen in new window

Rate Limit

The Phisherman API rate limits requests in order to prevent abuse and overload of our services. All users can make up to 50 requests per 10 seconds to our API.

All applications should make reasonable attempts to avoid making invalid requests. For example:

  • 401 responses are avoided by providing a valid token in the authorization header when required and by stopping further requests after a token becomes invalid
  • 403 responses are avoided by inspecting required permissions and by not making requests that are restricted by such permissions

If you have a very large application that may exceed this limit on on a regular or sustained basis, please contact us via ModMail.

HTTP response codes

The status of a response can be determined from the HTTP status code.

CodeStatusDescription
200OKRequest successful
201CreatedRequest successful, resource was created
202AcceptedRequest successful, resource was created or updated
204No ContentRequest successful, no additional information to return
400Bad RequestRequest was invalid of malformed
401UnauthorizedYou did not supply valid authentication credentials
403ForbiddenYou are not allowed to perform that action
429Too many requestsYour request exceeded the API rate limit
500Internal Server ErrorUnable to perform the request due to server-side problems

Testing your integration

In order for you to verify your Phisherman integration is fully functional, we provide a selection of domains that will trigger Phisherman as a real phish would.

The following domains can be used for testing:

DomainStatus
suspicious.test.phisherman.ggTriggers as a suspicious domain
verified.test.phisherman.ggTriggers as a verified, malicious domain
unknown.test.phisherman.ggTriggers as an unknown domain

Expected Responses

Checking a domain (v2 API)

{
    "classification": "suspicious",
    "verifiedPhish": false
}
1
2
3
4
{
    "classification": "malicious",
    "verifiedPhish": true
}
1
2
3
4
{
    "classification": "unknown",
    "verifiedPhish": false
}
1
2
3
4
Last Updated: