Reference of all API calls available. Consult also the concepts documentation and the Swagger documentation available for the interactive version of the API.

A Task represents a specific work item (payload of work) to be processed and delivered by clickworkers, such as a test to be written, or a single address to be researched. Before a task can be submitted, a Task Template must be defined, specifying the details of how the task should be fulfilled. While the Task Template defines aspects that are common to all Tasks (like selected product, input form, etc.) a Task carries the actual payload. The Task’s data can roughly be separated into two sections:

  1. Instructional data is the input presented to the clickworker (like text to translate, keywords, instructions, etc.)
  2. Result fields contain the final results of the task resolution (like translated text, created text, research results)

Attributes

Name Type Access Description
id Integer r/- The Task identifier
href URI r/- The Task’s unique resource identifier
Cloned_task URI r/- Show the cloned task if presend
customer_ref String r/w The customer may use this attribute to transport internal references.
template URI r/- The Task Template’s unique resource identifier. Contains a reference to the selected product.
amount numeric r/- The amount after tax in the customer’s currency for this task. Price may vary depending on the input parameters (e.g. length of text, quality assurance, etc.)
currency String r/- The ISO currency symbol for all amount data
net_amount numeric r/- The amount before tax in the customer’s currency for this task. Price may vary depending on the input parameters (e.g. length of text, quality assurance, etc.)
tax_amount numeric r/- The tax amount for this Task
state String r/w The current Task state. See section “Task States” for details.
input List r/c A list of items to be used as input data. Every item has two attributes:
1. The item’s code (item_code)
2. The item’s content (item_content)
result List r/- A list of items to be used as result data. Every item has two attributes:
1. The item’s code (item_code)
2. The item’s content (item_content)
Notifications (optional) List r/c A list of notification instances to automatically register after Task creation (see section Notify Clickworkers).
progress_logs List r/- A record of the Task’s progress. Every entry provides a timestamp (log_timestamp) and a code (log_code), suitable for automatic processing.

Task Result Additions

The result attribute contains input that was created by clickworkers using the Form Elements defined by the associated Task Template. In addition, service and statistical information may be added by the system.

Task States

The Task State indicates the current status of the Task. It is derived from a more extensive set of internal states but mapped to the following “public” states:

  • Unconfirmed: The task has been created but needs to be confirmed by the customer.
  • Confirmed: The task has been confirmed by the customer and is ready for queuing.
  • Queued: The task is waiting for clickworkers to apply for the associated jobs
  • Running: Clickworkers are currently working on the task’s jobs.
  • Cancelled: The task has been cancelled by the customer
  • Feedback: The task requires feedback – such as a buyoff by the customer.
  • Finished: The task is finished and contains the result data.
  • Deleted: The task has been marked as deleted and will not be listed in index requests any more. However, it is still available as long as it is referenced by other entities, likes Jobs or Notifications.

Representation

  • XML Representation (detail view)
<task>
  <link href=”[context]/customer/tasks/${id}” rel=”self”
    type=”application/xml” />
  <id>${id}</id>
  <customer_ref>${customer_ref}</customer_ref>
  <template>
    <link href=”[context]/customer/task_templates/${template}”
      rel=”template”
      type=”application/xml” />
    <product>
      <link href=”[context]/products/${product_code}” rel=”product”
        type=”application/xml” />
    </product>
  </template>
  <net_amount>${net_amount}</net_amount>
  <tax_amount>${tax_amount}</tax_amount>
  <amount>${amount}</amount>
  <currency>${currency}</currency>
  <state>${state}</state>
  <input>
    <items>
      <code>${item_code}</code>
      <content>${item_content}</content>
    </items>
  </input>
  <result>
    <items>
      <code>${item_code}</code>
      <content>${item_content}</content>
    </items>
  </result>
  <notifications>
    <link href=”[context]/customer/tasks/${task_id}/notifications/${id}” rel=”notifications” type=”application/xml” />
    <events>${event}</events>
    <events>TASK_COMPLETED</events>
    <callback_url>http://notification.example.com/</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
  </notifications>
  <progress_logs>
    <timestamp>${log_timestamp}</timestamp>
    <code>${log_code}</code>
  </progress_logs>
