To benefit from clickworker’s crowdsourcing services, customers need valid login credentials for the platform. With these credentials, they can upload their tasks through the API within an appropriate template, which includes several parameters like language, text length and a briefing for the clickworkers. Immediately our crowd starts working on these tasks. Finally, the customer must fetch the results through the API.

Two clickworker environments host installations of the API:

  • Production: This is the production environment. It uses the latest released version of the API, works with production data, and fully interacts with external systems like email servers. The current production environment is available at:

https://api.clickworker.com/api/marketplace/v2/

  • Sandbox: This is the testing environment. It uses the latest released version of the API, works with dedicated test data, and has limited interaction with external systems like email servers. Customers can use this environment to test their client implementations. No clickworker crowd is available on Sandbox. The current sandbox environment is available at:

https://sandbox.clickworker.com/api/marketplace/v2/

This high-level process is described more detailed in the following sections of this chapter.

  1. Getting login credentials (username and password) for testing environment (‘sandbox’)
  2. Testing access to the Sandbox environment
  3. Choosing the appropriate product
  4. Setting up the task-templates
  5. Submitting your tasks.
  6. Working on your tasks as a clickworker (sandbox only).
  7. Reviewing / appriving or rejecting results
  8. Fetching results data

Credentials and access via API

The clickworker Marketplace API uses HTTP Authentication (“Basic Auth”) for access control.

For the testing environment (‘sandbox’) credentials must to be requested ([email protected]) from our Solutions department.

The credentials used for API authentication on our production environment (‘production’) are the username and password. In order to request API access on production, please log in with your customer account and go to “Profile” / “API access”.

To ensure data security, the API requires the use of Secure Socket Layers (SSL).

As the API is REST-based, a proper REST-client is needed to communicate with our API. For a first try- out a Mozilla Firefox Add-on is available1. For production usage we highly recommended to contact us ([email protected]), as we also offer a client-side integration service. Alternatively you may use other command line tools such as “curl”, which is available on a wide range of operating systems.

With the given credentials you can get customer specific account information through the API.

Firefox REST-Client

Firefox REST-Client

As shown in the image “Firefox REST-Client” the URL for our testing environment is:

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

Make sure that you provided your credentials to the REST-client (click on ‘Authentication’ – see red rectangle). Also add a http-Header as “Content-Type: application/xml” (click on ‘Headers’->’Custom Header’).

If everything is setup correctly, the response will be a XML-document under the tab ‘Response Body (Preview)’ (see image “Firefox REST-Client”).

With this response you have verified that you have a working access to our API. In the following the necessary steps for a project setup are described.

Choose a product

