Pulling Profiles

Feature Overview

This API is used to pull profile fields of friends and other users.
We recommend that you pull the profile fields of no more than 100 users at a time to avoid response packet failure due to excessive data volume.
Ensure that all accounts in the request are imported into the Chat console. Otherwise, an error will be displayed at the Chat backend.

API Calling Description

Sample request URL

https://xxxxxx/v4/profile/portrait_get?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Request parameters

The following table describes the modified parameters when this API is called. For other parameters, see RESTful API Overview.
Parameter
Description
xxxxxx
Domain name corresponding to the country/region where your SDKAppID is located.
China: console.tim.qq.com
Singapore: adminapisgp.im.qcloud.com
Seoul: adminapikr.im.qcloud.com
Frankfurt: adminapiger.im.qcloud.com
Silicon Valley: adminapiusa.im.qcloud.com
Jakarta: adminapiidn.im.qcloud.com
v4/profile/portrait_get
Request API
sdkappid
SDKAppID assigned by the Chat console when an app is created
identifier
App admin account. For more information, see the App Admin section in Login Authentication.
usersig
Signature generated by the app admin account. For details, see Generating UserSig.
random
A random 32-bit unsigned integer ranging from 0 to 4294967295.
contenttype
Request format, which should always be json.

Maximum call frequency

200 calls per second

Sample request

Read a profile field of a user
{
"To_Account":["id1"],
"TagList":
[
"Tag_Profile_IM_Nick"
]
}
Read multiple profile fields of a user
{
"To_Account":["id1"],
"TagList":
[
"Tag_Profile_IM_Nick",
"Tag_Profile_IM_AllowType",
"Tag_Profile_IM_SelfSignature",
"Tag_Profile_Custom_Test"
]
}
Read a profile field of multiple users
{
"To_Account":["id1","id2","id3"],
"TagList":
[
"Tag_Profile_IM_Nick"
]
}
Read multiple profile fields of multiple users
{
"To_Account":["id1","id2","id3","id4"],
"TagList":
[
"Tag_Profile_IM_Nick",
"Tag_Profile_IM_AllowType",
"Tag_Profile_IM_SelfSignature",
"Tag_Profile_Custom_Test"
]
}

Request fields

Field
Type
Required
Description
To_Account
Array
Required
The UserID of users whose profile fields need to be pulled. <br />Note: profile fields of no more than 100 users can be pulled each time to prevent a response packet failure due to excessive data.
TagList
Array
Required
The tag of a profile field to be pulled. Supported fields include:<br />1. Standard profile fields. For more information, see Standard Profile Fields.<br />2. Custom profile fields. For more information, see Custom profile fields.

Sample response

Read a profile field of a user
{
"UserProfileItem":
[
{
"To_Account":"id1",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest1"
}
],
"ResultCode":0,
"ResultInfo":""
}
],
"ActionStatus":"OK",
"ErrorCode":0,
"ErrorInfo":"",
"ErrorDisplay":""
}
Read multiple profile fields of a user
{
"UserProfileItem":
[
{
"To_Account":"id1",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest1"
},
{
"Tag":"Tag_Profile_IM_AllowType",
"Value":"AllowType_Type_NeedConfirm"
},
{
"Tag":"Tag_Profile_IM_SelfSignature",
"Value":"I'm Test1"
},
{
"Tag":"Tag_Profile_Custom_Test",
"Value":"Custom Data1"
}
],
"ResultCode":0,
"ResultInfo":""
}
],
"ActionStatus":"OK",
"ErrorCode":0,
"ErrorInfo":"",
"ErrorDisplay":""
}
Read a profile field of multiple users
{
"UserProfileItem":
[
{
"To_Account":"id1",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest1"
}
],
"ResultCode":0,
"ResultInfo":""
},
{
"To_Account":"id2",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest2"
}
],
"ResultCode":0,
"ResultInfo":""
},
{
"To_Account":"id3",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest3"
}
],
"ResultCode":0,
"ResultInfo":""
}
],
"ActionStatus":"OK",
"ErrorCode":0,
"ErrorInfo":"",
"ErrorDisplay":""
}
Read multiple profile fields of multiple users
{
"UserProfileItem":
[
{
"To_Account":"id1",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest1"
},
{
"Tag":"Tag_Profile_IM_AllowType",
"Value":"AllowType_Type_NeedConfirm"
},
{
"Tag":"Tag_Profile_IM_SelfSignature",
"Value":"I'm Test1"
},
{
"Tag":"Tag_Profile_Custom_Test",
"Value":"Custom Data1"
}
],
"ResultCode":0,
"ResultInfo":""
},
{
"To_Account":"id2",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest2"
},
{
"Tag":"Tag_Profile_IM_AllowType",
"Value":"AllowType_Type_DenyAny"
},
{
"Tag":"Tag_Profile_IM_SelfSignature",
"Value":"I'm Test2"
},
{
"Tag":"Tag_Profile_Custom_Test",
"Value":"Custom Data2"
}
],
"ResultCode":0,
"ResultInfo":""
},
{
"To_Account":"id3",
"ProfileItem":
[
{
"Tag":"Tag_Profile_IM_Nick",
"Value":"NickNameTest3"
},
{
"Tag":"Tag_Profile_IM_AllowType",
"Value":"AllowType_Type_AllowAny"
},
{
"Tag":"Tag_Profile_IM_SelfSignature",
"Value":"I'm Test3"
},
{
"Tag":"Tag_Profile_Custom_Test",
"Value":"Custom Data3"
}
],
"ResultCode":0,
"ResultInfo":""
},
{
"To_Account":"id4",
"ResultCode":40006,
"ResultInfo":"Err_Profile_PortraitGet_Read_Custom_Data_Fail"
}
],
"Fail_Account":["id4"],
"ActionStatus":"OK",
"ErrorCode":0,
"ErrorInfo":"",
"ErrorDisplay":""
}

Response fields

Field
Type
Description
UserProfileItem
Array
Structured information of the returned user profile.
To_Account
String
UserID of a user.
ProfileItem
Array
The returned user profile object array. Each object in the array contains a tag and a value.
Tag
String
The returned profile object name. The profile objects include:<br>1. Standard profile fields. For more information, see Standard Profile Fields<br>2. Custom profile fields. For more information, see Custom Profile Fields.
Value
uint64_t/string/bytes
The value of a pulled profile object. For more information, see Profile Fields.
ResultCode
Integer
The processing result of To_Account. 0: Succeeded. Other values: Failed.
ResultInfo
String
Error description of To_Account. This field is empty if the request is successful.
Fail_Account
Array
List of users whose processing failed. This field is only returned when at least one user fails.
ActionStatus
String
The result of the request. OK means the request was successful. FAIL means the request failed.
ErrorCode
Integer
Error code. 0: Successful; other values: Failed
ErrorInfo
String
Detailed error information.
ErrorDisplay
String
Detailed information displayed on the client.

Error Codes

The returned HTTP status code for this API is always 200 unless a network error (such as error 502) occurs. The specific error code and details can be found in the response fields ErrorCode and ErrorInfo respectively. For public error codes (60000 to 79999), see Error Codes. The following table describes the error codes specific to this API:
Error Code
Description
40001
Incorrect request parameter. Check your request according to the error description.
40002
Request parameter error. To_Account is not specified.
40003
The requested account does not exist.
40004
The request requires app admin permission.
40006
Internal server error. Try again later.
40007
No permission to read profile fields.
40009
The tag of a profile field does not exist.

API Debugging Tool

Use the RESTful API online debugging tool to debug this API.

References

Configuring Profiles (v4/profile/portrait_set).