UAPI Functions - UserManager::lookup_user

https://hostname.example.com:2083/cpsess##########/execute/UserManager/lookup_user?guid=EXAMPLE1%3AEXAMPLE.COM%3A564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation.

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List a Subaccount.
$UserManager = $cpanel->uapi(
    'UserManager', 'lookup_user',
	array(
		'guid'	=>	'EXAMPLE1%3AEXAMPLE.COM%3A564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37'
	)
);

Note:

For more information, read our Guide to the LiveAPI System.

LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# List a Subaccount.
my $UserManager = $cpliveapi->uapi(
    'UserManager', 'lookup_user',
	{	
	'guid'	=>	'EXAMPLE1%3AEXAMPLE.COM%3A564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37'
	}
);

Note:

For more information, read our Guide to the LiveAPI System.

Command Line

uapi --user=username UserManager lookup_user guid=EXAMPLE1%3AEXAMPLE.COM%3A564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37

Notes:

You must URI-encode values.
username represents your account-level username.
For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command.
If you run CloudLinux™, you must use the full path of the uapi command:
```
/usr/local/cpanel/bin/uapi
```

Output (JSON)

{  
   "data":{  
      "parent_type":null,
      "has_expired_invite":0,
      "type":"sub",
      "avatar_url":null,
      "can_set_quota":0,
      "dismissed":0,
      "guid":"EXAMPLE1:EXAMPLE.COM:577D1256:877AF09F728A672078D0733ADB9B715F544C722D152DF0C1A5DE5084BD972AF1",
      "domain":"example.com",
      "invite_expiration":1467987286,
      "synced_password":0,
      "merge_candidates":[  

      ],
      "sub_account_exists":0,
      "has_invite":1,
      "real_name":"Bob Doe",
      "username":"example1",
      "dismissed_merge_candidates":[  

      ],
      "special":0,
      "can_delete":1,
      "alternate_email":"robert@example1.com",
      "has_siblings":0,
      "services":{  
         "webdisk":{  
            "enabled":1,
            "private":0,
            "homedir":"home/example/public_html/webdav",
            "perms":"rw",
            "enabledigest":1
         },
         "email":{  
            "enabled":1,
            "quota":0
         },
         "ftp":{  
            "enabled":1,
            "quota":"42.00",
            "homedir":"example1@example.com"
         }
      },
      "can_set_password":1,
      "issues":[  

      ],
      "phone_number":null,
      "full_username":"example1@example.com"
   },
   "status":1,
   "messages":null,
   "errors":null,
   "metadata":{  

   }
}

Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

Parameter Type Description Possible values Example

guid

string

Required

The Subaccount's unique identifier.

A system-assigned unique value.

Click to view...

EXAMPLE1%3AEXAMPLE.COM%3A564CD663%3AFE50072F2620B50988EA4E5F46022546FBE6BDDE3C36C2F2534F4967C661EC37

Returns

