Phishing Initiative

API

We provide you the ability to interact automatically and programmatically with our platform through a REST API using the http protocol (POST or GET requests). The results of the queries are provided in JSON.

This API allows you, depending on your permissions, to automatically submit URLs into the system and/or retrieve data from the database, according to the different search criteria passed in the query.

Don't hesitate to contact us for any question or API usage assistance.

API key Add this in the header of your request

"Authorization": "Token <my key>"

Your account (and its associated API key) has the specific below rights or permissions:

URL bulk report
URL classification
Access to URL database
Look up an URL in the database
Search in websites’ source code

Documentation

You’ll find below entries and parameters to be used with our API. Some use cases written in python are described in our official library PyEUPI here.

Don’t hesitate to contact us if you’d like example scripts in other programming languages.

url

GET /api/v1/urls/

Retrieve a list of urls.

Response class

UrlResource {
id ( integer , optional )
url ( integer , optional )
tag ( integer , optional )
tag_label ( integer , optional )
first_seen ( integer , optional )
num_seen ( integer , optional )
country ( integer , optional )
last_tagged ( integer , optional )
domain ( integer , optional )
tld ( integer , optional )
ip_address ( integer , optional )
ip_range ( integer , optional )
asn ( integer , optional )
language ( integer , optional )
google_blacklist_update_time ( integer , optional )
}

Parameters

Parameter	Description	Parameter type	Data type
tag	URL status. 0 = unknown, 1 = phishing, 2 = clean.	query	integer
tag_label	URL status. Allowed values are "unknown", "phishing" and "clean"	query	string
url		query	string
url_exact		query	string
country		query	string
asn		query	integer
domain		query	string
redirector	'true' to only have redirector urls, 'false' to filter them	query	string
language		query	string
tld		query	string
ip_address		query	string
ip_range	IP range, using format xxx.xxx.xxx.xxx/xx	query	string
first_seen_before	Date in ISO format	query	date-time
first_seen_after	Date in ISO format	query	date-time
last_tagged_before	Date in ISO format	query	date-time
last_tagged_after	Date in ISO format	query	date-time
order_by	Sort by selected field. Prefix the field by a '-' to have a reverted sort Allowed values: "first_seen", "url", "-first_seen", "-url"	query	string
page	Page to fetch	query	integer
page_size	Element count per page. Maximum is 50.	query	integer

Return codes

HTTP return code	Reason
400	Invalid request
200	OK

GET /api/v1/urls/<int:item_id>/

Send back informations about the url.

Response class

Return codes

HTTP return code	Reason
400	Invalid request
200	OK

GET /api/v1/urls/lookup/

Look for an URL qualification

Response class

UrlListLookupResource {
url ( integer , optional )
tag ( integer , optional )
tag_label ( integer , optional )
}

Parameters

Parameter	Description	Parameter type	Data type
url	URL to query	query	string

GET /api/v1/urls/search/

Search for string in URL source codes Restrictions on allowed terms to search may apply to your search depending on your account.

Response class

UrlListSearchResource {
id ( integer , optional )
url ( integer , optional )
first_seen ( integer , optional )
tag ( integer , optional )
tag_label ( integer , optional )
}

Parameters

Parameter	Description	Parameter type	Data type
url	Regular expression to search in the url string	query	string
content	Term to search in the page source code	query	string
tag_label	URL status. Allowed values are "unknown", "phishing" and "clean"	query	string
tag	URL status. 0 = unknown, 1 = phishing, 2 = clean.	query	integer
first_seen_after	URL first submission date from which to search, in ISO 8601	query	string
first_seen_before	URL first submission date until which to search, in ISO 8601	query	string
page	Page to fetch	query	integer
page_size	Element count per page. Maximum is 50.	query	integer

submission

GET /api/v1/submissions/

Retrieve a list of submissions.

Response class

SubmissionResource {
id ( integer , optional )
time ( integer , optional )
submitter_comment ( integer , optional )
submitter_notify ( integer , optional )
url ( integer , optional )
}

Parameters

Parameter	Description	Parameter type	Data type
submitted_before	Date in ISO format	query	date-time
submitted_after	Date in ISO format	query	date-time
order_by	Sort by selected field. Prefix the field by a '-' to have a reverted sort Allowed values: "time", "first_seen", "url", "-time", "-first_seen", "-url"	query	string
tag	URL status. 0 = unknown, 1 = phishing, 2 = clean.	query	integer
tag_label	URL status. Allowed values are "unknown", "phishing" and "clean"	query	string
url		query	string
url_exact		query	string
country		query	string
asn		query	integer
domain		query	string
redirector	'true' to only have redirector urls, 'false' to filter them	query	string
language		query	string
tld		query	string
ip_address		query	string
ip_range	IP range, using format xxx.xxx.xxx.xxx/xx	query	string
first_seen_before	Date in ISO format	query	date-time
first_seen_after	Date in ISO format	query	date-time
last_tagged_before	Date in ISO format	query	date-time
last_tagged_after	Date in ISO format	query	date-time
page	Page to fetch	query	integer
page_size	Element count per page. Maximum is 50.	query	integer

Return codes

HTTP return code	Reason
400	Invalid request
200	OK

POST /api/v1/submissions/

Create one or several submissions.

Response class

Parameters

Parameter	Description	Parameter type	Data type
body	dictionary or list of dictionaries of entries to add. Fields: comment: string notify: boolean tag: integer (0=inconnu, 1=phishing, 2=clean) url: string	body	string

Parameter

Description

Parameter type

Data type

body

dictionary or list of dictionaries of entries to add. Fields:

comment: string
notify: boolean
tag: integer (0=inconnu, 1=phishing, 2=clean)
url: string

body

string

Return codes

HTTP return code	Reason
400	Invalid request
201	Created

GET /api/v1/submissions/<int:item_id>/

Send back informations about the submission.

Response class

Return codes

HTTP return code	Reason
400	Invalid request
200	OK