</task>
  • XML Representation (index view)
<tasks>
  <link href=”[context]/customer/tasks/${id}” rel=”self” type=”application/xml” />
  <customer_ref>${customer_ref}</customer_ref}
  <template>
    <link href=”[context]/customer/task_templates/${template}”
      rel=”template”
      type=”application/xml” />
    <product>
      <link href=”[context]/products/${product_code}” rel=”product”
        type=”application/xml” />
    </product>
  </template>
  <state>${state}</state>
</tasks>
  • JSON Representation (detail view)
{
  link: [{
    href: “[context]/customer/tasks/${id}”,
    rel: “self”,
    type: “application/json”
  }],
  id: ${id},
  customer_ref: “${customer_ref}”,
  template: {
    link: [{
      href: ”[context]/customer/task_templates/${template}”,
      rel: “template”,
      type: “application/json”
    }],
    product: {
    link: [{
      href: “[context]/products/${product_code}”,
      rel: “product”,
      type: “application/json”
    }]
  }
  },

  net_amount: ${net_amount},
  tax_amount: ${tax_amount},
  amount: ${amount},
  currency: “${currency}”,
  state: “${state}”,
  input: {
    items: [{
      “code”: “${item_code}”,
      “content”: “${item_content}”
    }]
  },
  result: {
    items: [{
    “code”: “${item_code}”,
    “content”: “${item_content}”
    }]
  },
  notifications: [{
    link: [{
      href:”[context]/customer/tasks/${task_id}/notifications/${id}”,
      rel: “self”,
      type: “application/json”
    }],
    event: “${event}”,
    callback_url: “${callback_url}”,
    callback_method: “${callback_method}”,
    payload_format: “${payload_format}”
  }],
  progress_logs: [{
    timestamp: “${log_timestamp}”,
    code: “${log_code}”
  }]
}
  • JSON Representation (index view)
{
  link: [{
    href: “[context]/customer/tasks/${id}“,
    rel: “self”,
    type: “application/json”
  }],
  customer_ref: “${customer_ref}”,
  template: {
    link: [{
      href: ”[context]/customer/task_templates/${template}”,
      rel: “template”,
      type: “application/json”
    }],
  product: {
    link: [{
      href: “[context]/products/${product_code}”,
      rel: “product”,
      type: “application/json” 
    }]
  }
},
state: “${state}”
}

Operations

List Tasks

Request

Request line:

GET [context]/customer/tasks/

Request parameter:

Name Type Synopsis Mandatory
state String Filters tasks by specified state. List of possible values, see above. No
from Date Filters tasks by created_at attribute from specified date. Expected format is dd.mm.yyyy No
to Date Filters task by created_at attribute to specified date. Expected format is dd.mm.yyyy No
finished_from Date Filters finished tasks by finished_at attribute from specified date. Expected format is dd.mm.yyyy No
finished_to Date Filters finished task by created_at attribute to specified date. Expected format is dd.mm.yyyy No
order_id Date If you are using different projects under one account, these are separated by an order_id. On task creation the order id is returned. No

Request body: (empty)

Response

Response status

  • 200, if the request could be successfully handled (even if no tasks were found)

Response body

- XML Example
  <tasks_response>
  <request_status>...</request_status>
  <tasks>
    <link href=“/api/marketplace/v2/customer/tasks/123” rel=”task”
      type=”application/xml” />
    <customer_ref>translate_run_0</customer_ref>
    <task_template>
      <link
        href=”/api/marketplace/v2/customer/task_templates/tt_default”
        rel=”task_template” type=”application/xml”/>
      <product>
        <link href=“/api/marketplace/v2/products/TextTranslate”
          rel=”product” type=”application/xml”/>
      </product>
    </task_template>
    <state>Running</state>
  </tasks>
  <tasks>
    <link href=“/api/marketplace/v2/customer/tasks/456” rel=”task”
      type=”application/xml” />
    <customer_ref>translate_run_0</customer_ref>
    <task_template>
      <link
       href=”/api/marketplace/v2/customer/task_templates/tt_default”
        rel=”task_template” type=”application/xml”/>
      <product>
        <link href=“/api/marketplace/v2/products/TextTranslate”
        rel=”product” type=”application/xml”/>
      </product>
    </task_template>
    <state>Queued</state>
  </tasks>
