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

Title	Overview
Authorization	A token for account authorization. Add OAuth as a prefix.
Content-Type	Specifies the data format in the request body.

Query parameters

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

Parameter	Overview
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_id	string 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_id	string 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
}

Parameter	Overview
user_id	string Required parameter. Toloker ID.
amount	float Required parameter. The dollar amount of the bonus.
assignment_id	string ID of the Toloker's response to the task a bonus is issued for.
private_comment	string Comments that are only visible to the requester.
public_title	object 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_message	object 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_message	boolean 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}
  }
}

Parameter	Overview
items	string Object with information about bonuses issued.
validation_errors	string An object with validation errors. Returned if the request has the parameter `skip_invalid_items=true`.

Contact support

Toloka API

Overview Accessing the API Rate limiting

Quick start

Reference

Project

Pools

Training

Subscriptions to events

Toloker selection

Ways to upload tasks

Tasks