Return	Type	Description	Possible values	Example
`alternate_email`	string	An alternate email address for the subaccount's user.	A valid email address.	`user@example.com`
`avatar_url`	string	The user's subaccount profile photo.	A valid HTTPS URL that points to an image file.	Click to view... `https://img.example.com/avatars/example.jpg`
`can_delete`	Boolean	Whether the cPanel account user can delete the subaccount.	`1` — Can delete. `0` — Cannot delete.	`0`
`can_set_password`	Boolean	Whether the cPanel account user can change the subaccount's password.	`1` — Can change. `0` — Cannot change. Note: The function returns a `0` value for subaccounts that inherit their password from the cPanel account.	`1`
`can_set_quota`	Boolean	Whether the cPanel account user can change the subaccount's disk usage quota.	`1` — Can change. `0` — Cannot change.	`0`
`dismissed`	Boolean	Whether the cPanel account user dismissed the merge prompt for the service account. Note: Only service accounts return this value.	`1` — Dismissed. `0` — Did not dismiss.	`1`
`domain`	string	The subaccount user's associated domain.	A domain that the cPanel account owns.	`example.com`
`full_username`	string	The subaccount's username and domain name.	A valid username, the `@` character, and the associated domain.	`user@example.com`
`guid`	string	The subaccount unique identifier.	The system assigned unique value.	Click to view... `N4641:EXAMPLE.COM:564CC8A7:A82EA007D8348AC631C0170F9418EC1DEB0D164CC5A722A87C55EF5DD2AD98D4`
`issues`	array of hashes	Information about any issues or problems with the subaccount.	This array of hashes contains the `type`, `area`, `service`, `message`, `used`, and `limit` returns.
`type`	string	The type of issue. The function returns this value in the `issues` array of hashes.	`error` `warning` `info`	`info`
`area`	string	The affected section of cPanel & WHM. The function returns this value in the `issues` array of hashes.	A valid section name.	`quota`
`service`	string	The affected service. The function returns this value in the `issues` array of hashes.	`email` `ftp` `webdisk`	`email`
`message`	string	The description of the issue. The function returns this value in the `issues` array of hashes.	A valid string.	`Your account is over quota.`
`used`	integer	The number of megabytes (MB) that the account currently uses. The function returns this value in the `issues` array of hashes.	A positive integer.	`2000`
`limit`	integer	The set quota megabyte (MB) limit for the affected subaccount. The function returns this value in the `issues` array of hashes.	A positive integer.	`1500`
`merge_candidates`	array of hashes	An array of hashes that represents the service accounts that the system could merge for this subaccount.	This array contains the `alternate_email`, `avatar_url`, `can_delete`, `can_set_password`, `can_set_quota`, `dismissed`, `domain`, `full_username`, `guid`, `has_siblings`, `issues`, `merge_candidates`, `parent_type`, `phone_number`, `real_name`, `services`, `special`, `sub_account_exists`, `synced_password`, `type`, and `username` returns.
`has_siblings`	Boolean	Whether the service account shares a `full_username` value with another service account.	`1` — Shares. `0` — Does not share.	`0`
`parent_type`	string	The type of account that could own the service account.	`sub` — A subaccount. `hypothetical` — A hypothetical subaccount that does not yet exist, but the user could create as part of a merge. `null`— Not a merge candidate.	hypothetical
`phone_number`	string	The subaccount user's phone number.	A valid phone number that conforms to ITU-T's `E.164`-recommended standard for the representation of telephone numbers.	`+15551234567`
`real_name`	string	The name of the subaccount's user.	A first name, a last name, or a first name and last name. An empty string.	`John Doe`
`services`	hash	This hash contains information about the subaccount's access to email, FTP, and Web Disk.	This hash contains the `email`, `ftp`, and `webdisk` returns.
`email`	hash	This hash contains the information that indicates the subaccount's email status. The function returns this hash in the `services` hash.	This hash contains the `enabled` and `quota` returns.
`enabled`	Boolean	Whether the subaccount can access Webmail, POP, and IMAP services. The function returns this value in the `email` hash.	`1` — Can access. `0` — Cannot access.	`1`
`quota`	integer	The maximum amount of disk space allocated to subaccount's email account. The function returns this value in the `email` hash.	A positive integer that represents the maximum disk space that the subaccount may use, in megabytes (MB). Note: In cPanel & WHM version 70 and later, this funciton will not return `0` as a value.	`100`
`ftp`	hash	This hash contains the information that indicates the subaccount's FTP status. The function returns this hash in the `services` hash.	This hash contains the `enabled`, `quota`, and `homedir` returns.
`enabled`	Boolean	Whether the subaccount can access FTP. The function returns this value in the `ftp` hash.	`1` — Can access. `0` — Cannot access.	`0`
`quota`	integer	The subaccount's FTP disk space quota. The function returns this value in the `ftp` hash.	A positive integer between `1` and `999999` that represents the maximum disk space that the subaccount may use, in megabytes (MB). `0` — Unlimited.	`100`
`homedir`	string	The subaccount's FTP home directory. The function returns this value in the `ftp` hash.	A valid path, relative to the cPanel account's home directory.	`/subaccount`
`webdisk`	hash	This hash contains information that indicates the subaccount's Web Disk status. The function returns this hash in the `services` hash.	This hash contains the `enabled`, `homedir`, `perms`, and `private` returns.
`enabled`	Boolean	Whether the subaccount can access Web Disk. The function returns this value in the `webdisk` hash.	`1` — Can access. `0` — Cannot access.	`0`
`homedir`	string	The subaccount's Web Disk home directory. The function returns this value in the `webdisk` hash.	A valid path, relative to the cPanel account's home directory.	`/bob`
`perms`	string	Whether to grant write permissions to the subaccount. The function returns this value in the `webdisk` hash.	`ro` — Read-only permissions. `rw` — Read and write permissions.	`rw`
`private`	Boolean	Whether to set the Web Disk directory's permissions to public or private. The function returns this value in the `webdisk` hash.	`1` — Private (`0700`). `0` — Public (`0755`).	`0`
`special`	Boolean	Whether the account is a system-created special account that the user cannot remove.	`1` — A special account. `0` — Not a special account.	`1`
`sub_account_exists`	Boolean	Whether a subaccount exists with the same username.	`1` — Exists. `0` — Does not exist. Note: The function returns a `null` value if the account is not a service account.	`0`
`synced_password`	Boolean	Whether the user has synchronized the passwords for each of the subaccount's service accounts.	`1` — Synchronized. `0` — Not synchronized. Note: The function returns a `null` value if the account is not a subaccount.	`0`
`type`	string	The type of account.	`sub` — A subaccount. `hypothetical` — A hypothetical subaccount that does not exist, but that the user could create as part of a merge. `service` — A service account. `cpanel` — The cPanel account.	`sub`
`username`	string	The username for the subaccount.	A username that meets the subaccount name limitations. Length — 64 characters. Characters — `a-z`, `A-Z`, `0-9`, dot (`.`), hyphen (`-`), underscore (`_`). Note: This value does not include the domain name.	`example`
`has_invite`	Boolean	Whether an account login invitation exists.	`1` — Account invitation exists. `0` — Account invitation does not exist.	`0`
`has_expired_invite`	Boolean	Whether an expired account login invitation exists.	`1` — Expired account invitation exists. `0` — Expired account invitation does not exist.	`0`
`invite_expiration`	integer	When the invitation expires.	A valid timestamp, in Unix epoch time.	`1591718154`
`dismissed_merge_candidates`	array of hashes	An array of hashes of service candidates that the system dismissed from merges.	This array contains the `alternate_email`, `avatar_url`, `can_delete`, `can_set_password`, `can_set_quota`, `dismissed`, `domain`, `full_username`, `guid`, `has_siblings`, `issues`, `merge_candidates`, `parent_type`, `phone_number`, `real_name`, `services`, `special`, `sub_account_exists`, `synced_password`, `type`, and `username` returns.

