Marketplace API Concepts

How to host your own iframe-task

Customer Documentation

© 2017 clickworker GmbH.

Many people use clickworker to host their projects on the clickworker platform. In most cases these projects were developed and hosted on the clickworker servers.

But in some cases our customers already have an existing platform where people can work on a specific task and submit the result. If you are planning to reuse your existing solution and just want to have more people working on it then this is also possible with the clickworker platform.

The external HTML-form will be rendered inside an iframe so that our users can work on it without leaving the platform which they already know. This document describes how to integrate a custom HTML-form that is hosted on your servers into the clickworker workspace.

The complete process works as follows:

1. Create a task template using our ExternalForm product where you specify the target crowd (country, age, gender).

2. Create one task for each job that needs to be completed inside your form.

3. After a Clickworker submits your form send us a postback to let us know that the Clickworker has completed the task.

4. Review (optional)

Regarding Reviews:

When setting up the project you can specify to review every result or not.

If you choose to do an explicit review then you have seven days to approve or decline a Clickworker submission. In case you decline the result then the Clickworker will not get paid.

If you choose not to review results then all submissions will be accepted immediately and the Clickworker will be paid.

Now we will go over each step in more detail, providing some example requests.

1. Create a task template:

POST https://sandbox.clickworker.com/api/marketplace/v2/customer/task_templates

<task_template> 
  <code>my_project</code> 
  <name>Web-Recherche</name> 
  <titles>
    <de>Make some google searches</de>
    <en>Make some google searches</en> 
  </titles>
  <descriptions>
    <de>Hier sollte Ihr Briefing für die clickworker stehen.</de>
    <en>Here you should describe what the clickworker has to do.</en> </descriptions>
  <product>
  <link href="/api/marketplace/v2/products/ExternalForm" rel="product" type="application/xml"/>
  <attributes> 
    <code>external_form_country</code> 
    <value>de</value>
  </attributes> 
  <attributes>
    <code>external_form_payment</code> 
    <value>100</value>
  </attributes> 
  <attributes>
    <code>external_form_age_from</code>
    <value>20</value> 
  </attributes> 
  <attributes>
    <code>external_form_age_to</code>
    <value>60</value> 
  </attributes> 
  <attributes>
    <code>external_form_gender</code>
    <value>a</value> </attributes> <attributes>
    <code>external_form_with_buyoff</code>
    <value>yes</value> 
  </attributes>
  </product> 
  <form>
    <elements> 
      <is_output>false</is_output> 
      <titles>
        <de>iframe_url</de>
        <en>iframe_url</en>
      </titles> 
    <is_mandatory>true</is_mandatory> 
    <type>hidden</type> 
    <item_code>iframe_url</item_code> 
    <sort_order>10</sort_order>
  </elements> </form>
</task_template>

In the code-property you need to set a unique id for your template. In this case we set it to „my_project“.

You can configure different attributes to specify your target crowd:

• external_form_country (mandatory)
With this you can choose the country where our Clickworkers need to be located to participate in your project. For a list of available country-codes you can perform a GET request on the product itself: https://api.clickworker.com/api/marketplace/v2/products/ExternalForm.

• external_form_payment (mandatory)
Here you enter the Clickworker’s fee to participate in your project. We will add 40% to the amount for your invoice. Please offer a reasonable fee to make sure Clickworker’s are motivated to participate. The number will be interpreted as Cent (1/100) from your configured customer currency. 


• external_form_age_from (mandatory)
Here you can enter the minimum age of the Clickworker’s to participate (18-99). 


• external_form_age_to (mandatory)
Here you can enter the maximum age of the Clickworker’s to participate (18-99). 


• external_form_gender (optional)
Here you can enter the requested gender of the Clickworkers to participate. Valid values are f (female) and m (male) or a (all).

• external_form_with_buyoff (mandatory) If you set buyoff to no then the results are accepted automatically and the Clickworker gets paid immediately. If you set it to yes then you have seven days to review the results and call our accept/reject endpoints. After seven days the results are accepted automatically.

• external_form_timeout (optional) If you set this to some value (in seconds) than all tasks should be completed within this time value after task creation - after that the tasks will be canceled.

• external_form_max_jobs (optional) By default there is one job per task. When setting this attribute with a number, then external_form_max_jobs per task will be created. Workers can work in parallel on each of these jobs.

• external_form_team_blacklist (optional) Users from blacklist (team) will be excluded from the project. 


• external_form_team_whitelist (optional) Users from whitelist (team) will be included in the project. If no demography is provided, then only the users on the whitelist can participate. 


2. Create tasks

Now a task template is created with the basic project information. The next step is to let the system know how many Clickworkers should participate on the project. To do this it is necessary to create on task for each required submission. So if 1000 submissions are required then it is necessary to create 1000 tasks:

POST https://sandbox.clickworker.com/api/marketplace/v2/customer/tasks

<task> 
  <customer_ref></customer_ref>
  <template>
    <link href="/api/marketplace/v2/customer/task_templates/my_project"
rel="task_template" type="application/xml" /> 
  </template>
  <input> 
    <items>
      <code>iframe_url</code>
      <content>http://my-iframe-url.com</content> 
    </items>
  </input> 
</task>

Make sure that you set the correct task template id here. In our case we used „my_project“ as we specified while creating our task template.

This is also the place where you specify the url to your iframe. If necessary you can set a different url for each task. If all Clickworkers should use the same url then the request-body is always the same.

When we show the iframe to the clickworkers, we will append two parameters to the url:

• task_id

• user_id

• job_id (if external_form_max_jobs was set)

These parameters are required for the following requests. So you should store these somehow in your system.

3. Send postback

After the clickworker has completed the form on your server, you have to call a postback url to let us know about the finished task.

Call this url as soon as the clickworker submitted the results (insert the task_id which was appended to the iframe):

POST https://sandbox.clickworker.com/api/marketplace/v2/customer/tasks/[TASK_ID]/external_submit

<submit> 
  <clickworker_id>2</clickworker_id>
</submit>

4. (Optional) Review results

If you set external_form_with_buyoff to yes in the task template then you have seven days to review the results. After the seven days the results are accepted automatically and the Clickworker gets paid.

To accept the results you need to call the following url:

PUT https://sandbox.clickworker.com/api/marketplace/v2/customer/tasks/[TASK_ID]/accept

<accept>
  <description>Well done!</description>
</accept>

The description is optional and will be shown to the clickworker.

To reject the results and to not pay the clickworker you can call:

PUT https://staging-hgv4.clickworker.com/api/marketplace/v2/customer/tasks/[TASK_ID]/reject

<reject>
  <description>Well done!</description>
</reject>

For the reject call the description is mandatory and should include the reason why the task was rejected and additional tipps for the Clickworker.