open nav

Channel API

The CrowdFlower Channel API v2 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, please follow the Onboarding process. 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:

Conversion name (default: "cents")
This is used to display messaging to the user. For example, if your conversion name is "RadBucks," the user will see messaging like "This task pays 15 RadBucks per page of work." and "You have earned 100 RadBucks!"
Conversion rate (default: 1)
Floating point number that is multiplied by the actual earned amount of money (in US cents) when displaying the earned amount to a contributor. For example, if a contributor has earned 50 cents and your conversion rate is 0.1, the contributor will see messaging like "You have earned 5 RadBucks so far."
Minimum conversion amount (default: 1 cent)
Users will not convert until they have earned at least this amount on CrowdFlower (in US cents).
URL
This is the URL that CrowdFlower will POST conversions to. See below for details on the actual POST requests.

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:

Tasks index page

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:

uid
The unique identifier for the user provided in step 1.
amount
An integer corresponding to the reward, in US cents, that the user is being converted for.
adjusted_amount
A float corresponding to the adjusted conversion amount calculated from your conversion_rate, if provided. If the amount is greater than or equal to 1, then it is rounded down to the nearest integer, then converted to a float. If the amount is less than 1, it is rounded to the nearest 100th of a decimal. For example, 0.005 would be rounded to 0.01.

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 contributors. 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"
}

Task Listing

Channels host an iframe that points to an endpoint in this app that shows available tasks. The task listing requires a "uid" parameter (amongst other optional parameters) that is the channel's id for the worker. To ensure that the "uid" is trustworthy, the parameters are expected to be signed by adding two additional parameters. 

  1. generated_at - the unix timestamp at which the signature was generated
  2. signature - a signed token that encompasses all channel parameters and the generated_at parameter.
    • Channel parameters are "uid" and anything that starts with an underscore - "_"

How to generate a signature

Given:
  • url - /channels/prodege/tasks?uid=0000-0001&_conversion_rate=2.2&generated_at=1389070336&funny=true
  • channel_secret - my_secret
Steps:
  1. Gather all channel parameters and generated_at parameter
    • uid=WORKER-ID
    • _conversion_rate=2.2
    • generated_at=1389070336
  2. Sort these params and concatenate using ; as a delimiter

    _conversion_rate=2.2;generated_at=1389070336;uid=0000-0001

  3. Append "channel_secret" to create undigested token from the previous step

    _conversion_rate=2.2;generated_at=1389070336;uid=0000-0001my_secret

  4. Create a SHA1 digest of undigested token

    a0da42353cb142b6ef4cbd297215892cff283577

Signed url: /channels/prodege/tasks?uid=0000-0001&_conversion_rate=2.2&generated_at=1389070336&funny=
true&signature=a0da42353cb142b6ef4cbd297215892cff283577

Note: This url will only be valid for 30 seconds after generated_at.