PhishTank > API Documentation

API Documentation

API Diagram

Click thumbnail to view an API flow diagram.

Other ways to use PhishTank data

There are other ways to retrieve and use PhishTank data outside of the API.

XML data file of online, valid phishes from PhishTank

Full data file, updated hourly, of every online, valid phish.

Simple developer method for checking individual URLs

A lightweight way to check a single URL, base64 encoded.

Friends of PhishTank

PhishTank data has already made its way into multiple services and applications.

Introduction: Using the PhishTank API
Registering your application
Connecting
Request Format
Response Format
Versioning
Actions

Introduction: Using the PhishTank API

We've tried to make using the PhishTank API as easy as possible while still being secure and sensitive to the data we're passing back over the wire. There are a few things you should know before you start:

First, everything you do with the API has to happen over SSL. In a world where we encourage people to use IMAP and POP over SSL it only makes sense that emails, which may be submitted to PhishTank, and URLs you check against the PhishTank database, are also sent encrypted with SSL.

Second, as an application developer you are required to register your application with us. That means you need an account. We don't ask a lot of questions, but we use the information you give us to create your authorization page on Phishtank, so users can verify your application and access their data in the PhishTank.

Third, as a courtesy, please credit PhishTank in your application. Read the attribution guidelines.

Questions about the API? Let us know.

Registering your application

You will need to register your application to receive an API key and shared secret. Please register your application here.

Connecting

All calls to the PhishTank API should be made using HTTP over SSL to port 443 of api.phishtank.com. Please use DNS rather than hard-coding an IP address into your application to assist us in distributing API load across multiple servers.

Request Format

The API uses standard REST for all requests. See Response Format for details on supported response formats.

Response Format

You may select a format for the responses you receive by passing the responseformat parameter.

Parameter	Value	Description
responseformat	xml, php	Format of API response. Using xml will return XML. Using php will return an array encoded using the PHP serialize() function.

Versioning

PhishTank fully supports versioning of the API. You should pass the version parameter with all requests to indicate the version of the API your application was built for.

Parameter	Value	Description
version	1	Currently the PhishTank API only has one version.

Generating Signatures

A signature is required as part of every request to the PhishTank API.

Generating a signature:

Begin by building a list of all parameters being passed to the API.
Sort this list in alphabetical order.
For each parameter, concatenate the name of the parameter and the value to a string.
Prepend your application's shared secret to this string.
Generate an MD5 hash (in hexidecimal representation) of this string.
Add a sig parameter to your request with a value of your generated MD5 hash.

Example PHP code:


 <?
    $shared_secret = 'siuFrOUpl8stOuCIethlbLaH0at4l1b84EpIABoa';
    $sig_string = '';
    $request_string = '/api/?version=1&action=example.only&foo=bar';
    list($parameter_string) = array_reverse(explode('?', $request_string));
    $parameters = explode('&', $parameter_string);
    foreach($parameters as $parameter) {
        list($key, $value) = explode('=', $parameter);
        $sig_string .= $key . $value;
    };
    $sig_string = $shared_secret . $sig_string;
    $hash = md5($sig_string);
    $request_string .= '&sig=' . $hash;
 ?>

Actions

misc.ping

The misc.ping action provides a method for verifying connectivity to the API server.

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<pong>437727</pong>
	</results>
</response>

auth.frob.request

The auth.frob.request action allows you to request a "frob," which is used in authenticating application access to PhishTank user accounts. Your application should store the returned frob and direct the user to the supplied authorization_url.

Input:

Parameter	Description
app_key	The unique access key assigned to your application.
callback_url	An optional URL to return a user to after allowing application access. Useful for web-based applications that are requesting account access. (Note: Remember to URL-encode the callback_url option if passing it as part of a GET request.)

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<frob>
			8c8636e26626bcfbf2bddaf88f850b1fb5e97c75f7e9207e3b6a37c...
		</frob>
		<authorization_url>
			http://www.phishtank.com/allow_api_access.php?frob=8c86...
		</authorization_url>
	</results>
</response>

auth.frob.status

This action will allow you to check on the status of a pending frob request. A frob will have a status of “pending” until it is accepted by the user, or expires after 14 days. If the frob was accepted, this function will give you the credentials needed to request tokens on the user's behalf. (Note: The access credentials provided by this function will only be returned once per frob, further requests for the frob will return an error. Ensure that you store this data within your application to avoid having to re-request authorization from the user.)

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
frob	A valid frob string issued by the auth.frob.request action.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<status>approved</status>
		<username>demouser</username>
		<apikey>
			19afa6b5093aa952c121a0dc9a3a1142035918ffd7fd8ab7...
		</apikey>
	</results>
</response>

auth.token.request

The auth.token.request action should be called at the beginning of an API session to request a token, which is required to authenticate further API commands.

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
api_key	A valid API key obtained through user authorization.
username	The username of the user associated with the API key.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<token>
			dc4ea104ef0531f3f77b0eed1db816d5d83d42125b48e6...
		</token>
	</results>
</response>

auth.token.status

Although any API request may result in an expired token response, developers may use the auth.token.status action to check the validity of currently held token, without performing any action against the associated account.
Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
api_key	A valid API key obtained through user authorization.
username	The username of the user associated with the API key.
token	The token to check the status of.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<valid>true</valid>
		<secondsleft>112</secondsleft>
	</results>
