/v2/users/inquiryUserInfo

2023-04-28 21:00

POST /v2/users/inquiryUserInfo

With this API call, a merchant can inquire about user information with the access token. The specific information you can inquire about is defined in the my.getAuthCode JSAPI.

Note: Before calling this API, you must add the App_User_Authorization feature to your mini program in Mini Program Platform to access the API. For detailed instructions, refer to Add features.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
appId	String	Yes	Indicates the unique ID assigned by Mini Program Platform to identify a mini program. Maximum length: 32 characters Characters not allowed: special characters such as @ # ? Note: Obtain this field via the my.getAppIdSync JSAPI or Mini Program Platform.	"3333010071465913xxx"
accessToken	String	Yes	The access token is used to access user information. For the specific information that can be accessed, see the my.getAuthCode JSAPI. Maximum length: 128 characters Characters not allowed: special characters such as @ # ? Note: Obtain this field via the /v2/authorizations/applyToken API.	"281010033AB2F588D14B43238637264FCA5AAF35xxxx"
authClientId	String	Yes	Indicates the unique ID assigned by the super app to identify an authorized merchant. Maximum length: 128 characters Characters not allowed: special characters such as @ # ?	"202016726873874774774xxxx"
customerBelongsTo	String	Yes	Indicates the super app that the user uses. Valid values are: `ALIPAY_CN`: Alipay CN `ALIPAY_HK`: Alipay HK `ALIPAY_MO`: Alipay MO `TNG`: Touch 'n Go `GCASH`: Gcash `DANA`: Dana `KAKAOPAY`: KakaoPay `BKASH`: bKash `CHOPE`: Chope `TRUEMONEY`: TrueMoney	"TNG"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	copy `{ "memo": "memo" }`

Response parameters

Field

Data type

Required

Description

Example

result

Result

Yes

Indicates the request result such as status and error codes.

copy

{
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
}

userInfo

User

Indicates the user information that the merchant queried.

Note:

This parameter must be returned when the request is successful (that is, the value of result.resultStatus is S.
The information returned by this parameter is subject to the laws and regulations of the country or region where the super app is released.
The appUserId assigned by the super app is passed to the extendInfo in the userInfo to uniquely identify a user.
The acqUserId assigned by Alipay merchant service is passed to the extendInfo in the userInfo to uniquely identify a user.

See Response sample for details.

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	The inquiry is successful. Use the `accessToken` to access user information within the corresponding scope. The corresponding result.resultCode is `SUCCESS` and the result.resultMessage is `Success`.
U	The status of the inquiry is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION` and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The inquiry is failed. The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for all mini program OpenAPIs in V2.
API-specific error codes: are listed in the following table.

Error code	Result status	Error message	Further action
INVALID_AUTH_CLIENT	F	Either the merchant does not exist or the merchant does not onboard to the native app.	Use a valid authClientId assigned by the super app.
INVALID_ACCESS_TOKEN	F	The access token is not valid.	Obtain a new authorization code via the my.getAuthCode JSAPI and then get a valid access token with the authorization code via the /v2/authorizations/applyToken API.
EXPIRED_ACCESS_TOKEN	F	The access token is expired.	Obtain a new access token with a refresh token via the /v2/authorizations/applyToken API.
APP_NOT_EXIST	F	The app ID does not exist.	Obtain a valid appId via the my.getAppIdSync JSAPI or Mini Program Platform.
MERCHANT_AUTH_INFO_NOT_EXIST	F	The merchant does not grant authorization to Mini Program Platform for further operations.	Contact technical support to troubleshoot the issue.

Samples

The data flow of inquiring about a user's information is illustrated as below:

The merchant server calls this API with the access token to inquire about the user's information.
The super app server returns the user's information to the merchant server based on the scopes of the access token.

Request

copy
{
  "appId": "3333010071465913xxx",
  "accessToken": "281010033AB2F588D14B43238637264FCA5AAF35xxxx",
  "authClientId": "202016726873874774774xxxx",
  "customerBelongsTo": "CHOPE"
  
}

The merchant (202016726873874774774xxxx) uses the access token (281010033AB2F588D14B43238637264FCA5AAF35xxxx) to access the user's specific information.

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  },
  "userInfo": {
    "userId": "1000001119398804xxxx",
    "status": "ACTIVE",
    "nickName": "Jack",
    "userName": {
      "fullName": "Jack Sparrow",
      "firstName": "Jack",
      "lastName": "Sparrow"
    },
    "avatar": "http://example.com/avatar.htm?avatarId=FBF16F91-28FB-47EC-B9BE-27B285C23CD3xxxx",
    "gender": "MALE",
    "birthDate": "2020-07-25",
    "nationality": "US", 
    "loginIdInfos": [
      {
        "loginId": "1116874199xxx",
        "loginIdType": "MOBILE_PHONE"
      }
     ],
    "contactInfos": [
      {
        "contactNo": "1116874199xxx",
        "contactType": "MOBILE_PHONE"
      }
    ],
    "extendInfo": "{\"appUserId\":\"200xxxx\",\"acqUserId\":\"300xxxx\"}"
  }
}

In the above sample, result.resultStatus is S, which means the inquiry request is successful. And the specified userInfo includes the user information returned by the super app.