====== Abuse Manager Pro API ======

<color #ffc90e>__The API has been introduced in v3.4. Therefore, it is only available & supported on v3.4 and above.__</color>

This page explains the ways to interact with the Abuse Manager Pro API.

===== Generating your API ID For Authentication =====

  * Login to your WHMCS installation (WHMCS Admin)
  * Go to Setup > Staff Management > Manage API Credentials
  * Click on API roles, click on Create API Role button, DO NOT give it any actions, press save
  * Click on API credentials, click on Generate New API Credential button, select your admin user, select the API role created previously
  * Copy the identifier only - we do not need the secret
  * This identifier will be the API_ID that needs to be passed in the header of your call to authenticate with the API

<code php>'API_ID: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'</code>
===== API URL / Endpoint =====

The Abuse Manager Pro API can be consumed from:
<code>https://URL-TO-YOUR-WHMCS/modules/addons/abusemanagerpro/includes/api.php</code>

===== Available Actions/Functions =====

^ Action            ^ Description          ^
| [[amp_api#Create|Create]]            | Creates an abuse report automatically        |




----



===== Actions Index =====

==== Create ====

^ Action    | create          |
^ HTTP Method    | POST |
^ Authentication Required    | Yes          |
^ Variables    | <WRAP>
| service_id | required - this is the WHMCS ID of the service that the abuse report will be created for |
| category | required - this is the category of abuse - can be any value e.g. 'Spam' or 'High I/O' or 'Hacking Attempts' etc. |
| service_ip | optional - if not passed, the main dedicated IP of the service will be used - if service doesn't have a dedicated IP it will default to (No Dedicated IP) |
| suspend_method | optional - defaults to nosuspend - available options are 'nosuspend', 'immediate', and 'timelimit' |
| allow_unsuspend | optional - defaults to false - if you want to give the customer the option to self unsuspend set to true |
| additional_info | optional - This is the additional information field - this is visible to the customer |
| admin_notes | optional - This is the admin notes field - this is only visible to the admins |
</WRAP>|
^ Success JSON Output    | <code javascript>"{"status":"success","report_id":92}"</code>          |
^ Error JSON Output    | <code javascript>"{"status":"error","error_code":"AMP009","error_description":"Missing required parameters."}"</code>          |



----

===== Error Codes =====

^ Code            ^ Description          ^
| AMP001            | Unauthorized - make sure you are passing a valid API_ID in the header        |
| AMP002            | Missing or Invalid Action - make sure you are passing a valid action        |
| AMP003            | Missing required parameters - make sure you are passing the required parameters for the action        |

----
===== Example PHP Curl Script =====

The example below shows how to create an abuse report programmatically using the API service.

<file php example-php-curl.php>
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://URL-TO-YOUR-WHMCS/modules/addons/abusemanagerpro/includes/api.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    http_build_query(
        array(
            'action' => 'create',                                           // required - 'create' is to be used to create an abuse report

            'service_id' => '1',                                            // required - this is the WHMCS ID of the service that the abuse report will be created for
            'category' => 'Spam',                                           // required - this is the category of abuse - can be any value e.g. 'Spam' or 'High I/O' or 'Hacking Attempts' etc.
            
            'service_ip' => '1.2.3.4',                                      // optional - if not passed, the main dedicated IP of the service will be used - if service doesn't have a dedicated IP it will default to (No Dedicated IP)
            'suspend_method' => 'suspend',                                  // optional - defaults to nosuspend - available options are 'nosuspend', 'immediate', and 'timelimit'
            'allow_unsuspend' => true,                                      // optional - defaults to false - if you want to give the customer the option to self unsuspend set to true
            'additional_info' => 'This is the additional info field',       // optional - This is the additional information field - this is visible to the customer
            'admin_notes' => 'This is the admin notes field',               // optional - This is the admin notes field - this is only visible to the admins
        )
    )
);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'API_ID: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',                             // required - this header is required for authentication
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);

?>
</file>