APIBAN API Reference

REST API for sharing IP addresses sending unwanted SIP traffic

APIBAN helps prevent unwanted SIP traffic by identifying addresses of known bad actors before they attack your system. Bad actors are collected through globally deployed honeypots and curated by LOD/APIBAN.

horrible graphical representation of a honeypot in action

Block/Identify Traffic

This API allows you to integrate and interact with APIBAN data.

The data is provided in standard JSON responses and use HTTP Status Codes to help determine results.

NOTE If you are looking to protect your PBX or SIP server without programming, you should use the APIBAN client to automatically block traffic.


To use the APIBAN API, you will need to first obtain an API KEY. The API KEY is used for all API requests.

NOTE API KEYs are limited to one per user/email. If your organization needs multiple keys, please contact LOD.

The API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

Base URL


For integration examples for Kamailio, Homer, and more, please visit our Github repo.


Authentication with the API is made through the API KEY. If having trouble receiving an API KEY or if an API KEY needs to be replaced, please contact our support team.

Requests to the API are limited to 11 requests in 2 minutes.

Authentication Errors

HTTP 403{"ipaddress":"none", "ID":"unauthorized"}

HTTP 429{"ipaddress":"rate limit exceeded", "ID":"unauthorized"}


The API will return non-2xx http status codes and descriptive responses when able to do so. Examples include:

Core Resources


Banned is an object returning banned ip addresses in batches of 250. An ID is provided to use when pulling the next batch. If no ID is passed, the first 250 addresses (oldest first) will be provided.


GET https://apiban.org/api/[APIKEY]/banned

GET https://apiban.org/api/[APIKEY]/banned/[ID]

Example responses

HTTP 200 {"ipaddress":["",""], "ID":"9876543210"}

HTTP 400 {"ipaddress":["no new bans"], "ID":"none"}


Check is an object returning the status of a specific ip address. A 2xx indicates a ban and a 404 indicates the ipaddress is not banned.


GET https://apiban.org/api/[APIKEY]/check/[IPADDRESS]

Example responses

HTTP 200 {"ipaddress":"blocked", "ID":"9876543210"}

HTTP 404 {"ipaddress":"ok", "ID":"0"}


IPsets (lists of IPs) can be used by many firewalls, iptables, and appliances (such as pfsense, opnsense, etc.) to block unwanted traffic to your network.


List returns a plain text ipset with control id, record count, and IPs (listed in age order from oldest to most recent).


GET https://apiban.org/ipset/[APIKEY]/list

NOTE: This uses the ipset resource vs api.

Example responses

HTTP 200 (plain text document)

403 unauthorized {"ipaddress":"none", "ID":"unauthorized"}

429 rate limit exceeded {"ipaddress":"rate limit exceeded", "ID":"unauthorized"}

503 server error {"error":"gK10", "description":"an internal error occurred"}

License / Warranty

The APIBAN API is provided in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

apiban-iptables-client is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

apiban-iptables-client is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Getting Help

Help is provided by LOD and an APIBAN room is available on the LOD Matrix homeserver. The client software is provided under the GPLv2 license.

NOTE The best method to get assistance is in the APIBAN Matrix room: #apiban:matrix.lod.com.

Open Source

APIBAN (LOD, and Palner) greatly values and supports open source software.

There are many ways you can participate in open source software, including:

Open Source Used by APIBAN

Open Source Made by APIBAN

© 2019-2021. LOD Communications, Inc.