Introduction

You can use additional variables to filter and sort cPanel API 2 output.


  • You can test cPanel API 2 functions in cPanel's API Shell interface (Home >> Advanced >> API Shell). Click Show Sort/Filter/Paginate Options to display the additional text boxes.
  • cPanel & WHM version 11.28 introduced this functionality.

Filter output

cPanel API 2 filters use four basic variables:

VariableTypeDescriptionPossible values
api2_filter BooleanWhether to enable filtering.
  • 1 — Enable filtering.
  • 0 — Disable filtering.
api2_filter_columnstringThe return to match against.The name of one of the function's returns.
api2_filter_termstringThe value to match.An integer or string value.
api2_filter_typestring

The match type.

  • If the api2_filter_term value is an integer, use a numeric operator.
  • If the api2_filter_term value is a string, use a string operator.

This variable defaults to contains.

Numeric operators:

  • eq — The column equals to the match value.
  • lt — The column is less than the match value. This match type cannot handle unlimited values.

  • lt_handle_unlimited — The column is less than the match value. This match type can handle unlimited values.

  • gt — The column is greater than the match value. This match type cannot handle unlimited values.
  • gt_handle_unlimited — The column is greater than the match value. This match type can handle unlimited values.
  • ne — The column does not equal the match value.

    We introduced the ne operator in cPanel & WHM version 56.


String operators:

  • contains — The column contains the match value's string. Not case-sensitive.

  • begins The column begins with the match value's string. Not case-sensitive.

  • ends The column ends with the match value's string. Not case-sensitive.

  • matches The column matches the value as a regular expression.

Other operators:

  • defined — The column contains a value.
  • undefined — The column does not contain a value.

We introduced the defined and undefined operators in cPanel & WHM version 58.


Examples

The following example function callsexecute the Email::listpopswithdisk  function andfilter the results to return email accounts with disk quotas under 350 Megabytes (MB).



/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&domain=example.com&api2_filter=1&api2_filter_column=diskquota&api2_filter_term=350&api2_filter_type=lt_handle_unlimited



$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all example.com email addresses with quotas under 350MB.
$list_email_address_info = $cpanel->api2(
    'Email', 'listpopswithdisk', 
    array(
        'domain'                 => 'example.com',
        'api2_filter'            => '1',
        'api2_filter_column'     => 'diskquota',
        'api2_filter_term'       => '350',
        'api2_filter_type'       => 'lt_handle_unlimited',
    ) 
);



my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all example.com email addresses with quotas under 350MB.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    { 
        'domain'                 => 'example.com',
        'api2_filter'            => '1',
        'api2_filter_column'     => 'diskquota',
        'api2_filter_term'       => '350',
        'api2_filter_type'       => 'lt_handle_unlimited',
    }
);



<?cp Email::listpopswithdisk (
          [strong]%[/strong] - %[br],
          email,
          diskquota
          )
          domain="example.com",
          api2_filter="1",
          api2_filter_column="diskquota",
          api2_filter_term="350",
          api2_filter_type="lt_handle_unlimited",
?> 



uapi --user=username Email listpopswithdisk domain=example.com api2_filter=1 api2_filter_column=diskquota api2_filter_term=350 api2_filter_type=lt_handle_unlimited