</response>

auth.token.revoke

Calling the auth.token.revoke action is required before ending an API session. Applications that do not properly revoke tokens may have their application keys banned to protect the security of end users.
Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
api_key	A valid API key obtained through user authorization.
username	The username of the user associated with the API key.
token	The token you would like to revoke.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<result>revoked</result>
	</results>
</response>

check.url

The check.url action may be used to check a single URL against the PhishTank database. (Note: Care should be taken when implementing this function to avoid taking action based solely on a positive in_database response, as innocent URLs may be in the PhishTank database but not verified as being involved in a phishing attack.)

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
token	A valid token for this API session.
url	The URL you wish to check.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<url0>
			<url>http://www.example.org/</url>
			<in_database>true</in_database>
			<phish_id>11728</phish_id>
			<phish_detail_page>
				http://www.phishtank.com/phish_detail.php?phish_id=11728
			</phish_detail_page>
			<verified>true</verified>
			<verified_at>2006-10-01T02:32:23+00:00</verified_at>
			<valid>true</valid>
			<submitted_at>2006-10-01T02:28:46+00:00</submitted_at>
		</url0>
	</results>
</response>

check.email

The check.email action allows an email to be scanned for known phishing URLs. All URLs found in email will be returned along with their status. URLs not found by the automated parser (such as URLs encoded in MIME parts) should not be trusted simply because they were not returned. A maximum of 25 URLs will be scanned, however the remainder of a message, after the last returned URL, may be resubmitted for further checking. (Note: Care should be taken when implementing this function to avoid taking action based solely on a positive in_database response, as innocent URLs may be in the PhishTank database but not verified as being involved in a phishing attack.)

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
token	A valid token for this API session.
email	The contents of the email you wish to check.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<url0>
			<url>http://www.example.com/</url>
			<in_database>false</in_database>
		</url0>
		<url1>
			<url>http://www.example.net/</url>
			<in_database>true</in_database>
			<phish_id>11727</phish_id>
			<phish_detail_page>
				http://www.phishtank.com/phish_detail.php?phish_id=11727
			</phish_detail_page>
			<verified>false</verified>
			<submitted_at>2006-10-01T02:28:06+00:00</submitted_at>
		</url1>
		<url2>
			<url>http://www.example.org/</url>
			<in_database>true</in_database>
			<phish_id>11728</phish_id>
			<phish_detail_page>
				http://www.phishtank.com/phish_detail.php?phish_id=11728
			</phish_detail_page>
			<verified>true</verified>
			<verified_at>2006-10-01T02:32:23+00:00</verified_at>
			<valid>true</valid>
			<submitted_at>2006-10-01T02:28:46+00:00</submitted_at>
		</url2>
	</results>
</response>

check.phish_id

New in API Version 2
The check.phish_id action may be used to check a single Phish ID against the PhishTank database. (Note: Care should be taken when implementing this function to avoid taking action based solely on a positive in_database response, as innocent URLs may be in the PhishTank database but not verified as being involved in a phishing attack.)

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
token	A valid token for this API session.
phish_id	The Phish ID you wish to check.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<url0>
			<url>http://www.example.org/</url>
			<in_database>true</in_database>
			<phish_id>11728</phish_id>
			<phish_detail_page>
				http://www.phishtank.com/phish_detail.php?phish_id=11728
			</phish_detail_page>
			<verified>true</verified>
			<verified_at>2006-10-01T02:32:23+00:00</verified_at>
			<valid>true</valid>
			<submitted_at>2006-10-01T02:28:46+00:00</submitted_at>
		</url0>
	</results>
</response>

submit.url

The submit.url action allows you to submit an individual URL as a suspected phish to PhishTank. To avoid unnecessary submissions, we encourage application developers to use check.url before submit.url is called. The submit.url action should not be used for the same URL more than once. If the submission is accepted (response = true), then the phish ID and the phish detail URL will be returned. A submission will not be accepted (response = false) if the URL is invalid (by format) or the submission already exists in the PhishTank database, among other possibilities.

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
token	A valid token for this API session.
username	The username of the user associated with the API key.
url	The url you wish to submit as a suspected phish.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<accepted>true</accepted>
		<phish_id>1234</phish_id>
	</results>
</response>

Note: If the parameter is returned false, then the response will not include phish_id and phish_detail.

submit.email

The submit.email action allows you to submit an individual email as a suspected phish to PhishTank. If the submission is accepted (response = true), then the phish ID and the phish detail URL will be returned. A submission will not be accepted (response = false) if the submission already exists in the PhishTank database, among other possibilities. Please use POST when submitting the email. Submit as much of the email as you possibly can, including headers and attachments. The submit will not fail if it's missing headers, for instance, but all information is useful when analyzing the submission.

Input:

Parameter	Description
app_key	The unique API access key assigned to your application.
token	A valid token for this API session.
username	The username of the user associated with the API key.
email	The email you wish to submit as a suspected phish.

Example Output:

<response>
	<meta>
	...
	</meta>
	<results>
		<accepted>true</accepted>
		<phish_id>1234</phish_id>
	</results>
</response>

Note: If the parameter is returned false, then the response will not include phish_id and phish_detail.