Step 2 on how to place an order using the API.

Step 2 - Submit a Task

Once the TaskTemplate has been defined, you are ready to submit new tasks. The structure of the XML document carrying the task data must fit to the corresponding Task-template. However there are some elements that need to be part of every task-creation process.

Task - common elements

  • XML
<task>
  <customer_ref>[CUSTOMER ID]</customer_ref>
  <template>
    <link href="/api/marketplace/v2/customer/task_templates/[TEMPLATE CODE]"
rel="task_template" type="application/xml" />
  </template>
  <notifications>
    <event>CUSTOMER_INPUT_REQUIRED</event>
    <callback_url>http://notification.example.com</callback_url>
    <callback_method>POST</callback_method>


    <payload_format>XML</payload_format>
  </notifications>
  <notifications>
    <event>TASK_COMPLETED</event>
    <callback_url>http://notification.example.com</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
  </notifications>
</task>
  • <customer_ref> This is an element to carry an identifier, which the customer may need for his own reference. This identifier will be included in each task output as it is.

  • <template> As described in 3.1.3 the Task-template defines the structure of the input and the output data. Therefore the task itself must reference the Task-template it is designed for. As shown in 3.1.4 during the project setup process a Task-template is uploaded via API. Within this the customer has filled the <code> element with an unique identifier of the template. This identifier needs to be added to the common path:

  • XML
<template>
  <link
href="/api/marketplace/v2/customer/task_templates/ **unqiue_template_id_1234** "
rel="task_template" type="application/xml" />
</template>
  • <notifications> The final task configuration value offers the customer the option to be notified via a http POST call about the state of the task adaption. During the editing process of the task on the clickworker platform the task passes several states. These state changes are indicated by two different events. The customer can define for each of these events an URL which will be automatically called when this event occurs:
1. TASK_COMPLETED
This event is triggered when all work related to the task, including the customer’s
review, has been completed.
2. CUSTOMER_INPUT_REQUIRED
This event is triggered when the customer needs to approve the task results.

Part of this notification will be a payload carrying the results of the task. See 3.2.3 for details.

Task-template specific elements

Now the task specific input data for an individual task needs to be added. As shown in the Task-template in 3.1.4 the <form> element defines an input item with the <item_code> given as ‘link_to_hotel’:

  • XML
<elements>
  <is_output>false</is_output>
  <titles>
    <de>Hotel-URL</de>
    <en>Hotel URL</en>
  </titles>
  <is_mandatory>true</is_mandatory>
  <type>url</type>
  <item_code>link_to_hotel</item_code> 
  <sort_order>10</sort_order>
</elements>

In this example this input data is needed by the clickworker to fulfil the task. This input element needs to be referenced by its item code within the XML document carrying the task data:

  • XML
<input>
  <items>
    <code>link_to_hotel</code>
    <content>http://www.myhotel.com</content>
  </items>
</input>

Putting it all together

The structure of the XML document carrying the task data the customer needs to upload would look like this:

  • XML
<task>
  <customer_ref>[CUSTOMER ID]</customer_ref>
  <template>
    <link href="/api/marketplace/v2/customer/task_templates/[TEMPLATE CODE]"
rel="task_template" type="application/xml" />
  </template>
  <input>
    <items>
      <code>link_to_hotel</code>
      <content>http://www.myhotel.com</content>
    </items>
  </input>
  <notifications>
    <event>CUSTOMER_INPUT_REQUIRED</event>
    <callback_url>http://notification.example.com</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
  </notifications>
  <notifications>
    <event>TASK_COMPLETED</event>
    <callback_url>http://notification.example.com</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
  </notifications>
</task>

Send this XML document as a HTTP-POST request to https://.clickworker.com/api/marketplace/v2/customer/tasks. As we strongly recommend to test the setup first on the sandbox environment the placeholder should be ‘sandbox’ (for production this would be ‘api’).

The response to this API-Request will be a http-status code:

  • 200 , if the task was successfully created
  • 400, if the referenced Task-template does not exist

and a response body:

  • XML
<?xml version="1.0"?>
<task_response>
  <request_status>
    <id>gl1ZwYiU/BXh1+UYxn/9yoiCSLE=</id>
    <valid>true</valid>
    <status_code>200</status_code>
    <status_text>OK</status_text>
  </request_status>
  <task>
  <link
href="https://sandbox.clickworker.com/en/api/marketplace/v2/customer/tasks/240581
0" rel="self" type="application/xml"/>
**<id>2405810</id>**
  <customer_ref>[CUSTOMER ID]</customer_ref>
  <template>
    <link
href="https://sandbox.clickworker.com/en/api/marketplace/v2/customer/task_templ
ates/[TEMPLATE CODE]" rel="self" type="application/xml"/>
    <product>
      <link
href="https://sandbox.clickworker.com/en/api/marketplace/v2/products/TextCreat
e" rel="self" type="application/xml"/>
    </product>
  </template>
  <net_amount>[€]</net_amount>
  <tax_amount>[€]</tax_amount>
  <amount>[€]</amount>
  <currency>EUR</currency>
  <state>queued</state>
  <inputs>
    <code>link_to_hotel</code>
    <content>http://www.myhotel.com</content>
  </inputs>
  <notifications>
    <link href=
"https://sandbox.clickworker.com/api/marketplace/v2/customer/tasks/2405811/noti
fications/19265" rel="self" type="application/xml"/>
    <event>CUSTOMER_INPUT_REQUIRED</event>
    <callback_url>http://notification.example.com</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
  </notifications>
  <notifications>
    <link href=
"https://sandbox.clickworker.com/api/marketplace/v2/customer/tasks/2405811/noti
fications/1926 6 " rel="self" type="application/xml"/>
    <event>TASK_COMPLETED</event>
    <callback_url>http://notification.example.com</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
  </notifications>

</task>
</task_response>

As shown above, part of the response is a <id> element. The content of this element will be the reference required for buyoff. It is a unique identifier for this individual task.

Tags: