Create a Lottery Activity

Updated: 2026-10-12 10:24:30

API Description

1、创建抽奖活动
2、接口支持https协议

API URL

http://api.polyv.net/live/v4/channel/lottery-activity/create

Request Method

POST

API Constraints

The API supports both HTTP and HTTPS. HTTPS is recommended to ensure API security. There is a frequency limit for API calls. For details, please see
If the parameters are incorrect, a 400 exception will be returned.
When the lottery user type is custom group and the group lottery method is specified, customGroupLotterySpecified cannot be empty and must exactly match the groups in customGroupIds (the lottery quantity must be specified for each group, no more and no less), otherwise error code 40218 will be returned.

Request Parameter Description

Parameter Name	Required	Type	Description
appId	true	String	Account appId [See Get Key for details]
timestamp	true	Long	Current 13-digit millisecond timestamp, valid within 3 minutes
sign	true	String	Signature, a 32-character uppercase MD5 value, `The appSecret key used to generate the signature is key information for communication data security. It is strictly prohibited to save it on the client for direct use. All APIs must be called through the customer's own server as an intermediary to the POLYV server to obtain response data.` [See Signature Generation Rules for details]
channelId	true	Integer	Channel ID

Request Body Parameter Description

Parameter Name	Required	Type	Description
activityName	true	String	Lottery activity name
lotteryCondition	true	String	Lottery activity type, none: unconditional, invite: invite friends, duration: watch duration, comment: comment lottery, question: question lottery, questionnaire: questionnaire lottery
amount	true	Integer	Number of winners
hiddenWinnerAmount	false	String	Whether to hide the number of winners, value: Y/N, default N
lotteryRange	false	String	Type of users participating in the lottery: all: all, notWinning: users who have not won, customGroup: custom group, userLabel: user label
customGroupIds	false	Array	Custom group IDs, valid when the lottery user type is custom group, maximum 10
customGroupLotteryType	false	String	Group lottery method, average: equal lottery, random: random lottery, specified: specified number per group
customGroupLotteryAmount	false	Integer	Number to draw per group, valid when the group lottery method is average
customGroupLotterySpecified	false	Array	Number to draw per group, required when the group lottery method is specified [See CustomGroupLotterySpecified Parameter Description for details]
userLabels	false	Array	User label IDs, valid when the lottery user type is userLabel, maximum 10
hiddenAttendeeNumber	false	String	Whether to hide the number of participants, value: Y/N, default N
repeatWinEnabled	false	String	Allow repeated winning, value: Y/N, default N
receiveEnabled	false	String	Whether to fill in shipping information, value: Y/N, default N
receiveInfo	false	Array	List of shipping field information, filled in for unconditional lottery [See ReceiveInfo for details]
prizeName	true	String	Prize name
thumbnail	false	String	Prize image
activityDuration	false	String	Activity duration, required for non-unconditional lottery
activityDurationType	false	String	Activity duration unit (second, minute, hour), default minute, second is only supported when lotteryCondition is none
inviteType	false	String	Invitation method, poster: invitation poster, external: external invitation, required for invitation lottery
externalListLink	false	String	External list link, required for invitation lottery when the invitation method is external invitation
externalInviteNumLink	false	String	Link to get the number of invitees, required for invitation lottery when the invitation method is external invitation
inviteNum	false	Integer	Number of invitees, required for invitation lottery
duration	false	Integer	Watch duration, required for watch duration lottery
comment	false	String	Comment content, required for comment lottery
acceptType	false	String	Prize claim method, form: form, link: external link, qrCode: scan QR code, required for non-unconditional and question lottery
formInfo	false	Array	Form field information for the prize claim method, filled in when the prize claim method is form [See ReceiveInfo for details]
prizeUrl	false	String	Prize link for the prize claim method, required when the prize claim method is external link
qrCode	false	String	QR code link for the prize claim method, required when the prize claim method is QR code
qrCodeTips	false	String	QR code tip text for the prize claim method, filled in when the prize claim method is QR code
realPrice	false	BigDecimal	Discounted price
price	false	BigDecimal	Original prize price
prizeInfo	false	Array	Prize information, required for question or questionnaire lottery [See PrizeInfo for details]
questionGroupId	false	Long	Question group template ID, required for question or questionnaire lottery
perAnswerDuration	false	Integer	Answer duration per question, required for question lottery
lotteryOnlineEnabled	false	String	Viewers must be online when the lottery is drawn, value: Y/N, default Y (takes effect when set for unconditional group lottery)
answerType	false	String	Question lottery, answering method, pushQuestion: answer while pushing, autonomyAnswer: independent answering, default: pushQuestion
showWinnerCode	false	String	Whether to display the prize redemption code, default on, value: Y/N, default Y
showWinners	false	String	Whether to display the winner list, default on, value: Y/N, default Y

