Reference of all API calls available. Consult also the concepts documentation and the Swagger documentation available for the interactive version of the API.
In order to submit work to Clickworker through the API, the customer must provide information on how his request is structured and in which form results are expected back. For example, one customer might want to order a text using our TextCreate product, which should be structured using a title section and a content section, while another customer might need the text to be structured using title, abstract, and content sections.
Similarly, one customer might provide a list of URLs of company websites when using our product AddressResearch, while another customer might supply the company name and address for verification using the AddressResearch product.
TaskTemplates are used to define input and result structures, as well as to specify additional parameters required to fulfill a task, such as the target language for an article. For each input and result field, additional options can be supplied to control the presentation of each field. Constraints, such as whether a field is optional or mandatory, can also be supplied.
To summarize, a Task Template serves multiple purposes:
- Select and configure an existing product by using its defined Product Attributes.
- Define how Tasks are presented to the clickworker using Form Elements
- Select or exclude clickworkers from certain Tasks using Clickworker List references.
Attributes
| Name | Type | Access | Description |
|---|---|---|---|
| href | URI | r/- | The unique resource identifier |
| code | String | r/- | The symbolic Task Template code |
| name | String | r/w | A short text helping the customer identify the purpose of the Template |
| titles | Localized String | r/w | A short text used when presenting tasks to clickworkers (either as a list or in detail) |
| descriptions | Localized Text | r/w | A more extensive text containing a task summary that is presented to the clickworker. |
| product | Product | r/w | The referenced product and its configuration |
| form | Form | r/w | The embedded form and its configuration. See Form description (page ff) for details. |
| is_draft | Boolean | r/- | An indicator as to whether any tasks already use this Task Template. |
Representation
- XML Representation (Index view)
<task_templates>
<link href=”[context]/customer/task_templates/${code}”
rel=”self”
type=”application/xml” />
<name>${name}</name>
<product>
<link href=“/api/marketplace/v2/products/${product_code}”
rel=”product”
type=”application/xml” />
</product>
<is_draft>${is_draft}</is_draft>
</task_template>
- XML Representation (Detail View)
<task_templates>
<link href=”[context]/customer/task_templates/${code}”
rel=”self”
type=”application/xml” />
<code>${code}</code>
<name>${name}</name>
<titles>
<$<en|fr|de>>${title}<$<en|de|fr>>
</titles>
<descriptions>
<$<en|fr|de>>${description}</$<en|fr|de>>
</descriptions>
<product>
<link href=”[context]/products/${product_code}” rel=”product”
type=”application/xml” />
<attributes> ... </attributes>
</product>
<form> ... </form>
<is_draft>${is_draft}</is_draft>
</task_template>
- JSON Representation (Index View)
task_templates: [{
link: [{
href: “[context]/customer/task_templates/${code}”,
rel: “self”,
type: “application/json”
}],
name: “${name}”,
product: {
link: [{
href: “[context]/products/${product_code}”,
rel: “product”,
type: “application/json”
}],
},
is_draft: ${is_draft}
}]
- JSON Representation (Detail View)
task_template: {
link: [{
href: “[context]/customer/task_templates/${code}”,
rel: “self”,
type: “application/json”
}],
code: “${code}”,
name: “${name}”,
titles: {
”$<de|en|fr|...>”: “${title}”
},
descriptions: {
”$<de|en|fr|...>”: “${description}”
},
product: {
link: [{
href: “[context]/products/${product_code}”,
rel: “product”,
type: “application/json”
}],
attributes: [ ... ]
},
form: [ ... ],
is_draft: ${is_draft}
}
Operations
Index Registered Task Templates
Indexing registered Task Templates will produce a brief overview.
Request
Request line:
GET [context]/customer/task_templates/
Request parameter: (none)
Response
Response status:
- 200, if the request was successfully processed, even if no Task Templates were found
XML Example
<task_templates_response>
<request_status>...</request_status>
<task_templates>
<link
href=“/api/marketplace/v2/customer/task_templates/translate”
rel=”task_template” type=”application/xml” />
<name>Übersetzungstemplate</name>
<product>
<link href=“/api/marketplace/v2/products/TextCreate”
rel=”product” type=”application/xml”/>
<is_draft>false</is_draft>
</task_templates>
</task_templates_response>
JSON Representation
task_templates_response: {
request_status: ... ,
task_templates: [{
link: [{
href:“/api/marketplace/v2/customer/task_templates/translate”,
rel: “task_template”,
type: “application/json”
}],
name: “Übersetzungstemplate”,
product: {
link: [{
href: “/api/marketplace/v2/products/TextCreate”,
rel: “product”,
type: “application/json”
}]
},
is_draft: false
}]
}
Create a new Task Template
Request
Request line:
POST [context]/customer/task_templates/
Request parameter: (none)
JSON Example
task_template: {
code: “tpl_text_create_keywords_en”,
name: “Standard Text Creation Template (English)”,
titles: {
en: “Please write a message with keywords”
},
descriptions: {
en: “You are required to write a short English message, containing at least 50 words, with a keyword in it.”
},
product: {
link: [{
href: “/api/marketplace/v2/products/TextCreateWithKeywords”
rel: “product
type: “application/json”
}],
attributes: [{
code: “textcreatewithkeywords_language”,
value: “en”
},{
code: “textcreatewithkeywords_text_length”,
value: “10#55”
},{
code: “textcreatewithkeywords_proof_read”,
value: “textcreate_proof_no”
}]
},
form: {
“elements“: [
{
type: “text_field”,
titles: {
en: “Topic”
},
item_code: “topic”,
is_output: false
},{
type: “text_area”,
titles: {
en: “Your Message”
},
item_code: “result”,
is_output: true,
is_mandatory: true,
options: [{
code: “min_length”,
value: “50”
},{
code: “max_length”,
value: “150”
}],
},{
type: “keyword”,
item_code: “keyword_a”,
is_output: false,
is_mandatory: true,
options: [{
code: “min_occurrence_ref”,
value: “keyword_a_min”
},{
code: “max_occurrence_ref”,
value: “keyword_a_max”
},{
code: “reference_code”,
value: “all”
}]
}]
}
}
Response
Response status:
- 200, if the Task Template was successfully created
- 409, if a Task Template of the given code already exists
Response body:
(See “View Task Template Details”)
View Task Template Details
Request
Request line:*
GET [context]/customer/task_templates/${code}
Request parameter:
| Name | Type | Synopsis | Mandatory |
|---|---|---|---|
| code | String | The Task Templates code as defined by the customer at the time of creation | Yes |
Response*
Response status:
- 200, if the request was successfully handled
-
404, if the addressed Task Template does not exist
- XML Example
<task_template_response>
<request_status>...</request_status>
<task_template>
<link href=“/api/marketplace/v2/customer/task_templates/
tpl_text_create_keywords_en” rel=”self” type=”application/xml”
/>
<code>tpl_text_create_keywords_en</code>
<name>Standard Text Create Template (English)</name>
<titles>
<en>Please write a SEO message</en>
</titles>
<descriptions>
<en>You are required to write a short English message, containing at least 50 words, with a keyword in it.
</en>
</descriptions>
<product>
<link href=“/api/marketplace/v2/products/TextCreateWithKeywords”
rel=”product” type=”application/xml”/>
<attributes>
<code>textcreatewithkeywords_language</code>
<value>en</value>
</attributes>
<attributes>
<code>textcreatewithkeywords_text_length</code>
<value>10#55</value>
</attributes>
<attributes>
<code>textcreatewithkeywords_proof_read</code>
<value>textcreate_proof_no</value>
</attributes>
</product>
<form>
<elements>
<type>text_field</type>
<titles>
<en>Topic</en>
</titles>
<item_code>topic</item_code>
<is_output>false</is_output>
</elements>
</elements>
<elements>
<type>text_area</type>
<titles>
<en>Your Message</en>
</titles>
<item_code>result</item_code>
<is_output>true</is_output>
<is_mandatory>true</is_mandatory>
<options>
<code>min_length</code>
<value>50</value>
</options>
<options>
<code>max_length</code>
<value>150</value>
</options>
</elements>
<elements>
<type>keyword</type>
<titles>
<en>Keyword A</en>
</titles>
<item_code>keyword_a</item_code>
<is_output>false</is_output>
<is_mandatory>true</is_mandatory>
<options>
<code>min_occurrence_ref</code>
<value>keyword_a_min</value>
</options>
<options>
<code>max_occurrence_ref</code>
<value>keyword_a_max</value>
</options>
<options>
<code>reference_code</code>
<value>all</value>
</options>
</elements>
</form>
</task_template>
</task_template_response>
- JSON Example
task_template_response: {
request_status: { ... },
task_template: {
link: [{href: “/api/marketplace/v2/customer/task_templates/tpl_text_create_keywords_en”,
rel: “self”,
type: “application/json”
}],
product: {
link: [{href: “/api/marketplace/v2/products/TextCreateWithKeywords”
rel: “product
type: “application/json”
}],
attributes: [{
code: “textcreatewithkeywords_language”,
value: “en”
},{
code: “textcreatewithkeywords_text_length”,
value: “10#55”
},,{
code: “textcreatewithkeywords_proof_read”,
value: “textcreate_proof_no”
}]
},
form: {
"elements": [
{
type: “text_field”,
titles: {
en: “Topic”
},
item_code: “topic”,
is_output: false
},{
type: “text_area”,
titles: {
en: “Your Message”
},
item_code: “result”,
is_output: true,
is_mandatory: true,
options: [{
code: “min_length”,
value: “50”
},{
code: “max_length”,
value: “150”
}],
},{
type: “keyword”,
item_code: “keyword_a”,
is_output: false,
is_mandatory: true,
options: [{
code: “min_occurrence_ref”,
value: “keyword_a_min”
},{
code: “max_occurrence_ref”,
value: “keyword_a_max”
},{
code: “reference_code”,
value: “all”
}]
}
]
}
}
Update Task Template
Request
Request line:
PUT [context]/customer/task_templates/${code}
Request parameter:
| Name | Type | Synopsis | Mandatory |
| code | String | The Task Templates code as defined by the customer at the time of creation | yes |
Request body:
- JSON Example
task_template: {
name: “Standard Text Creation Template (English)”,
titles: {
en: “Please write a message with keywords”
},
descriptions: {
en: “You are required to write a short English message, containing at least 50 words, with a keyword in it.”
}
}
Response
Response status:
- 200, if the Task Template was successfully updated
- 409, if a Task Template has invalid attributes
Response body: (See “View Task Template Details” on page 40 for examples)
Delete a Task Template
When deleting a Task Template, it must not be in use by any Task (regardless of the Task’s state).
Request
Request line:
DELETE [context]/customer/task_templates/${code}
or
POST [context]/customer/task_templates/${code}?_method=DELETE
Request parameter:
| Name | Type | Synopsis | Mandatory |
| code | String | The Task Template’s code, as defined by the customer at the time of creation | yes |
Request body: (Empty)
Response
Response status:
- 204, if the request could be successfully handled
- 404, if the given resource was not found
- 409, if the Task Template is in use by Tasks.
Response body: (Empty)
Add Clickworker to Task Template blacklist
Clickworkers on the blacklist are not allowed to work on this task. When removing the valid_until parameter the Clickworker will stay on the blacklist indefinitely.
Request
Request line:
PUT [context]/customer/task_templates/${code}/blacklist
Request parameter:
| Name | Type | Synopsis | Mandatory |
| code | String | The Task Templates code as defined by the customer at the time of creation |
Request body:
- JSON Example
blacklist: {
clickworker_ids: [36, 40],
valid_until: “201 7 - 06 - 13”
}
Response
Response status:
- 200, if the Clickworkers were successfully added to the blacklist
Response body: (Empty)