API Documentation

Introduction

BotSmasher API allows site owners a means of automatically checking IP addresses, email addresses, and names to determine if those pieces of information match the information of alleged bots or otherwise fraudulent users of web systems. This can be used to protect against comment spam, forum spam, fraudulent registrations and other illegitimate actions - particularly in cases where forms are in use.

Common Use Cases for the BotSmasher API

Checking For Bots or other Fraudulent usage

BotSmasher can be used at the time of form submission to check whether the email address or name submitted are fraudulent or whether the IP address of the submitter is associated with fraudulent submissions. In this scenario we check our database, which is an aggregate of our own data as well as other, similar services, to see if any of these pieces of information have been found.

Submitting Bots (we call them bad guys)

API Users can also submit IPs, names, and emails to be included into our database. Note, however, that your submission will only cause that information to be 'true' for you. In order to be included in our listings, those same pieces of information must come from peer submissions as well. This helps thwart abusive or overzealous submissions while giving you real-time ability to block abuse. In other words, you can use BotSmasher as your own personal blacklist.

"Clearing" Bad Guys

API users can also clear IP addresses, names, and emails. The intended purpose for this is to act as an "Undo" for accidentally submitting new bad guys.

Using the API

Registration Required

All requests against the API must come from registered users with a valid API key. To obtain a key, register at http://www.botsmasher.com/register.php.

Steps to Register

Limitations

Requirements

Response format

All responses come in the form of JSON. The following is a sample response from BotSmasher showing all possible values.

{
    "response": {
        "summary": {
            "requesttype": "check|submit|clear",
            "code": "failure|success",
            "badguys": "true|false",
            "description": "foo"
        },
        "request": {
            "ip": {
                "submitted": "127.0.0.1",
                "found": "true|false",
                "count": "123",
                "lastseen": "0000-00-00 00:00:00",
                "flaggedbyyou": "true|false"
            },
            "name": {
                "submitted": "me@example.com",
                "found": "true|false",
                "count": "789",
                "lastseen": "0000-00-00 00:00:00",
                "flaggedbyyou": "true|false"
            },
            "email": {
                "submitted": "joe schmoe",
                "found": "true|false",
                "count": "456",
                "lastseen": "0000-00-00 00:00:00",
                "flaggedbyyou": "true|false"
            }
        }
    }
}

Success Responses

A success response is returned whenever you submit a well-formed request. The information returned will include whether we have a match for your query and, for each match, how many times it was found.

Failure Responses

A failure response is returned whenever some condition exists which causes the process to halt prematurely.

Response Explanation
Missing Parameter A required parameter was missing. All requests must contain the 'key' parameter and one or more of the following: 'ip', 'name', or 'email' (up to and including all of them)
Invalid User This message is returned whenever the API key supplied is either not found or has been banned.
Over Limit This message is returned whenever you have exceeded the total # of requests you're allowed in a day. If you repeatedly get this error, contact us to upgrade you.
Unknown Error This message is returned whenever the API is unable to return any data at all.
Check Example

This example would check email, ip, and name

https://www.botsmasher.com/api/?action=check&key=YOURAPIKEYHERE&email=me@example.com&ip=127.0.0.1&name=filthySpammer

Submissions

The BotSmasher API also accepts submissions for new bots. This is performed using the 'submit' value in the action parameter.

Submission Example

This example would submit email, ip, and name

https://www.botsmasher.com/api/?action=submit&key=YOURAPIKEYHERE&email=me@example.com&ip=127.0.0.1&name=filthySpammer

Submission Responses

Submission responses will come in the same format as 'check' responses, with obvious differences being that the relevant values for a 'check' are missing. Here's a sample:

{
    "response": {
        "summary": {
            "requesttype": "submit",
            "code": "failure|success",
            "description": "foo"
        }
    }
}

What happens when you submit a new bot

As soon as you submit a new bot, it will be added to our database. Future queries against the API will return that fact in the results. That does not, however, mean that all other users will see this. We must see multiple other users submitting the same information before we flag that info for all.

Note: Abuse - or even suspected abuse - of this feature will cause immediate and permandent revokation of your API access.

"Clearing"

The clearing action essentially un-submits a previous submission you've made. For instance, if you submit an email address and later decide that you don't want to block that email, you can clear it.

