Skills

A skill is an assessment of some aspect of a user's responses (a number from 0 to 100). You can set up skill calculation in a quality control rule, or manually set the skill level for a user. The skill can be used for selecting users to complete tasks in a pool.

A sample of skill properties in JSON with key descriptions is shown below.

You can use the API for performing the following operations with skills:

Sample skill in JSON

{
   "id":"79",
   "name":"Image identification",
   "private_comment": "Skill for my pool",
   "hidden":true,
   "training":true,
   "skill_ttl_hours": 240,
   "created":"2016-09-14T08:22:34.595"
}

Keys

Key

Value

Data type

Required during creation

id

Skill ID.

String

Not used

name

Skill name.

String

Yes

private_comment

Comments on the skill (only visible to the requester).

String

No

hidden

Access to information about the skill (the name and value) for users:

  • true — closed

  • false — open

The default value is true.

Boolean

No

training

Whether the skill is related to a training pool:

  • true — The skill level is calculated from training pool tasks.

  • false — The skill isn't related to a training pool.

Boolean

No

skill_ttl_hours

The skill's "time to live" after the last update (in hours). The skill is removed from the user's profile if the skill level hasn't been updated for the specified length of time.

Integer

No

created

The UTC date and time when the skill was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

Not used

Create a skill

To create a skill, send a POST request to the /skills resource. You can send a maximum of 10 requests of this kind per minute and 100 requests per day.

Request

POST /api/v1/skills
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

{
 "name": "Image markup",
 "private_comment": "Skills for my pool",
 "hidden": false,
 "training":true,
 "skill_ttl_hours": 240
}
Key descriptions

Key

Value

Data type

Required during creation

name

Skill name.

String

Yes

private_comment

Comments on the skill (only visible to the requester).

String

No

hidden

Access to information about the skill (the name and value) for users:

  • true — closed

  • false — open

The default value is true.

Boolean

No

training

Whether the skill is related to a training pool:

  • true — The skill level is calculated from training pool tasks.

  • false — The skill isn't related to a training pool.

Boolean

No

skill_ttl_hours

The skill's "time to live" after the last update (in hours). The skill is removed from the user's profile if the skill level hasn't been updated for the specified length of time.

Integer

No

Response

Contains the skill properties and ID:

{
  "name" : "Identifying elephant color",
  "hidden" : true,
  "training":true,
  "skill_ttl_hours": 240
  "id" : "1",
  "created" : "2016-04-12T13:56:53.629"
  
}
Key descriptions

Key

Value

Data type

Required during creation

name

Skill name.

String

Yes

hidden

Access to information about the skill (the name and value) for users:

  • true — closed

  • false — open

The default value is true.

Boolean

No

training

Whether the skill is related to a training pool:

  • true — The skill level is calculated from training pool tasks.

  • false — The skill isn't related to a training pool.

Boolean

No

skill_ttl_hours

The skill's "time to live" after the last update (in hours). The skill is removed from the user's profile if the skill level hasn't been updated for the specified length of time.

Integer

No

id

Skill ID.

String

Not used

created

The UTC date and time when the skill was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

Not used

Edit a skill

To change the name, comments, or access level of a skill, send a PUT request to the resource /skills/<skill ID>.

Request

PUT /api/v1/skills/<skill ID>
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

{
  "name" : "Identifying elephant color",
  "private_comment": "Skill for my pool"
}
Key descriptions

Key

Value

Data type

Required during creation

name

Skill name.

String

Yes

private_comment

Comments on the skill (only visible to the requester).

String

No

Response

Contains the changed skill properties in JSON.

Get the list of skills

To get the list of created skills, send a GET request to the /skills resource.

Request

GET /api/v1/skills ?
  [status=<skill name>]
