• Requester Interface
• Gold
• API
• CML
• Channel API
• Image Moderation API

Channel API v2 Switch to version 1

The CrowdFlower Channel API allows anyone to provide CrowdFlower tasks for their users. Channel partners can specify custom conversion rates and minimum conversion amounts.

Becoming a CrowdFlower provider

To become a CrowdFlower channel provider, send an email to CrowdFlower at solutions@crowdflower.com. Once you have been approved, you’ll need to provide us with some information (outlined below) and we will assign you a URL and secret key.

What we need

When becoming a CrowdFlower channel partner, CrowdFlower will need the following information from you:

Workflow

Users will follow this general process when chosing and working on CrowdFlower tasks:

Step 1: Viewing available tasks

Users from your site can view a list of available tasks at:

http://crowdflower.com/judgments/{channel_name}?uid={unique_user_identifier}

(channel_name will be provided to you during the setup process.)

You must provide the uid parameter, which uniquely identifies each user. The uid must be 50 or fewer UTF-8 characters.

By default, the tasks index page looks like this:

We can include custom CSS on the task index page, by request.

Step 2: Beginning a task

When the user clicks a link on the task index page and begins working on a task, CrowdFlower will keep track of their balance. Any money the user has earned on previous tasks but that have not yet been converted will be carried over into the new task.

Step 3: Converting

When the user has earned at least the minimum conversion amount, we will issue two requests to your servers:

Converting: Conversion id

The first request CrowdFlower issues is a POST with the following information:

payload: {
  uid: "900af657a65e",
  amount: 50,
  adjusted_amount: 25
},
signature: "4dd0f5da77ecaf88628967bbd91d9506"

The payload params are:

signature is a SHA1 signature of the payload and your secret channel key (given to you in the setup process). This should be used to validate the post. For example, you can validate the payload in Ruby with:

require 'json'
require 'cgi'
require 'digest/sha1'

secret_key = "secret_key_defined_in_setup_phase"
params = CGI::parse(post_body)
digest = Digest::SHA1.hexdigest(params["payload"]+secret_key)

if digest == params["signature"]
  # Valid signature
  payload = JSON.parse(params["payload"])
  # Respond with status code 200 and conversion id
else
  # Invalid signature. You should response with a non-200 response code.
end

Response

Your server should respond a 200 status code and a unique identifier for the conversion (a “conversion id”). The conversion id must be a string of UTF8 characters 50 characters in length or less and should be the only contents of the body of your response. The conversion id will be used in the next request from CrowdFlower.

If you respond with a non-200 status code, the user will be able to continue working and accumulating money and CrowdFlower will attempt to acquire a conversion id the next time they submit a page of work.

Converting: Finalizing the conversion

After you have given CrowdFlower a conversion id, it will issue another POST shortly thereafter to finalize the conversion with the following:

payload: {
  conversion_id: "32402345984532934511",
  amount: 50,
  adjusted_amount: 25,
  job_title: "The title of the last job they completed (and 2 other jobs)"
},
signature: "1221299611f823b8c30a347373b449ad"

amount and adjusted_amount are the same as in the first POST. conversion_id is the unique conversion identifier your server returned in the first conversion POST. To prevent confusion, please be sure to assert that each conversion id is recorded only once. Asserting the uniqueness of conversion ids will prevent accounting errors due to network or configuration errors.

signature should be verified in the same way as before.

Response

Your server should respond with a 200 status code. If it does not, the user will be able to continue working and accumulating money and CrowdFlower will attempt to start the conversion process over again the next time the user submits a page of work.

In case of problems, you can easily download conversion histories from the CrowdFlower web site for reconciliation.

Extra Parameters

Any parameters passed to the task listing page that begin with an underscore will be returned in the two payloads listed above under a key named “extra_params”. There are two special parameters “_conversion_name” and “_conversion_rate”. These allow you to specify different conversion rates and names for your workers. You must set the conversion_name and conversion_rate parameters in the dashboard to nil for these to work. Below is an example of passing extra parameters:

http://crowdflower.com/judgments/{channel_name}?uid={unique_user_identifier}&_meta_info=something

Results in this payload:

payload: {
  uid: "900af657a65e",
  amount: 50,
  adjusted_amount: 25,
  extra_params: {_meta_info: "something"}
},
signature: "4dd0f5da77ecaf88628967bbd91d9506"