Note: This will only clear your submission. For instance, if that same email has been added to the main BotSmasher database, it will still return 'true' for bad guys.

Clearing Example

This example would clear an email

https://www.botsmasher.com/api/?action=submit&key=YOURAPIKEYHERE&email=me@example.com

Clearing Responses

Clearing responses will come in the same format as 'submit' responses. Here's a sample:

{
    "response": {
        "summary": {
            "requesttype": "clear",
            "code": "failure|success",
            "description": "foo"
        }
    }
}

Terms of Use

The following Terms of use apply both for the use of the BotSmasher API and this website as a whole.

Acceptance of Terms

The services that BotSmasher provides to you are subject to the following Terms of Use. The most current version of these terms can always be reviewed by following the "Terms of Use" hypertext link located at the bottom of all pages on this site.

Rights To Change Terms

BotSmasher may add, modify, change, alter, or remove any part of these Terms of Use at any time, without any notice to you. Any changes to these Terms of Use or any terms posted on this site apply immediately upon posting. By continuing to use this site after any changes are posted, you are indicating your acceptance of those changes.

Warranty

BOTSMASHER AND/OR ITS RESPECTIVE SUPPLIERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE INFORMATION CONTAINED IN THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED AS PART OF THE SERVICES FOR ANY PURPOSE. ALL SUCH DOCUMENTS AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. BOTSMASHER AND/OR ITS RESPECTIVE SUPPLIERS HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, INCLUDING ALL WARRANTIES AND CONDITIONS OF MERCHANTABILITY, WHETHER EXPRESS, IMPLIED OR STATUTORY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL BotSmasher AND/OR ITS RESPECTIVE SUPPLIERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION AVAILABLE FROM THE SERVICES.

THE DOCUMENTS AND RELATED GRAPHICS PUBLISHED ON THE SITE COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN. BOTSMASHER AND/OR ITS RESPECTIVE SUPPLIERS MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED HEREIN AT ANY TIME.

Personal and Non-Commercial Use Limitation

Unless otherwise specified, you may not modify, copy, distribute, transmit, display, perform, reproduce, publish, license, create derivative works from, transfer, or sell any information, software, products or services obtained from the Services.

Use of Copyrighted Materials and Logos

You may not reproduce, copy or redistribute the design or layout of any BotSmasher Web page, individual elements of the Web site design, or BotSmasher logos without the express written permission of BotSmasher. Copyright, trademark, and other proprietary notices may not be removed.

Ownership/Attribution

BotSmasher retains all ownership and other rights in our RSS Content. You must provide attribution to the appropriate BotSmasher website in connection with your use of our RSS feeds. If you provide this attribution using a graphic, you must use the appropriate BotSmasher website's logo that we have incorporated into the RSS feed.

Privacy Policy

BotSmasher maintains a detailed privacy policy. The most current version of this site's privacy policy can always be reviewed by following the "Privacy Policy" hypertext link located at the bottom of all pages on this site. No Warranties; Limitations of Liability

Although BotSmasher attempts to provide useful and timely information, we do not guarantee that the information is accurate, current, or suitable for any particular purpose. We assume no obligation to update or continue to post information or updates to said information.

While you visit our site, BotSmasher does not guarantee that access to this site will be uninterrupted, that this site will be free of viruses or that this site cannot be tampered with by third parties.

BotSmasher does not guarantee that information sent to this site will not be obtained, reviewed, or tampered with by third parties.

This site and the information on this site are provided "as is" with no warranties of any kind whatsoever, either express or implied, including, but not limited to, any warranties of title or accuracy or any implied warranties of merchantability or fitness for a particular purpose. Links to Third Party Sites

Some of the links in the BotSmasher Web site will let you leave this site. The linked sites are not under the control of BotSmasher and we are not responsible for the contents of any linked site, or any changes or updates to such sites. BotSmasher is not responsible for Webcasting or any other form of transmission received from any linked site. BotSmasher provides these links to you only as a matter of convenience, and the inclusion of any link does not imply endorsement by BotSmasher of the site.

Use of This Site and the Information Is At the User's Sole Risk

