Issue rewards

Attention

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

Issues rewards to Tolokers.

The size of the reward 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 rewards 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

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 rewards). `false` — Synchronous. The response contains information about rewards issued. Maximum of 100 rewards per request. The default value is `false`.
assignment_id	string ID of the Toloker's response to the task a reward is issued for.
skip_invalid_items	boolean Validation parameters for JSON objects: `true` — Issue a reward if the JSON object with reward information passed validation. Otherwise, skip the reward. `false` — Stop the operation and don't issue rewards 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 reward.
assignment_id	string ID of the Toloker's response to the task a reward 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 reward message to the Toloker. The default value is `false`. To issue a reward 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 rewards (async_mode=false)

Information about the operation (async_mode=true)

{
  "items": {
    "0": {details of a reward #0},
    "2": {details of a reward #2},
    "<N>": {details of a reward #N}
  },
  "validation_errors": {
    "1": {validation errors for a reward #1},
    "3": {validation errors for a reward #3},
    "<N>": {validation errors for a reward #N}
  }
}

Parameter	Overview
items	string Object with information about rewards 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