{
  "cpanelresult": {
    "apiversion": 2,
    "records_before_filter": 6,
    "func": "listpopswithdisk",
    "data": [
      {
        "txtdiskquota": "unlimited",
        "diskquota": "unlimited",
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "None",
        "_diskused": "483",
        "login": "user1@example.com",
        "email": "user1@example.com",
        "domain": "example.com",
        "user": "user1",
        "humandiskused": "483\u00a0bytes",
        "diskusedpercent20": 0,
        "_diskquota": 0
      },
      {
        "txtdiskquota": "unlimited",
        "diskquota": "unlimited",
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "None",
        "_diskused": "0",
        "login": "user2@example.com",
        "email": "user2@example.com",
        "domain": "example.com",
        "user": "user2",
        "humandiskused": "None",
        "diskusedpercent20": 0,
        "_diskquota": 0
      },
      {
        "txtdiskquota": 325,
        "diskquota": 325,
        "diskusedpercent": 0,
        "mtime": 1414015408,
        "diskused": 0,
        "humandiskquota": "325\u00a0MB",
        "_diskused": "0",
        "login": "user3@example.com",
        "email": "user3@example.com",
        "domain": "example.com",
        "user": "user3",
        "humandiskused": "None",
        "diskusedpercent20": 0,
        "_diskquota": "340787200"
      },
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
} 



Use multiple filters

To use multiple filters on a single cPanel API 2 call, append an underscore (_) and a number to the end of each filter variable.

For example, use the following variables to pass two sets of filter information:

  • Pass the first set of filter information to the api2_filter_type_0api_filter_column_0, and api_filter_term_0 variables.
  • Pass the second set of filter information to the  api2_filter_type_1 api_filter_column_1 , and  api_filter_term_1 variables.

Do not include more than one api2_filter boolean variable. 

For example, the following examples filter the Email::listpopswithdisk function's output to email addresses that contain com with a quota that is greater than 100.



/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&domain=example.comapi2_filter=1&api2_filter_type_0=gt_handle_unlimited&api2_filter_column_0=quota&api2_filter_term_0=100&api2_filter_type_1=contains&api2_filter_column_1=email&api2_filter_term_1=com



$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List all .com email addresses with quotas over 100MB.
$list_email_address_info = $cpanel->api2(
    'Email', 'listpopswithdisk', 
    array(
        'api2_filter'            => '1',
        'api2_filter_column_0'   => 'diskquota',
        'api2_filter_term_0'     => '100',
        'api2_filter_type_0'     => 'gt_handle_unlimited',
        'api2_filter_column_1'   => 'email',
        'api2_filter_term_1'     => 'com',
        'api2_filter_type_1'     => 'contains',
    ) 
);



my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List all .com email addresses with quotas over 100MB.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    { 
        'api2_filter'            => '1',
        'api2_filter_column_0'   => 'diskquota',
        'api2_filter_term_0'     => '100',
        'api2_filter_type_0'     => 'gt_handle_unlimited',
        'api2_filter_column_1'   => 'email',
        'api2_filter_term_1'     => 'com',
        'api2_filter_type_1'     => 'contains',
    }
);



cpapi2 --user=username Email listpopswithdisk domain=example.com api2_filter=1 api2_filter_type_0=gt_handle_unlimited api2_filter_column_0=quota api2_filter_term_0=100 api2_filter_type_1=contains api2_filter_column_1=email api2_filter_term_1=com




<?cp Email::listpopswithdisk (
          [strong]%[/strong] - %[br],
          email,
          diskquota
          )
          domain="example.com",
          api2_filter="1",
          api2_filter_column_0="diskquota",
          api2_filter_term_0="100",
          api2_filter_type_0="gt_handle_unlimited",
          api2_filter_column_1="email",
          api2_filter_term_1="com",
          api2_filter_type_1="contains",
?> 


Sort output

cPanel API 2 sorting uses four basic variables:

VariableTypeDescriptionPossible values
api2_sort BooleanWhether to enable sorting.
  • 1 — Enable sorting.
  • 0 — Disable sorting.
api2_sort_columnstringThe output parameter to sort by.The name of one of the function's parameters.
api2_sort_methodstring

The type of sorting to use.

This variable defaults to lexicographic.

You must set this parameter whenever you sort numeric values, or the function will fail. 


  • ipv4 — Sort output by the numeric value of each octet in an IPv4 address.
  • numeric — Sort output in numeric order, with 0 as the lowest number.
  • numeric_zero_as_max — Sort output in numeric order, with 0 as the highest number.
  • lexicographic — Sort output in alphabetical order.
api2_sort_reverseBoolean

Whether to sort data in reverse order.

  • 1 — Sort in reverse order.
  • 0 — Do not sort in reverse order.

Examples

The following example function callsexecute the Stats::lastvisitors function and use the ipv4 method to sort the ip parameter's values in reverse order.



/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Stats&cpanel_jsonapi_func=lastvisitors&domain=example.com&api2_sort=1&api2_sort_column=ip&api2_sort_method=ipv4&api2_sort_reverse=1



$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List recent visitors, sorted by IP address in reverse order.
$sorted_visitors = $cpanel->api2(
    'Stats', 'lastvisitors', 
    array(
        'domain'                 => 'example.com',
        'api2_sort'              => '1',
        'api2_sort_column'       => 'ip',
        'api2_sort_method'       => 'ipv4',
        'api2_sort_reverse'      => '1',
    ) 
);



my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List recent visitors, sorted by IP address in reverse order.
my $list_email_addresses = $cpliveapi->api2(
    'Email', 'listpopswithdisk',
    { 
        'domain'                 => 'example.com',
        'api2_sort'              => '1',
        'api2_sort_column'       => 'ip',
        'api2_sort_method'       => 'ipv4',
        'api2_sort_reverse'      => '1',
    }
);



cpapi2 --user=username Stats lastvisitors domain=example.com api2_sort=1 api2_sort_column=ip api2_sort_method=ipv4 api2_sort_reverse=1




<?cp Email::listpopswithdisk (
          %[br],
          ip
          )
          domain="example.com",
          api2_sort="1",
          api2_sort_column="ip",
          api2_sort_method="ipv4",
          api2_sort_reverse="1",
?>