In no event will BotSmasher be liable for any damages whatsoever arising out of or related to this site, any site operated by a third party or any information contained in this site or any other site, including but not limited to direct, indirect, incidental, special, consequential or punitive damages, whether under a contract, tort or any other theory of liability, even if BotSmasher is aware of the possibility of such damages.

Transmitted Material Through the Internet

Transmissions are never completely private or secure. By visiting our site, you understand and accept that any message or information you send to this site may be read of intercepted by others unless there is a special notice that a particular message is encrypted. Sending a message or a resume to BotSmasher does not cause BotSmasher to have any special responsibility to you.

Agreement to Conduct Rules

You agree to abide by the BotSmasher User Conduct Rules, including but not limited to, agreeing not to use this site for any unlawful purpose:

By posting information in or otherwise using any communications service, message board, or other interactive service that may be available to you on or through the BotSmasher Site, you agree that you will not upload, post, or otherwise distribute or facilitate distribution of any materials, including text, communications, software, images, sounds, data, or other information (hereafter "Content") that:

is unlawful, threatening, abusive, harassing, defamatory, libelous, deceptive, fraudulent, invasive of another's privacy or publicity rights, tortious, or otherwise violates the BotSmasher rules or policies;

infringes on any patent, trademark, trade secret, copyright, right of publicity, or other proprietary right of any party;

constitutes unauthorized or unsolicited advertising, chain letters, any other form of unauthorized solicitation, or any form of lottery or gambling;

contains software viruses or any other computer code, files, or programs that are designed or intended to disrupt, damage, or limit the functioning of any software, hardware, or telecommunications equipment or to damage or obtain unauthorized access to any data or other information of any third party; or

contains information, material, or pictures of any person who is not both older than eighteen (18) years old and over the age of majority in such person's state, providence, or country of residence.

contains pornography or obscene material. BotSmasher has sole discretion as to what constitutes obscenity.

You also agree that you will not harvest or collect information about the users or members of this Site or use such information for the purpose of transmitting or facilitating transmission of unsolicited bulk electronic e-mail or communications. BotSmasher generally does not pre-screen, monitor, or edit the content posted by users of communications services, chat rooms, message boards, or other interactive services that may be available on or through this site. However, we have the right at our sole discretion to remove any content that, in our judgment, does not comply with these User Conduct Rules or is otherwise harmful, objectionable, or inaccurate. BotSmasher is not responsible for any failure or delay in removing such content.

Termination of Access

BotSmasher reserves the right, in its sole discretion, to terminate your access to all or part of this Site, with or without notice, for any reason, including, without limitation, if BotSmasher believes that you have violated or acted inconsistently with the letter or spirit of these Terms of Use. This includes our right to terminate a user's access to and/ or ability to post materials to the Site. You acknowledge that BotSmasher shall not be liable to you or any third party for any termination of your access to this Site.

Applicable Laws

This Web site (excluding linked sites) is controlled by Karl Groves from our office in the United States of America. It can be accessed from all 50 states, as well as from other countries around the world. As each of these places has laws that may differ from those of the State of Maryland, by accessing this Web site, both you and Karl Groves agree that the statutes and laws of the State of Maryland, without regard to the conflicts of law principles thereof, will apply to all matters relating to use of this Web site. Those who choose to access this site from other locations do so on their own initiative and are responsible for compliance with local laws.

International Use

BotSmasher makes no representation that materials on this Site are appropriate or available for use in any particular locations, and accessing them from territories where their contents are illegal is prohibited. Those who choose to access this Site from any location do so on their own initiative, at their own risk, and are responsible for compliance with local laws. If you use this Site in a jurisdiction that prohibits or restricts such use, your use will be subject to, without limitation, any other provision of the Terms of Use, and we shall not have any liability with respect to such use.

Copyright Policy

Copyright © 2013 BotSmasher. All Rights Reserved. For More Information

If you have any comments, concerns or questions regarding our site's Terms of Use policy, please contact us.

Spam Policy

BotSmasher has an absolute zero tolerance for spamming of any kind. Any member who sends unsolicited emails or places posts on usenet, internet forums or discussion lists on which such messages are considered against that site's terms will be immediately and irrevocably banned from our site. If you believe you have received spam concerning BotSmasher, please contact us.