CustomGroupLotterySpecified Parameter Description

Parameter Name	Required	Type	Description
customGroupId	true	Long	Custom group ID, must match the groups in customGroupIds
amount	true	Integer	Number to draw for this group, 1-10000

ReceiveInfo Parameter Description

Parameter Name	Required	Type	Description
type	false	String	Type, userName: name, userPhone: mobile phone number, custom: custom
field	true	String	Field name
tips	true	String	Tip text
required	false	Boolean	Whether required, true/false

PrizeInfo Parameter Description

Parameter Name	Required	Type	Description
prizeItem	true	String	Prize item name
correctAnswerCount	true	Integer	Number of correctly answered questions
prizeName	true	String	Prize name
thumbnail	false	String	Prize image
realPrice	false	BigDecimal	Discounted price
price	false	BigDecimal	Original prize price
acceptType	true	String	Prize claim method, form: form, link: external link, qrCode: scan QR code
formInfo	false	Array	Form field information for the prize claim method, filled in when the prize claim method is form [See ReceiveInfo for details]
prizeUrl	false	String	Prize link for the prize claim method, required when the prize claim method is external link
qrCode	false	String	QR code link for the prize claim method, required when the prize claim method is QR code
qrCodeTips	false	String	QR code tip text for the prize claim method, filled in when the prize claim method is QR code
amount	true	Integer	Number of winners
hiddenWinnerAmount	false	String	Whether to hide the number of winners, value: Y/N, default N

Example

http://api.polyv.net/live//v4/channel/lottery-activity/create?appId=frlr1zazn3&timestamp=1665629374000&sign=6CFA3141718E1AF0155889EEA2988206&channelId=2974342

Request body JSON parameters:

{
    "activityName": "无条件抽奖",
    "lotteryCondition": "none",
    "amount": 1,
    "receiveEnabled": "Y",
    "prizeName": "键盘",
    "receiveInfo": [{
        "field": "姓名",
        "tips": "请输入您的名称",
        "type": "userName",
        "required": true
    }, {
        "field": "手机",
        "tips": "请输入您的手机号码",
        "type": "userPhone",
        "required": true
    }],
    "lotteryRange": "all"
}

Example request body for custom groups with a different number to draw specified for each group (lotteryRange is customGroup, customGroupLotteryType is specified):

{
    "activityName": "分组指定人数抽奖",
    "lotteryCondition": "none",
    "amount": 30,
    "receiveEnabled": "N",
    "prizeName": "键盘",
    "lotteryRange": "customGroup",
    "customGroupIds": [10001, 10002],
    "customGroupLotteryType": "specified",
    "customGroupLotterySpecified": [
        {"customGroupId": 10001, "amount": 10},
        {"customGroupId": 10002, "amount": 20}
    ]
}

Response Description

Parameter Name	Type	Description
code	Integer	Status code, the same as the HTTP status code, used to determine the basic response status
status	String	Response result, determined by the business, returns success on success and error on failure
success	Boolean	Whether the response is successful
requestId	String	Request ID, a unique UUID generated for each request, only for troubleshooting and debugging, and should not be tied to business
error	Object	Error information when the status code is not 200 [See Error Field Description for details]
data	Object	Response details [See data Field Description for details]

Error Response Description

Parameter Name	Type	Description
code	Integer	Error code, used to determine the specific cause of the error
desc	String	Error description, corresponding to error.code

data Response Description

