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.

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.

Code	Status	Description
200	OK	Request successful
201	Created	Request successful, resource was created
202	Accepted	Request successful, resource was created or updated
204	No Content	Request successful, no additional information to return
400	Bad Request	Request was invalid of malformed
401	Unauthorized	You did not supply valid authentication credentials
403	Forbidden	You are not allowed to perform that action
429	Too many requests	Your request exceeded the API rate limit
500	Internal Server Error	Unable 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:

Domain	Status
suspicious.test.phisherman.gg	Triggers as a suspicious domain
verified.test.phisherman.gg	Triggers as a verified, malicious domain
unknown.test.phisherman.gg	Triggers as an unknown domain

Expected Responses

Checking a domain (v2 API)

{
    "classification": "suspicious",
    "verifiedPhish": false
}

{
    "classification": "malicious",
    "verifiedPhish": true
}

{
    "classification": "unknown",
    "verifiedPhish": false
}