Child pages
  • WHM API 1 - Return Data
Skip to end of metadata
Go to start of metadata

 

Introduction

WHM API 1 outputs data in either JSON or XML format. The output format depends on the options that you choose when you call the function.

Basic return data  

Both JSON and XML output return data as hashes or arrays of hashes. All WHM API 1 function output follows the following basic structure:

  • A top-level hash contains the data and metadata hashes. In XML output, <result> tags wrap the top-level hash of output.
    • The data hash contains the function's output parameters.
    • The  metadata hash contains the function's metadata parameters.

Metadata

Important:

  • WHM API 1 function documentation does not include metadata parameters in the table of return parameter information. 
  • WHM API 1 calls via the command line do not return the metadata that other methods return if they experience errors that prevent a successful function run. To check for errors in code that calls WHM API 1 functions via the command line, validate the command line return for a nonzero exit code instead.

The metadata hash includes the following output parameters:

Metadata parameterTypeDescriptionPossible valuesExample
versionintegerThe WHM API version.For WHM API 1 functions, this value is always 1.1
reasonstringA message of success, or a reason for failure.
  • OK
  • An error message.
OK
resultBooleanWhether the function succeeded.
  • 1 — Success.
  • 0 — Failure.
1
commandstringThe WHM API 1 function name.Any WHM API 1 function's name.listaccts

Note:

If the function returns a hash with a single key whose value is an array, the metadata will include the payload_is_literal output parameter with a value of 1. You will only receive this parameter when you call WHM API's rename_mysql_database or rename_mysql_user functions, or when you call certain UAPI functions via WHM API.

Example

The accountsummary function's output is typical of WHM API 1 output:

{
  "data": {
    "acct": [
      {
        "maxaddons": "unlimited",
        "ip": "10.215.214.95",
        "min_defer_fail_to_trigger_protection": "5",
        "legacy_backup": 0,
        "diskused": "14M",
        "maxftp": "unlimited",
        "startdate": "13 May 22 16:03",
        "max_defer_fail_percentage": "unlimited",
        "disklimit": "unlimited",
        "is_locked": 0,
        "suspendtime": null,
        "email": "user@example.com",
        "domain": "example.com",
        "unix_startdate": 1369256589,
        "user": "user",
        "plan": "extensions_user_user",
        "shell": "/bin/bash",
        "maxpop": "unlimited",
        "backup": 0,
        "theme": "paper_lantern",
        "owner": "root",
        "max_email_per_hour": "unlimited",
        "ipv6": [
           
        ],
        "suspendreason": "not suspended",
        "maxlst": "unlimited",
        "suspended": 0,
        "maxsql": "unlimited",
        "maxparked": "unlimited",
        "partition": "home",
        "maxsub": "unlimited"
      }
    ]
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": 1,
    "command": "accountsummary"
  }
}

Remember:

cPanel & WHM version 66 deprecated XML output. 

<result>
    <data>
        <acct>
            <maxaddons>unlimited</maxaddons>
            <ip>10.215.214.95</ip>
            <min_defer_fail_to_trigger_protection>5</min_defer_fail_to_trigger_protection>
            <legacy_backup>0</legacy_backup>
            <diskused>14M</diskused>
            <maxftp>unlimited</maxftp>
            <startdate>13 May 22 16:03</startdate>
            <max_defer_fail_percentage>unlimited</max_defer_fail_percentage>
            <disklimit>unlimited</disklimit>
            <is_locked>0</is_locked>
            <suspendtime/>
            <email>user@example.com</email>
            <domain>example.com</domain>
            <unix_startdate>1369256589</unix_startdate>
            <user>user</user>
            <plan>extensions_user_user</plan>
            <shell>/bin/bash</shell>
            <maxpop>unlimited</maxpop>
            <backup>0</backup>
            <theme>paper_lantern</theme>
            <owner>root</owner>
            <max_email_per_hour>unlimited</max_email_per_hour>
            <suspendreason>not suspended</suspendreason>
            <maxlst>unlimited</maxlst>
            <suspended>0</suspended>
            <maxsql>unlimited</maxsql>
            <maxparked>unlimited</maxparked>
            <partition>home</partition>
            <maxsub>unlimited</maxsub>
        </acct>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>accountsummary</command>
    </metadata>
</result>