Parameter Name	Type	Description
id	Long	Lottery activity ID
activityName	String	Lottery activity name
lotteryCondition	String	Lottery type
status	String	Lottery activity status
amount	Integer	Number of winners
hiddenWinnerAmount	String	Whether to hide the number of winners
lotteryRange	String	Type of users participating in the lottery: all: all, notWinning: users who have not won, customGroup: custom group, userLabel: user label
customGroup	Array	Custom group information [See CustomGroup for details]
customGroupLotteryType	String	Group lottery method, average: equal lottery, random: random lottery, specified: specified number per group
customGroupLotteryAmount	Integer	Number to draw per group, returned when the group lottery method is average
customGroupLotterySpecified	Array	Number to draw per group, returned when the group lottery method is specified [See CustomGroupLotterySpecified Parameter Description for details]
userLabels	Array	User label IDs
hiddenAttendeeNumber	String	Whether to hide the number of participants
repeatWinEnabled	String	Allow repeated winning
receiveEnabled	String	Whether to fill in shipping information
receiveInfo	Array	List of shipping field information, filled in for unconditional lottery [See ReceiveInfo for details]
prizeName	String	Prize name
thumbnail	String	Prize image
activityDuration	String	Activity duration (minutes)
inviteType	String	Invitation method
externalListLink	String	External list link
externalInviteNumLink	String	Link to get the number of invitees
inviteNum	Integer	Number of invitees
duration	Integer	Watch duration
comment	String	Comment content
acceptType	String	Prize claim method, form: form, link: external link, qrCode: scan QR code,
formInfo	Array	Form field information for the prize claim method [See ReceiveInfo for details]
prizeUrl	String	Prize link for the prize claim method
qrCode	String	QR code link for the prize claim method
qrCodeTips	String	QR code tip text for the prize claim method
realPrice	BigDecimal	Discounted price
price	BigDecimal	Original prize price
prizeInfo	Array	Prize information [See PrizeInfo for details]
questionGroupId	Long	Question group template ID
perAnswerDuration	Integer	Answer duration per question

CustomGroup Response Description

Parameter Name	Type	Description
id	Long	Group ID
title	String	Group title
type	String	Group type
count	String	Number of people in the group

ReceiveInfo Response Description

Parameter Name	Type	Description
type	String	Type, userName: name, userPhone: mobile phone number, custom: custom
field	String	Field name
tips	String	Tip text
required	Boolean	Whether required, true/false

PrizeInfo Response Description

Parameter Name	Type	Description
prizeItem	String	Prize item name
correctAnswerCount	Integer	Number of correctly answered questions
prizeName	String	Prize name
thumbnail	String	Prize image
realPrice	BigDecimal	Discounted price
price	BigDecimal	Original prize price
acceptType	String	Prize claim method, form: form, link: external link, qrCode: scan QR code
formInfo	Array	Form field information for the prize claim method [See ReceiveInfo for details]
prizeUrl	String	Prize link for the prize claim method
qrCode	String	QR code link for the prize claim method
qrCodeTips	String	QR code tip text for the prize claim method
amount	Integer	Number of winners
hiddenWinnerAmount	String	Whether to hide the number of winners

Java Request Example

For quick integration with the basic code, please download the relevant dependency source code, click to download the source code, and add it to your own source project after downloading. The HttpUtil.java and LiveSignUtil.java in the test cases are both included in the downloaded file.

It is strongly recommended that you use the Live Java SDK to complete API integration. The Live Java SDK provides unified encapsulation and optimization of API call logic, exception handling, data signing, and HTTP request thread pools.

Response Example

For system global error descriptions, see Global Error Description

Success example

{
    "code": 200,
    "status": "success",
    "requestId": "723ed01861804e9aa3dc1cf1aced83d5.72.17097790901718347",
    "data": {
        "id": 20521,
        "activityName": "无条件抽奖",
        "lotteryCondition": "none",
        "amount": 1,
        "receiveEnabled": "Y",
        "receiveInfo": [
            {
                "type": "userName",
                "field": "姓名",
                "tips": "请输入您的名称",
                "required": true
            },
            {
                "type": "userPhone",
                "field": "手机",
                "tips": "请输入您的手机号码",
                "required": true
            }
        ],
        "prizeName": "键盘",
        "activityDuration": null,
        "inviteType": "poster",
        "inviteNum": null,
        "duration": null,
        "comment": null,
        "externalListLink": null,
        "externalInviteNumLink": null,
        "acceptType": null,
        "formInfo": null,
        "prizeUrl": null,
        "qrCode": null,
        "qrCodeTips": null,
        "thumbnail": null,
        "realPrice": null,
        "price": null,
        "status": null,
        "prizeInfo": null,
        "questionGroupId": null,
        "perAnswerDuration": null,
        "lotteryRange": "all",
        "repeatWinEnabled": "N",
        "customGroup": [],
        "hiddenWinnerAmount": "N",
        "hiddenAttendeeNumber": "N",
        "customGroupLotteryType": "random",
        "customGroupLotteryAmount": null
    },
    "success": true
}

Exception example

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