& [limit=<maximum number of results in the response>]
& [sort=<fields to sort by>]
& [id_gt=<skill ID>]
& [id_gte=<skill ID>]
& [id_lt=<skill ID>]
& [id_lte=<skill ID>]
& [created_gt=<date>]
& [created_gte=<date>]
& [created_lt=<date>]
& [created_lte=<date>]

Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>    
Request parameters

Parameter

Description

Data type

Required during creation

name

Skill name.

String

No

limit

Limit on the number of results to return. By default — 20; maximum — 300.

String

No

sort

Parameters for sorting in ascending order:

  • id — Skill ID.

  • created — Date the skill was created, in UTC in the format YYYY-MM-DD.

You can set multiple comma-separated parameters.

To change the sorting direction to descending, add the minus sign before the parameter. For example, sort=-id.

String

No

id_gt

Skills with an ID greater than the specified value.

String

No

id_gte

Skills with an ID greater than or equal to the specified value.

String

No

id_lt

Skills with an ID less than the specified value.

String

No

id_lte

Skills with an ID less than or equal to the specified value.

String

No

created_gt

Skills created after the specified date. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

created_gte

Skills created on or after the specified date. The date is in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

created_lt

Skills created before the specified date. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

created_lte

Skills created before or on the specified date. The date is in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

To get the list of skills in parts (for example, 10 skills at a time), use a combination of parameters in requests:

GET /api/v1/skills?sort=id&limit=10
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>
GET /api/v1/skills?sort=id&limit=10&id_gt=<last skill ID from the previous request>
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>

Response

Contains a list of skills and their properties in the items array:

{"items" : [{свойства навыка 1}, {свойства навыка 2}, ... {свойства навыка n}], "has_more": false}

Get information about a skill

To get information about a skill, send a GET request to the resource / skills/<skill ID>.

Request

GET /api/v1/skills/<skill ID>
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>

Response

Contains skill properties in JSON format. Example:

{
  "name" : "Identifying elephant color",
  "hidden" : true,
  "training":true,
  "skill_ttl_hours": 240
  "id" : "1",
  "created" : "2016-04-12T13:56:53.629"
  
}
Key descriptions

Key

Value

Data type

Required during creation

name

Skill name.

String

Yes

hidden

Access to information about the skill (the name and value) for users:

  • true — closed

  • false — open

The default value is true.

Boolean

No

training

Whether the skill is related to a training pool:

  • true — The skill level is calculated from training pool tasks.

  • false — The skill isn't related to a training pool.

Boolean

No

skill_ttl_hours

The skill's "time to live" after the last update (in hours). The skill is removed from the user's profile if the skill level hasn't been updated for the specified length of time.

Integer

No

id

Skill ID.

String

Not used

created

The UTC date and time when the skill was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

Not used

Set the skill value

To set the skill value for a user, send a PUT request to the /user-skills resource. You can send a maximum of 100,000 requests of this kind per day.

Request

PUT /api/v1/user-skills
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth-токен>
Content-Type: application/JSON

{
  "skill_id": "32",
  "user_id": "566ec2b0ff0deeaae5f9d500",
  "value": 59.7
}
Key descriptions

Key

Value

Data type

Required during creation

skill_id

Skill ID.

String

Yes

user_id

User ID.

String

Yes

value

Fractional value of the skill. Minimum - 0, maximum - 100.

Floating-point number

Yes

Response

Contains the updated value for the skill:

{
  "id": "43",
  "skill_id": "32",
  "user_id": "566ec2b0ff0deeaae5f9d500",
  "value": 60,
  "exact_value": 59.7,        
  "created": "2016-03-25T15:59:08"
}
Key descriptions

Key

Value

Data type

Required during creation

id

ID of the user's skill, assigned to the “skill-user” pair.

String

No

skill_id

Skill ID.

String

Yes

user_id

User ID.

String

Yes

value

The integer value of that skill (exact_value, rounded to the nearest integer). Minimum - 0, maximum - 100.

Number

Yes

exact_value

Fractional value of the skill. Minimum - 0, maximum - 100.

Floating-point number

No