The first step in the project creation is to choose which product to use for creating your project. Each product has unique quality mechanisms, pricings and options to configure the service. Out of the box, two services are offered. Our Solutions department may have configured a specific product to meet your client conditions and needs.

  • TextCreate

    “Your content authored competently and economically. Our clickworkers create exclusive content and articles for you. From a single text to a large-scale order, quickly and at affordable rates.”

    This product offers texts in different languages and in different lengths.

    The different languages offered are: German [de], Swedish [sv], Dutch [nl], Italian [it], Polish [pl], Turkish [tr], Spanish [es], Hungarian [hu], Czech [cs], Portuguese [pt], Romanian [ro], French [fr], Russian [ru], English [en], Danish [da], Finnish [fi], Norwegian [no].

    Additional to the language, customers can choose between different text lengths. These are (numbers mean words – [from#to]): 10#55, 50#110, 101#155, 151#205, 201#255, 251#305, 301#355, 351#405, 401#455, 451#505, 501#555, 551#605, 601#710, 701#810, 801#910, 901#1010 and 1001#1210.

    As a final decision customers need to choose if a second clickworker should proof-read the text to achieve an outstanding quality.

    Each customer project needs a proper task description for text creation, so our clickworkers know what kind of text they are supposed to write. We strongly advise also to deliver an example text, so the created texts meet the customer’s expectations even more accurate.

  • TextCreateWithKeywords“

    Content is King. Search engine optimized text. Our authors create and correct content that makes your site more attractive to search engines.”

    The offered text lengths differ slightly from TextCreate and are (numbers mean words – [from#to]): 10#55, 50#110, 100#160, 151#205, 201#255, 251#305, 301#355, 351#405, 401#455, 451#505, 501#555, 551#605, 601#710, 701#810, 801#910, 901#1010, 1001#1210 and 1450#1500.

    For this product customers have to add at least one keyword to each text creation task, which will be incorporated into the texts by our clickworkers. This way we provide a highly-scaling SEO-Text creation option. All other aspects are equal to our ‘TextCreate’ product (see above).

Define your document templates (Task-Template)

Once you have chosen a product, you need to define your document structure by creating a new TaskTemplate. The TaskTemplate defines:

  • The briefing to the clickworker for this type of task

Each customer needs to charge their account to create tasks through API. If you want to test our API on Sandbox, please contact us ([email protected]). We will provide credits for your sandbox accounts.

  • Input fields provided to the clickworker to fulfil the task (e.g. topic, keywords)

  • Result fields filled out by clickworker when fulfilling the task (e.g title field, abstract, long text)

Defining a new TaskTemplate is explained in section “Project setup - Define TaskTemplate”. New TaskTemplates are defined by posting the XML definition.

Creating tasks

Once you have chosen a product and configured your templates, you can post new tasks for your project, and resolution by our clickworkers. Together with the task description (briefing) this input data defines the task to be delivered by the clickworkers.

Submitted tasks will be distributed to the crowd and clickworkers will author the article according to the briefing. Depending on the quality assurance options configured, results will be reviewed by the crowd or our lecturer service and then sent to you for final approval. This step is called the ‘buyoff’.

Buyoff

Completing your submitted tasks will take some time. At any time you may have multiple tasks submitted and ongoing. The order of completion will be different than the order of submitting tasks. There are two options to get an overview of your active and completed tasks:

  • Polling / Pull approach: As the customer, you may check regularly if your tasks have reached the state ‘Feedback’

  • Push notification / Notification approach: When submitting a new task, you may add a Notification URL which will be called when the task has reached that state ‘Feedback’. Push notifications are highly recommended as it is superior in terms of performance and load on your client system.

The buyoff carried out by the customer itself will be done via the “buyoff Job”: Each task is partitioned into different jobs, representing different steps in the overall workflow. E.g. if the task has been configured to include quality assurance there are at least 3 jobs involved to solve the task. The first job is to create the content. The second job is to review the content. And the third job is to execute the buyoff. So on the testing environment (‘sandbox’) the customer needs to compete two jobs through the clickworker workplace before the task reaches the buyoff state. This last job includes the results of the task and requests for approval.

In order to buy off or reject the result, you need to post an XML-document (http-POST) carrying the approval information from the customer’s API client to the API. This approval information ensures, that clickworkers will receive an appropriate rating and therefore is cruicial for sustaining good quality in your projects. More details on this will be given in section “Project setup - Approval / Rejection”. Once approved, your may fetch the task results via the API.

Get task results

During task creation (see Integration Description - Creating tasks) the customer will have received a unique identifier for each task which was uploaded. With this given identifier you may check the results by calling this reference URL (http-GET). On the Sandbox-Environment this URL would be:

https://sandbox.clickworker.com/api/marketplace/v2/customer/tasks/<identifier>

Results are delivered as a XML payload within the response body as an answer to the http-request. The structure in detail can vary and depends on the structure the customer has configured within the step of the initial project creation (See Integration Description - Define your document templates (Task-Template)).

Managing Clickworker Teams

Teams allow to group clickworkers and include or exclude them from your projects. Teams are typically used in the following scenarios:

  • Excluding clickworkers that have already participated in a previous survey.
  • Only addressing specific clickworkers with a survey for follow up surveys
  • Excluding authors from your text project (blacklisting)
  • Assigning text projects to a list of known authors that have worked for you previously

Creating a new team

To create a new team you want to send POST request to /api/marketplace/v2/customer/teams, with specified XML body

<team>
  <id>[TEAM ID]</id>
  <name>[TEAM NAME]</name>
  <note>[OPTIONAL NOTE]</note>
  <hide>false</hide>
</team>
  • <id> Team ID identifier (in)
  • <name> Team name
  • <note> Any note (optional).
  • <hide> Identifies that team is hidden (optional boolean attribute).

Deleting a team

To permanently delete a team you want to send DELETE request to /api/marketplace/v2/customer/teams/ where is an integer number – the Id of a team.

Modifying a team

To hide a team from marketplace drop down lists, use a PUT request to /api/marketplace/v2/customer/teams/ and set attribute hide into true:

<team>
  <hide>true</hide>
</team>

You may update the following attributes of a team:

  • <name> The team name
  • <note> Description of the team
  • <hide> show/hide from lists

Listing teams of a customer

To retrieve all customer’s teams you want to send GET request to /api/marketplace/v2/customer/teams. Response will look like:

<teams_response>
  <request_status>
    <id>wybSKEcLKGBNbd+LKX7zXIsvVJc=</id>
    <valid>true</valid>
    <status_code>200</status_code>
    <status_text>OK</status_text>
    <total_count>5</total_count>
    <page_num>1</page_num>
    <page_size>50</page_size>
  </request_status>
  <teams>
    <id>12242</id>
    <name>Content Managers</name>
  </teams>
  <teams>
    <id>232304</id>
    <name>Interpreters</name
  </teams>
</teams_response>

Adding clickworkers to a team

To add clickworkers to the team you want to send PUT request to /api/marketplace/v2/customer/teams/<team_id>, with specified XML body:

<team>
  <add_user_ids>[USER_ID]</add_user_ids>
  <add_user_ids>[USER_ID]</add_user_ids>
  <add_user_ids>[USER_ID]</add_user_ids>
</team>

<add_user_ids> is a list (Array) of clickworkers users Ids that should be added to the team, e.g. [1,2,3,4]

Removing clickworkers from a team

To remove clickworkers from the team send a PUT request to /api/marketplace/v2/customer/teams/<team_id> with the following XML body:

<team>
  <remove_user_ids>[USER_ID]</remove_user_ids>
  <remove_user_ids>[USER_ID]</remove_user_ids>
  <remove_user_ids>[USER_ID]</remove_user_ids>
</team>

<remove_user_ids> is a list (Array) of clickworkers users Ids that should be removed from the team, e.g. [1,2,3,4]

Summary

The previous chapters have explained the typical usage scenario for the API. The next chapter explains the process in more detail.

Tags: