Get Inviter List

Updated: 2025-06-05 18:34:19

API Description

1、支持按特定的条件去过滤、获取账号下的邀请员列表
2、接口支持https协议

API URL

https://api.polyv.net/live/v4/user/invite-sales/list

Request Method

GET

API Constraints

The API supports both HTTP and HTTPS. HTTPS is recommended for security. API calls have frequency limits. See details

Request Parameters

Parameter	Required	Type	Description
appId	true	String	Account appId See details on obtaining the key
timestamp	true	Long	Current 13-digit millisecond timestamp, valid for 3 minutes
sign	true	String	Signature, a 32-character uppercase MD5 value. `The appSecret key used to generate the signature is critical for communication data security. It must never be used directly on the client side. All APIs must be called through your own server to relay requests to the POLYV server.` See signature generation rules
viewerUnionId	false	String	Inviter user ID, exact match
mobile	false	String	Inviter phone number, exact match
keyword	false	String	Inviter nickname keyword, supports fuzzy matching
organizationId	false	Integer	Inviter's organization ID
pageSize	false	Integer	Records per page (default 10, max 1000)
pageNumber	false	Integer	Page number (max 1000 pages)

Request Example

https://api.polyv.net/v4/user/invite-sales/list?appId=xxx&timestamp=1670471250000&sign=xxx&mobile=18112345678

Response Parameters

Parameter	Type	Description
code	Integer	Response status code, 200 for success, non-200 for failure
status	String	Response result, determined by business logic. Returns "success" on success, "error" on failure
success	Boolean	Response result, determined by business logic. Returns true on success, false on failure
data	Object	Specific response data See data object description
error	Object	Error information when status code is non-200 See error object description
requestId	String	Request ID, a unique UUID generated for each request. For troubleshooting and debugging only, not for business logic

data Object Description

Field	Type	Description
pageSize	Integer	Records per page
totalPages	Integer	Total pages
totalItems	Integer	Total records
contents	Array	List of inviter information See contents object description
requestId	String	Request ID, a unique UUID generated for each request. For troubleshooting and debugging only, not for business logic

contents Object Description

Note:

If the queried organization has an inviter admin, that admin will be pinned to the top of the first page of data. In this case, the first page will have one more record than the regular "records per page" value.
If the "inviter organization" parameter is not specified or passed, the admin of "Headquarters" (if any) will be pinned to the top by default.

Field	Type	Description
viewerUnionId	String	User ID
nickname	String	User nickname
wxNickName	String	WeChat nickname
wxAvatar	String	WeChat avatar
mobile	String	Phone number
inviteSalesSource	String	Source. console - added via backend; apply - recruited; api - external import
inviteSalesGrantedTime	timestamp	Join time, format is 13-digit timestamp
organizationId	Integer	Organization ID
organizationName	String	Organization name
inviteSalesAdmin	String	Whether the user is an inviter admin, Y/N
customerNum	Integer	Number of bound viewers

error Object Description

Field	Type	Description
code	Integer	Error code, used to identify the specific error cause
desc	String	Error description, corresponds to error.code

Java Request Example

For quick integration of the base code, please download the relevant dependency source code. Click here to download the source code. After downloading, add it to your own source code project. The test cases include HttpUtil.java and LiveSignUtil.java in the downloaded file.

It is strongly recommended to use the Live Java SDK for API integration. The Live Java SDK provides a unified wrapper and optimization for API call logic, exception handling, data signing, and HTTP request thread pools.

public void test() throws IOException, NoSuchAlgorithmException {
    //公共参数,填写自己的实际参数
    String appId = super.appId;
    String appSecret = super.appSecret;
    String timestamp = String.valueOf(System.currentTimeMillis());
    
    //业务参数
    String mobile = "18112345678";
    
    String url = "https://api.polyv.net/v4/user/invite-sales/list";
    
    //http 调用逻辑
    Map<String, String> requestMap = new HashMap<>();
    requestMap.put("appId", appId);
    requestMap.put("timestamp", timestamp);
    requestMap.put("mobile", mobile);
    requestMap.put("sign", LiveSignUtil.getSign(requestMap, appSecret));
    String response = HttpUtil.get(url, requestMap);
    log.info("response: {}", response);
}

Response Example

For global system error descriptions, see Global Error Description

Success Example

{
    "code": 200,
    "status": "success",
    "requestId": "5b33d00b-d284-4a3d-adcd-38210f8681c8",
    "data": {
        "pageSize": 5,
        "totalPages": 2,
        "totalItems": 10,
        "contents": [
            {
                "viewerUnionId": "6_xxx",
                "nickname": "广州观众",
                "wxNickName": null,
                "wxAvatar": null,
                "mobile": "18112345678",
                "inviteSalesSource": "apply",
                "inviteSalesGrantedTime": 1744795084000,
                "organizationId": 123,
                "organizationName": "总部",
                "inviteSalesAdmin": "Y",
                "customerNum": 10,
            }
        ]
    },
    "success": true
}

Failure Example

{
    "code": 400,
    "status": "error",
    "requestId": "d310b70bc329403f87f77f9203d50f89.128.16360831552223589",
    "error": {
        "code": 20001,
        "desc": "application not found."
    },
    "success": false
}

Live Streaming Server API