created

The date and time in UTC when the user was first assigned the skill with the specified value. It uses ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

Not used

Get a list of user skills

To get a list of a user's skills, send a GET request to the /user-skills resource.

Request

GET /api/v1/user-skills ?
  [skill_id=<skill ID>]
& [user_id=<user ID>]
& [limit=<maximum number of results in the response>]
& [sort=<fields to sort by>]
& [id_gt=<skill ID>]
& [id_gte=<skill ID>]
& [id_lt=<skill ID>]
& [id_lte=<skill ID>]
& [created_gt=<date>]
& [created_gte=<date>]
& [created_lt=<date>]
& [created_lte=<date>]
& [modified_gt=<date>]
& [modified_gte=<date>]
& [modified_lt=<date>]
& [modified_lte=<date>]

Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>    
Request parameters

Parameter

Description

Data type

Required

user_id

User ID.

String

No

skill_id

Skill ID.

String

No

limit

Limit on the number of results to return. By default — 20; maximum — 300.

String

No

sort

Parameters for sorting in ascending order:

  • id — Skill ID.

  • created — Date the skill was created, in UTC in the format YYYY-MM-DD.

You can set multiple comma-separated parameters.

To change the sorting direction to descending, add the minus sign before the parameter. For example, sort=-id.

String

No

id_gt

Skills with an ID greater than the specified value.

String

No

id_gte

Skills with an ID greater than or equal to the specified value.

String

No

id_lt

Skills with an ID less than the specified value.

String

No

id_lte

Skills with an ID less than or equal to the specified value.

String

No

created_gt

Skills created after the specified date. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

created_gte

Skills created on or after the specified date. The date is in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

created_lt

Skills created before the specified date. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

created_lte

Skills created before or on the specified date. The date is in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

No

modified_gt Skills changed after the specified date. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. String No
modified_gte Skills created on or after the specified date. The date is in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. String No
modified_lt Skills that changed before the specified date. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. String No
modified_lte Skills that changed before the specified date. The date is in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. The date is specified in UTC in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss]. String No

To get the list of user skills in parts (for example, 10 skills at a time), use a combination of parameters in requests:

GET /api/v1/user-skills?sort=id&limit=10
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>
GET /api/v1/user-skills?sort=id&limit=10&id_gt=<last skill ID from the previous request>
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>

Response

Contains properties of user skills in the items array:

{"items" : [{<свойства навыка пользователя 1>}, {<свойства навыка пользователя 2>}, ... {<свойства навыка пользователя n>}], "has_more": false}

Get a user's skill value

To get the user's skill value, send a GET request to the resource /user-skills/<user skill ID>.

Request

GET /api/v1/user-skills/<user skill ID>
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>

Response

The response contains the properties and value of the skill in JSON:

{
  "id": "43",
  "skill_id": "32",
  "user_id": "566ec2b0ff0deeaae5f9d500",
  "value": 60,
  "exact_value": 59.7,
  "created": "2016-03-25T15:59:08",
  "modified" : 2017-07-24T16:32:41.386
}
Key descriptions

Key

Value

Data type

Required during creation

id

ID of the user's skill, assigned to the “skill-user” pair.

String

No

skill_id

Skill ID.

String

Yes

user_id

User ID.

String

Yes

value

The integer value of that skill (exact_value, rounded to the nearest integer). Minimum - 0, maximum - 100.

Number

Yes

exact_value

Fractional value of the skill. Minimum - 0, maximum - 100.

Floating-point number

No

created

The date and time in UTC when the user was first assigned the skill with the specified value. It uses ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

Not used

modified

The date and time in UTC when the user's skill level changed. It uses ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

String

Not used

Remove a skill for a user

To remove a skill for a user, send the DELETE request to the /user-skills resource.

Request

GET /api/v1/user-skills/<user skill ID>
Host: https://sandbox.toloka.yandex.ru
Authorization: OAuth <OAuth token>