Skip to main content
Call this API to get the user ID of an Enterprise Account user by mobile number. If the employee has left the organization, the user ID cannot be retrieved by mobile number.

Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/topapi/v2/user/getbymobile
HTTP MethodPOST
Supported app typesappType-Internal app
Required permissionspermission-qyapi_get_member_by_mobile-Permission to get user basic information by mobile number

Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesbe3FxxxxThe App credential used to call this API. Obtain it by calling the API to get the access_token of an internal app.

Request body

NameTypeRequiredExampleDescription
mobileStringYes185xxxxx676The mobile number of the user.
support_exclusive_account_searchBooleanYestrueWhether to support searching for Enterprise Accounts by mobile number. - true: Supported. - false: Not supported. Note - Applies to Enterprise Accounts only. - Only Enterprise Accounts created by the current organization can be searched.

Request example

curl -X POST "https://oapi.dingtalk.io/topapi/v2/user/getbymobile" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=a16xxxxa2efbee' \
-d 'mobile=1851xxxx676' \
-d 'support_exclusive_account_search=true'
Java
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/getbymobile");
OapiV2UserGetbymobileRequest req = new OapiV2UserGetbymobileRequest();
req.setMobile("185xxxx");
OapiV2UserGetbymobileResponse rsp = client.execute(req, acces_token);
System.out.println(rsp.getBody());
Python
import dingtalk.api

req=dingtalk.api.OapiV2UserGetbymobileRequest("https://oapi.dingtalk.io/topapi/v2/user/getbymobile")

req.mobile="13800138000"
req.support_exclusive_account_search=true
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)
PHP
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2UserGetbymobileRequest;
$req->setMobile("13800138000");
$req->setSupportExclusiveAccountSearch("true");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/topapi/v2/user/getbymobile");
C#
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/topapi/v2/user/getbymobile");
OapiV2UserGetbymobileRequest req = new OapiV2UserGetbymobileRequest();
req.Mobile = "1851xxxx76";
req.SupportExclusiveAccountSearch = true;
OapiV2UserGetbymobileResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

NameTypeExampleDescription
request_idString5w82ciuur781The request ID.
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
resultObjectThe returned result.
useridStringzhangsanThe user ID of the employee.
exclusive_account_userid_listString[][“zxxxx”,“lixxxi”]The list of user IDs of Enterprise Account employees. Note Only Enterprise Accounts created by the current organization are returned.

Response body example

{
  "errcode":"0",
  "result":{
    "exclusive_account_userid_list":"[\"zxxxx\",\"lixxxi\"]",
    "userid":"zhangsan"
  },
  "errmsg":"ok"
}

Error codes

If an error occurs when calling this API, find the solution in the Global error codes document based on the error message.
Error code (errcode)Error message (errmsg)Solution
400002Invalid parameterVerify that the parameters are filled in as required by the documentation above.
40104Invalid mobile number in the organizationVerify that the mobile number is correct.
60121User not foundVerify that the information is filled in correctly.
-1System busyTry again later.