Function information

Module:

UserManager

API Version:

UAPI

Available in:

cPanel 54+

Methods:

GET, POST

Required Parameters:

guid

Return formats:

JSON, XML

Legacy Equivalents:

(none)

About this module

The UserManager module modifies a cPanel account's Subaccounts.

About UAPI

UAPI accesses and modifies data for cPanel accounts.

Notes:

These functions may require specific features. To enable or disable features, use WHM's Feature Manager interface.
Unless you call this API via the WHM API, you must use the appropriate cPanel ports (2082 or 2083). You can also call some functions via cPanel's Webmail ports (2095 or 2096).

Find a function

Related functions

Page:

UAPI Functions - EmailAuth::get_mail_helo_ip — This function retrieves the HELO domain and IP address that the server uses when it sends a domain's mail.
Page:

UAPI Modules - DomainAliases — The DomainAliases module manages domain aliases.
Page:

UAPI Functions - DomainAliases::get_redirect_url — This function retrieves the redirection URL for a domain alias (parked domain).
Page:

UAPI Functions - DomainAliases::disable_redirect — This function disables the redirection URL for a domain alias (parked domain).
Page:

UAPI Functions - DomainAliases::set_redirect_url — This function redirects a domain alias (parked domain) to a URL.

Child pages

UAPI Functions - UserManager::lookup_user

Description

Examples

Parameters

Returns

Function information

About this module

About UAPI

Find a function

Search

Related functions