</tasks_response>
  • JSON Representation
tasks_response: {
  request_status: ... ,
  tasks: [{
  link: [{
    href: “[context]/customer/tasks/ 123“,
    rel: “task”,
    type: “application/json”
  }],
  customer_ref: “translate_run 0”,
  template: {
    link: [{
      href:“/api/marketplace/v2/customer/task_templates/translate_en_de”,
      rel: “task_template”, 
      type: “application/json”
    }],
    product: {
      link: [{
        href: “/api/marketplace/v2/products/TextTranslate“,
        rel: “product”,
        type: “application/json”
      }]
    },
    state: “Running”
  },{
  link: [{
    href: “[context]/customer/tasks/ 456“,
    rel: “task”,
    type: “application/json”
  }],
  customer_ref: “translate_run 0”,
  template: {
    link: [{
      href:“/api/marketplace/v2/customer/task_templates/translate_en_de”,
      rel: “task_template”,
      type: “application/json”
    }],
    product: {
      link: [{
        href: “/api/marketplace/v2/products/TextTranslate“,
        rel: “product”,
        type: “application/json”
      }]
    }
  },
  state: “Queued”
 }]
}

Search Tasks by Customer Reference

Request

Request line:

GET [context]/customer/tasks/search

Request parameter:

Name Type Synopsis Mandatory
customer_ref String Filters tasks by specified No
customer_reference.   If parameter is not specified, it filters tasks by customer_reference = NULL  

Request body: (empty)

Response

Response status

  • 200, if the request could be successfully handled (even if no tasks were found)

Response body

  • XML Example
  <tasks_response> 
  <request_status>...</request_status> 
  <tasks>
    <link href=“/api/marketplace/v2/customer/tasks/123” rel=”task” type=”application/xml” />
    <customer_ref>translate_run_0</customer_ref> 
    <created_at>2012-08-28T12:56:08+01:00</created_at> 
    <task_template>
      <link href=”/api/marketplace/v2/customer/task_templates/tt_default”
        rel=”task_template” type=”application/xml”/> 
      <product>
        <link href=“/api/marketplace/v2/products/TextTranslate” rel=”product” type=”application/xml”/>
      </product> 
    </task_template> 
    <state>Running</state>
  </tasks> <tasks>
  <link href=“/api/marketplace/v2/customer/tasks/456” rel=”task” type=”application/xml” />
  <customer_ref>translate_run_0</customer_ref> 
  <created_at>2012-08-28T12:50:01+01:00</created_at> 
  <task_template>
    <link href=”/api/marketplace/v2/customer/task_templates/tt_default”
      rel=”task_template” type=”application/xml”/> 
    <product>
      <link href=“/api/marketplace/v2/products/TextTranslate” rel=”product” type=”application/xml”/>
    </product> 
  </task_template> <state>Queued</state>
</tasks> </tasks_response>
  • JSON Representation
tasks_response: { 
  request_status: ... , 
  tasks: [{
    link: [{
      href: “[context]/customer/tasks/123“, rel: “task”,
      type: “application/json”
    }],
    customer_ref: “translate_run 0”, template: {
      link: [{
        href:“/api/marketplace/v2/customer/task_templates/translate_en_de”, rel: “task_template”,
        type: “application/json”
      }], 
      product: {
        link: [{
          href: “/api/marketplace/v2/products/TextTranslate“, rel: “product”,
          type: “application/json”
        }] 
      },
      state: “Running”,
      created_at: “2012-08-28T12:56:08+01:00” 
    },{
      link: [{
        href: “[context]/customer/tasks/456“, rel: “task”,
        type: “application/json”
      }],
      customer_ref: “translate_run 0”, template: {
        link: [{
          href:“/api/marketplace/v2/customer/task_templates/translate_en_de”, rel: “task_template”,
          type: “application/json”
        }], 
      product: 
      {
        link: [{
          href: “/api/marketplace/v2/products/TextTranslate“, rel: “product”,
          type: “application/json”
      }] 
    }
  },
  state: “Queued”,
  created_at: “2012-08-28T12:50:01+01:00” }]
}

Create Task

A customer makes new work available by creating a task. Tasks are automatically confirmed and distributed to the crowd for resolution.

Customers can choose to receive notifications upon task completion.

Request

Request line:

	POST [context]/customer/tasks/

Request parameter:

(Common only)

Request body:

  • XML Example
<task>
  <customer_ref>task_batch 1</customer_ref> 
  <template>
    <link
href=“/api/marketplace/v2/customer/task_templates/translate_en_d e” rel=”task_template” type=”application/xml” />
  </template> 
  <input>
    <items>
      <code>source</code> 
      <content>English Term</content>
    </items> 
  </input> 
  <notifications>
    <event>CUSTOMER_INPUT_REQUIRED</event> 
    <callback_url>http://notification.example.com</callback_url> 
    <callback_method>POST</callback_method> 
    <payload_format>JSON</payload_format>
  </notifications> 
</task>
  • JSON Example
task: {
  customer_ref: “task_batch 1”, 
  template: {
    link: [{
       href: “/api/marketplace/v2/customer/task_templates/translate_en_de”, rel: “task_template”,
       type: “application/json” 
    }]
  }, 
  input {
    items: [{
      code: “source”, content: “English Term”
    }] 
  },
  notifications: [{
    event: “CUSTOMER_INPUT_REQUIRED”,
    callback_url: “http://notification.example.com/”, 
    callback_method: “POST”,
    payload_format: “JSON”
  }] 
}

Response

Response Status

  • 201, if the taks has succesfully been created
  • 400, if the referenced Task Template does not exist

***Response body

(See example in section View Task Details)

View Task Details

Request

Request Line:

GET [context]/customer/tasks/${id}

Request Parameter:

Name Type Synopsis Mandatory
id Integer The automatically generated Task id as returned by the Create Task operation Yes
show_cloned_task Boolean If is true and the task has cloned task, than the data of the cloned task will be shown. No

Rquest Body:

(Empty)

Response

Response status

  • 200, if the requested resource was found
  • 404, if the requested resource was not found or the given customer id is not associated with the detected credentials

Response body:

  • XML Example
<task_response>
  <request_status>...</request_status> 
  <task>
    <link href=“/api/marketplace/v2/customer/tasks/123” rel=”self” type=”application/xml” />
    <id>123</id> 
    <cloned_task>
      <link href=”/api/marketplace/v2/customer/tasks/234” rel=”self” type=”application/xml”>
    </cloned_task>
    <customer_ref>translate batch a</customer_ref> 
    <template>
      <link 
        href=“/api/marketplace/v2/customer/task_templates/translate_en_d e” rel=”task_template” type=”application/xml” />
      <product>
        <link href=“/api/marketplace/v2/products/TextTranslate”
rel=”product” type=”application/xml”/> 
      </product>
    </template> 
    <net_amount>0.00</net_amount> 
    <tax_amount>0.00</tax_amount> 
    <amount>0.00</amount> 
    <currency>EUR</currency> 
    <state>Created</state> 
    <input>
      <items>
        <code>source</code> 
        <content>English Term</item>
      </items> 
    </input>
    <result /> 
    <notifications /> 
    <progress_logs />
  </task> 
</task_response>
  • JSON Example
task_response: { 
  request_status: ..., 
  task: {
    link: [{
      href: “/api/marketplace/v2/customer/tasks/123”, 
      rel: “self”,
      type: “application/json”
    }],
    id: 123, 
    cloned_task: {
      href: “/api/marketplace/v2/customer/tasks/234”,
      rel: “self”,
      type: “application/json” 
    },
    customer_ref: “translate batch a”, 
    template: {
      link: [{
        href:“/api/marketplace/v2/customer/task_templates/translate_en_de”, 
        rel=”task_template”,
        type=”application/json”
      }], 
      product: {
        link: [{
          href: “/api/marketplace/v2/products/TextTranslate”, 
          rel=”product”,
          type=”application/json”
        }] 
     }
   },
   net_amount: 0.00, 
   tax_amount: 0.00, 
   amount: 0.00, 
   currency: “EUR”, 
   state: “Created”, 
   input: {
     items: [{
      code: “source”, 
      content: “English Term”
     }] 
   },
   result: {}, 
   notifications: [], 
   progress_logs: []
  } 
}

Delete Task

Request

Request line

DELETE [context]/customer/tasks/${id}

or

POST [context]/customer/tasks/${id}?_method=DELETE

Request Paramenter

*Name Type Synopsis Mandatory
id Integer The auto-computed Task id as returned by the Create Task operation 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 could not be deleted

Response body:

(empty)

Clickworker Bonus Payment

A customer has a way to make bonus payments to clickworkers. NOTE: 40% of the amount will be added to the basic payemnt.

Request

Request line:

POST [context]/customer/tasks/${id}/grant_bonus

Request Parameter:

Name Type Synopsis Mandatory
id Integer The auto-computed Task id as returned by the Create Task operation Yes

Request Body:

  • XML Exmaple
<bonus>
  <amount>30.0</amount> 
  <clickworker_id>2</clickworker_id> 
  <comment>Clickworker bonus payment</comment>
</bonus>
  • JSON Example
bonus: {
  amount: 30.0,
  clickworker_id: 2,
  comment: “Clickworker bonus payment”
}

Response

Response status

  • 201, if the payment has successfully been created
  • 422, if some validation error has occurred

Response body

(See example in section View Task Details)

  • XML Example
<grant_bonus_response> 
  <request_status>
    <id>qcscPfWiEqKsOGLP1kfFVHQKJbQ=</id> 
    <valid>true</valid> 
    <status_code>201</status_code>
    <status_text>Created</status_text>
  </request_status> 
  <bonus>
    <amount>100.0</amount> 
    <clickworker_id>2</clickworker_id> 
    <comment>Clickworker bonus payment</comment>
  </bonus> 
</grant_bonus_response>
  • JSON Example
grant_bonus_response: { 
  request_status: {
    id: “qcscPfWiEqKsOGLP1kfFVHQKJbQ=”, 
    valid: true,
    status_code: 201,
    status_text: “Created”,
  }, 
  bonus: {
    amount: 30.0,
    clickworker_id: 2,
    comment: “Clickworker bonus payment” 
  } 
}

External form submit (used for iframe tasks)

When the task-form is hosted on your platform, we need a way to know when the clickworker has finished the task. As soon as the clickworker saves the form on the external platform, you should call this endpoint to let us know about the submit.

Request

Request line:

POST [context]/customer/tasks/${id}/external_submit

Request paramater:

Name Type Synopsis Mandatory
id Integer The auto-computed Task id is returned by the Create Task operation Yes

Request body:

  • XML Example
<submit>
  <clickworker_id>2</clickworker_id> 
</submit>
  • JSON Example
{
  submit: { 
  clickworker_id: 2
  }
}

Response

Response status

  • 201, if the result was successfully submitted
  • 422, if the some validation error has occurred

Response body

(See example in section View Task Details)

  • XML Example
<external_submit_response> 
  <request_status>
    <id>qcscPfWiEqKsOGLP1kfFVHQKJbQ=</id> 
    <valid>true</valid> 
    <status_code>201</status_code> 
    <status_text>Created</status_text>
  </request_status> 
  <external_submit> 
    <id>1000</id>
    <clickworker_id>2</clickworker_id> 
  </external_submit>
</external_submit_response>
  • JSON Example
external_submit_response: { 
  request_status: {
    id: “qcscPfWiEqKsOGLP1kfFVHQKJbQ=”, 
    valid: true,
    status_code: 201,
    status_text: “Created”,
  }, 
  external_submit: {
    id: 1000,
    clickworker_id: 2 
  }
}

Accept the results of this task (used for iframe tasks)

Accept the results of this task. You can add an optional description.

Request

Request line:

PUT [context]/customer/tasks/${id}/accept

Request parameter:

Name Type Synopsis Mandatory
id Integer The auto-computed Task id as returned by the Create Task opeeration Yes

Request body:

  • XML Example
<accept>
  <description>Well done</description>
</accept>
  • JSON Example
{
  accept: {
    description: “Well done”
  }
}

Response

Response status

  • 201, if the result was successfully submitted
  • 422, if the some validation error has occurred

Response body

(See example in section View Task Details)

  • XML Example
<accept_response> 
  <request_status>
    <id>qcscPfWiEqKsOGLP1kfFVHQKJbQ=</id> 
    <valid>true</valid> 
    <status_code>201</status_code> 
    <status_text>Created</status_text>
  </request_status> 
  <accept>
    <id>1000</id> 
  </accept>
</accept_response>
  • JSON Example
accept_response: { 
  request_status: {
    id: “qcscPfWiEqKsOGLP1kfFVHQKJbQ=”, 
    valid: true,
    status_code: 201,
    status_text: “Created”,
  }, 
  accept: {
    id: 1000 
  }
}

Reject the results of this task (used for iframe tasks)

Reject the results of this task. The description is mandatory

Request

Request line:

PUT [context]/customer/tasks/${id}/reject

Request parameter:

Name Type Synopsis Mandatory
id Integer The auto-computed Task id as returned by the Create Task operation Yes

Request body:

  • XML Example
<reject>
  <description>Well done</description>
</reject>
  • JSON Example
{
  reject: {
    description: “Well done”
  }
}

Response

Response status

  • 201, if the result was successfully submitted
  • 422, if a validation error has occurred

Response body

(See example in section View Task Details)

  • XML Example
<reject_response> 
  <request_status>
    <id>qcscPfWiEqKsOGLP1kfFVHQKJbQ=</id> 
    <valid>true</valid> 
    <status_code>201</status_code> 
    <status_text>Created</status_text>
  </request_status> <reject>
  <id>1000</id> </reject>
</reject_response>
  • JSON Example
reject_response: { 
  request_status: {
    id: “qcscPfWiEqKsOGLP1kfFVHQKJbQ=”, 
    valid: true,
    status_code: 201,
    status_text: “Created”,
  }, 
  reject: {
    id: 1000 
  }
}

Notify clickworkers

With this call, you are able to notify clickworkers. Your emails will be delivered to workers as E-mail messages. Clickworker will receive a copy of this email. You may send a message to up to 100 clickworkers at a time.

Request

Request line:

POST [context]/customer/notify_workers

Request body:

  • XML Example
<notify_workers> 
  <subject>Subject</subject> 
  <message>Message body</message> 
  <clickworker_ids>1</clickworker_ids> 
  <clickworker_ids>2</clickworker_ids> 
  <clickworker_ids>3</clickworker_ids> 
  <clickworker_ids>4</clickworker_ids>
</notify_workers>
  • JSON Example
notify_workers: {
  subject: “Subject”, 
  message: “Message body”, 
  clickworker_ids: [1,2,3,4]
}

Response

Response status

  • 201, if the notification has successfully been created
  • 422, if validation error has occurred

Response body

(See example in section View Task Details)

  • XML Example
<notify_workers_response> 
  <request_status>
    <id>qcscPfWiEqKsOGLP1kfFVHQKJbQ=</id> 
    <valid>true</valid> 
    <status_code>201</status_code> 
    <status_text>Created</status_text>
  </request_status>
  <notify_workers>
    <subject>Subject</subject>
    <message>Message body</message> 
    <clickworker_ids>1</clickworker_ids> 
    <clickworker_ids>2</clickworker_ids> 
    <clickworker_ids>3</clickworker_ids> 
    <clickworker_ids>4</clickworker_ids>
  </notify_workers> 
</notify_workers_response>
  • JSON Example
notify_workers_response: { 
  request_status: {
    id: “qcscPfWiEqKsOGLP1kfFVHQKJbQ=”, 
    valid: true,
    status_code: 201,
    status_text: “Created”,
  }, 
  notify_workers: {
    subject: “Subject”, 
    message: “Message body”, 
    clickworker_ids: [1,2,3,4]
  } 
}
Tags: