Obtaining Users' Basic Information (UnionID Mechanism)

Upon the interaction between a follower and the Official Account by sending messages, the Official Account can obtain the follower's OpenID (an encrypted Weixin ID that is unique to each user under each Official Account. A user's OpenID varies with different Official Accounts). This API is used to obtain users' basic information, including alias, profile photo, gender, city, language, and time of following, based on the OpenIDs.

Note that you need to go to the Weixin Open Platform (open.weixin.qq.com) to link the Official Account before you can make a user account consistent between multiple Official Accounts, or between the Official Accounts and Apps, using the UnionID mechanism.

About UnionID Mechanism

You can obtain a user's basic information using the OpenID. If you have multiple Apps, website applications, and Official Accounts, you can uniquely identity the user by getting the UnionID in the user's basic information, as the user's UnionID is unique across all the Apps, website applications and Official Accounts under the same Weixin Open Platform account. In other words, a single user has the same UnionID between different Apps and applications under the same Weixin Open Account.

Obtaining User's Basic Information (UnionID Mechanism)

You can obtain a user's basic information using the OpenID with the HTTPS protocol.

API Request Format
HTTP request method: GET
https://api.weixin.qq.com/cgi-bin/user/info?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN

Parameters:

Parameter Required Description
access_token Yes The credential for calling the API
openid Yes ID of an ordinary user. This is unique to the current Official Account.
lang No Language used in the country/region. zh_CN: Simplified Chinese; zh_TW: Traditional Chinese; en: English.

Response

For a successful request, Weixin returns the following JSON packet to the Official Account:

{
    "subscribe": 1, 
    "openid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M", 
    "nickname": "Band", 
    "sex": 1, 
    "language": "zh_CN", 
    "city": "Guangzhou", 
    "province": "Guangdong", 
    "country": "China", 
    "headimgurl":"http://thirdwx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/0",
    "subscribe_time": 1382694957,
    "unionid": " o6_bmasdasdsad6_2sgVt7hMZOPfL"
    "remark": "",
    "groupid": 0,
    "tagid_list":[128,2],
    "subscribe_scene": "ADD_SCENE_QR_CODE",
    "qr_scene": 98765,
    "qr_scene_str": ""
}

Parameters:

Parameter Description
subscribe Indicates whether the user has subscribed to the Official Account. 0: the user has not followed the Official Account, and no addition user information can be fetched.
openid User ID, which is unique to the current Official Account.
nickname User's alias
sex User's gender. 1: Male; 2: Female; 0: Unknown.
city User's city
country User's country
province User's province
language User's language. zh_CN: simplified Chinese.
headimgurl User's profile photo. The last numeric value represents the size of a square profile photo (The value can be 0, 46, 64, 96, or 132. The value 0 represents a 640*640 square profile photo). This parameter is left empty if the user has no profile photo. If the user has changed the profile photo, the URL of the original profile photo becomes invalid.
subscribe_time The time when the user followed the Official Account. It is expressed as a timestamp. If a user followed the Official Account multiple times, this value takes the time when the user last followed the Official Account.
unionid This field only appears after the user links the Official Account to a Weixin Open Platform account.
remark The Official Account operator's remarks for the follower (add it in User Management on the Weixin Official Accounts Platform).
groupid ID of the user group (compatible with the old User Grouping API)
tagid_list List of tag IDs for the user
subscribe_scene The channel through which the user follows the Official Account. ADD_SCENE_SEARCH: Search in the Official Account; ADD_SCENE_ACCOUNT_MIGRATION: Official Account migration; ADD_SCENE_PROFILE_CARD: Shared contact card; ADD_SCENE_QR_CODE: Scanning QR code; ADD_SCENE_PROFILE_ LINK: Tapping the name on the article page; ADD_SCENE_PROFILE_ITEM: Menu on the upper right corner of the article page; ADD_SCENE_PAID: Following Official Account after payment; ADD_SCENE_OTHERS: Others
qr_scene QR code scanning scenario (developer-defined)
qr_scene_str QR code scanning scenario description (developer-defined)

When an error occurs, Weixin returns the error code and other information. The following is an example of JSON packet (in this case, the error is caused by an invalid AppID):

{"errcode":40013,"errmsg":"invalid appid"}

Obtaining Users' Basic Information in Batch

You can obtain multiple users' basic information in batch with this API. A maximum of 100 user's information can be fetched at a time.

API Request Format

HTTP request method: GET
https://api.weixin.qq.com/cgi-bin/user/info/batchget?access_token=ACCESS_TOKEN

POST data example:

{
    "user_list": [
        {
            "openid": "otvxTs4dckWG7imySrJd6jSi0CWE", 
            "lang": "zh_CN"
        }, 
        {
            "openid": "otvxTs_JZ6SEiP0imdhpi50fuSZg", 
            "lang": "zh_CN"
        }
    ]
}

Parameters:

Parameter Required Description
openid Yes User ID, which is unique to the current Official Account.
lang No Language used in the country/region. zh_CN: simplified Chinese (default); zh_TW: traditional Chinese; en: English

Response

For a successful request, Weixin returns the following JSON packet to the Official Account (in the example, the basic information of two users (two 2 openids) is fetched at a time. The first user has followed the Official Account, and the second one has not).

{
   "user_info_list": [
       {
           "subscribe": 1, 
           "openid": "otvxTs4dckWG7imySrJd6jSi0CWE", 
           "nickname": "iWithery", 
           "sex": 1, 
           "language": "zh_CN", 
           "city": "Jieyang", 
           "province": "Guangdong", 
           "country": "China", 

           "headimgurl": "http://thirdwx.qlogo.cn/mmopen/xbIQx1GRqdvyqkMMhEaGOX802l1CyqMJNgUzKP8MeAeHFicRDSnZH7FY4XB7p8XHXIf6uJA2SCunTPicGKezDC4saKISzRj3nz/0",

          "subscribe_time": 1434093047, 
           "unionid": "oR5GjjgEhCMJFyzaVZdrxZ2zRRF4", 
           "remark": "", 

           "groupid": 0,
           "tagid_list":[128,2],
           "subscribe_scene": "ADD_SCENE_QR_CODE",
           "qr_scene": 98765,
           "qr_scene_str": ""

      }, 
       {
           "subscribe": 0, 
           "openid": "otvxTs_JZ6SEiP0imdhpi50fuSZg"
       }
   ]
}

Parameters:

Parameter Description
subscribe Indicates whether the user has subscribed to the Official Account. 0: the user has not followed the Official Account, and no addition user information can be fetched.
openid User ID, which is unique to the current Official Account.
nickname User's alias
sex User's gender. 1: Male; 2: Female; 0: Unknown.
city User's city
country User's country
province User's province
language User's language. zh_CN: simplified Chinese.
headimgurl User's profile photo. The last numeric value represents the size of a square profile photo (The value can be 0, 46, 64, 96, or 132. The value 0 represents a 640*640 square profile photo). This parameter is left empty if the user has no profile photo. If the user has changed the profile photo, the URL of the original profile photo becomes invalid.
subscribe_time The time when the user followed the Official Account. It is expressed as a timestamp. If a user followed the Official Account multiple times, this value takes the time when the user last followed the Official Account.
unionid This field only appears after the user links the Official Account to a Weixin Open Platform account.
remark The Official Account operator's remarks for the follower (add it in User Management on the Weixin Official Accounts Platform).
groupid ID of the user group (compatible with the old User Grouping API)
tagid_list List of tag IDs for the user
subscribe_scene The channel through which the user follows the Official Account. ADD_SCENE_SEARCH: Search in the Official Account; ADD_SCENE_ACCOUNT_MIGRATION: Official Account migration; ADD_SCENE_PROFILE_CARD: Shared contact card; ADD_SCENE_QR_CODE: Scanning QR code; ADD_SCENE_PROFILE_ LINK: Tapping the name on the article page; ADD_SCENE_PROFILE_ITEM: Menu on the upper right corner of the article page; ADD_SCENE_PAID: Following Official Account after payment; ADD_SCENE_OTHERS: Others
qr_scene QR code scanning scenario (developer-defined)
qr_scene_str QR code scanning scenario description (developer-defined)

When an error occurs, Weixin returns the error code and other information. The following is an example of JSON packet (in this case, the error is caused by an invalid AppID):

{"errcode":40013,"errmsg":"invalid appid"}