Issue bonuses

Attention

The toloka.yandex.com domain will be disabled starting July 1, 2023. Please use the toloka.dev domain for API requests.

Issues bonuses to Tolokers.

The size of the bonus can range between $0.005 and $100 per Toloker at a time.

Restriction

You can send a maximum of 10,000 requests of this kind per day. Refer to the Rate limiting section for the complete list of the request limitations in Toloka API.

You can't use one request to pass multiple bonuses with the same price, name, and message to the same annotator. A response with the status 409 will be returned.

Sample error with HTTP status code 409

Request

Tip

Try our new API reference: more parameter details, request/response examples, and code samples in various programming languages, including the Toloka-Kit usage samples.

Production version
Sandbox
POST https://toloka.dev/api/v1/user-bonuses
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

Headers

TitleOverview
AuthorizationA token for account authorization. Add OAuth as a prefix.
Content-TypeSpecifies the data format in the request body.

Query parameters

Specified in the link after the question mark; separated by &.

ParameterOverview
async_mode

boolean

Mode for request processing:

  • true — Asynchronous. Creates an asynchronous operation that runs in the background. The response contains information about the operation (start and completion time, status, number of bonuses).
  • false — Synchronous. The response contains information about bonuses issued. Maximum of 100 bonuses per request.

    The default value is false.
assignment_idstring

ID of the Toloker's response to the task a bonus is issued for.
skip_invalid_items

boolean

Validation parameters for JSON objects:

  • true — Issue a bonus if the JSON object with bonus information passed validation. Otherwise, skip the bonus.
  • false — Stop the operation and don't issue bonuses if at least one JSON object didn't pass validation.

    The default value is false.
operation_idstring

Operation ID. Can be used for any method of request processing.

Request body

{
"user_id": "21c4f092ebad180cf56b9babe0ef9f19",
"amount": 1.5,
"assignment_id": "6946cefa-32af-4f62-b530-8d2c71fa2966",
"private_comment": "Good job!",
"public_title": {
"EN": "Completed tasks"
},
"public_message": {
"EN": "10 tasks successfully completed"
},
"without_message": false
}
ParameterOverview
user_idstring

Required parameter. Toloker ID.
amountfloat

Required parameter. The dollar amount of the bonus.
assignment_idstring

ID of the Toloker's response to the task a bonus is issued for.
private_commentstring

Comments that are only visible to the requester.
public_titleobject

The subject of the message for the Toloker. You can enter it in multiple languages (the message will be sent in the Toloker's language). Format: "<language RU/EN/TR/ID/FR>": "<title text>".
public_messageobject

The text of message for the Toloker. You can enter it in multiple languages (the message will be sent in the Toloker's language). Format: "<language RU/EN/TR/ID/FR>": "<message text>".
without_messageboolean

Allows you not to send a bonus message to the Toloker. The default value is false.

To issue a bonus without a message, specify null for public_title and public_message and true for without_message.

Response

The response format depends on the value of async_mode.

Information about bonuses (async_mode=false)
Information about the operation (async_mode=true)
{
"items": {
"0": {details of a bonus #0},
"2": {details of a bonus #2},
"<N>": {details of a bonus #N}
},
"validation_errors": {
"1": {validation errors for a bonus #1},
"3": {validation errors for a bonus #3},
"<N>": {validation errors for a bonus #N}
}
}
ParameterOverview
itemsstring

Object with information about bonuses issued.
validation_errorsstring

An object with validation errors. Returned if the request has the parameter skip_invalid_items=true.
Contact support
Toloka API
OverviewAccessing the APIRate limiting
Quick start
Reference
Project
Pools
Training
Subscriptions to events
Toloker selection
Ways to upload tasks
Tasks
Task suites
Tracking operations
Getting responses
Checking completed tasks
Bonuses
Messages for Tolokers
Various parameters
Libraries