Phisherman

Reporting a caught phish POST

WARNING

v2 API is still in beta, there may be breaking changes at any time. It is recommended you keep updated with the #v2-api-betaopen in new window channel in Discord for updates and announcements.

When integrating the Phisherman checks with your Discord bot, you can optionally report back when it catches a phish in your server(s).

TIP

Reporting back caught phish is entirely optional and not required for normal usage, it purely helps us with our analytics

🔒 Auth Token: Required
🔑 API Permission Required: API.UPDATE

The URL for this endpoint is:

https://api.phisherman.gg/v2/phish/caught/<domain>

Required Parameters

NameTypeDescription
domainstringThe fully qualified domain name you wish to query

Optional Parameters

NameTypeDescription
guildintegerThe Discord ID of the Guild this phish was found in

Example Requests

curl -L -X POST "https://api.phisherman.gg/v2/phish/caught/suspicious.test.phisherman.gg" \
-H "Authorization: Bearer <API-KEY>" \
-H "Content-Type: application/json" \
--data-raw "{
    \"guild\": 878130674844979210
}"
1
2
3
4
5
6
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <API-KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "guild": 878130674844979200
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.phisherman.gg/v2/phish/caught/suspicious.test.phisherman.gg", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import http.client
import json

conn = http.client.HTTPSConnection("api.phisherman.gg")
payload = json.dumps({
  "guild": 878130674844979200
})
headers = {
  'Authorization': 'Bearer <API-KEY>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/v2/phish/caught/suspicious.test.phisherman.gg", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Example Response

HTTP2/204
1

Bulk Reporting

For public bots that serve a large number of guilds, Phisherman offers a bulk reporting endpoint to help reduce the number of API calls made.

🔒 Auth Token: Required
🔑 API Permission Required: API.UPDATE_BULK

The URL for this endpoint is:

https://api.phisherman.gg/v2/phish/caught/bulk
1

Example JSON payload

The JSON payload for this endpoint uses the end-users API key as the object key, followed by the fully-qualified domain, then an array of timestamps. This allows the end user to view the number of Phish they have caught in the dashboardopen in new window

{
    "<USER#1-API-KEY>": {
        "suspicious.test.phisherman.gg": [
            1635591332,
            1635592459
        ],
        "malicious.test.phisherman.gg": [
            1635591332
        ]
    },
    "<USER#2-API-KEY-2>": {
        "suspicious.test.phisherman.gg": [
            1635591332,
            1635592459
        ],
        "malicious.test.phisherman.gg": [
            1635591332
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

TIP

We recommend caching caught phish data locally, and sending a periodic request to bulk report them every 10 minutes.

Example Requests

curl -L -X POST "https://api.phisherman.gg/v2/phish/caught/bulk" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API-KEY>" \
--data-raw "{
    \"<USER#1-API-KEY>\": {
        \"suspicious.test.phisherman.gg\": [
            1635591332,
            1635592459
        ],
        \"malicious.test.phisherman.gg\": [
            1635591332
        ]
    },
    \"<USER#2-API-KEY-2>\": {
        \"suspicious.test.phisherman.gg\": [
            1635591332,
            1635592459
        ],
        \"malicious.test.phisherman.gg\": [
            1635591332
        ]
    }
}"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer <API-KEY>");

var raw = JSON.stringify({
  "<USER#1-API-KEY>": {
    "suspicious.test.phisherman.gg": [
      1635591332,
      1635592459
    ],
    "malicious.test.phisherman.gg": [
      1635591332
    ]
  },
  "<USER#2-API-KEY-2>": {
    "suspicious.test.phisherman.gg": [
      1635591332,
      1635592459
    ],
    "malicious.test.phisherman.gg": [
      1635591332
    ]
  }
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.phisherman.gg/v2/phish/caught/bulk", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
import http.client
import json

conn = http.client.HTTPSConnection("api.phisherman.gg")
payload = json.dumps({
  "<USER#1-API-KEY>": {
    "suspicious.test.phisherman.gg": [
      1635591332,
      1635592459
    ],
    "malicious.test.phisherman.gg": [
      1635591332
    ]
  },
  "<USER#2-API-KEY-2>": {
    "suspicious.test.phisherman.gg": [
      1635591332,
      1635592459
    ],
    "malicious.test.phisherman.gg": [
      1635591332
    ]
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer <API-KEY>'
}
conn.request("POST", "/v2/phish/caught/bulk", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Example response

HTTP2/204
1
Last Updated: