Channel API documentation

Scaling human intelligence

Becoming a CrowdFlower channel provider

The CrowdFlower Channel API v2 allows any organization with users, contractors or employees to make CrowdFlower tasks available for them to complete. As a channel partners you are required to host an iframe of available CrowdFlower tasks on your own website so your users can access tasks within your own web property. Channel partners can specify custom conversion rates and minimum conversion amounts in order to customize the integration to fit your business needs and preferred currency.

If you are interested in becoming a CrowdFlower channel provider, please submit an inquiry via the contact form found on our Labor Channel overview page. If you are approved, we will provide you access to a user interface in order to set up the integration, customize it to your business and track the activity of your users. Within the interface you’ll need to provide us with some basic information (outlined below). We will also assign you a custom iframe URL and secret key.

What we need

CrowdFlower places great emphasis on ensuring the security & integrity of all communications with our channel partners. At this time, we require that all API calls from our NDA partners have digital signatures as described here. Non NDA partners are required to use digital signatures for conversion calls, and will be required to apply signatures to all calls in the near future.

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 choosing and working on CrowdFlower tasks:

Step 1: Viewing available tasks

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

https://tasks.crowdflower.com/channels/{channel_name}/tasks?uid={unique_user_identifier}

You will establish your channel_name during the setup process once you have been approved to integrate and we have provided you access to your admin UI.

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 listing page available via the iframe appears like the below:

Task Listing Index

Important: We are not able to include custom CSS on the task listings page at this time.

Step 2: Beginning a task

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

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
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.

An example of how you can use the signature to validate the payload in Ruby is provided below:

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”].to_json+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 and body “OK”. 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.

 

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 required 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/{channel_name}/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 alphabetically 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/{channel_name}/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.

Advanced

It is possible for additional parameters to be passed to the task listing page that begin with an underscore and have them returned in the two payloads listed above under a key named extra_params. It is important to note that this only needs to be done if you pay different rates or currencies per user which is very rare. 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:

https://tasks.crowdflower.com/channels/{channel_name}/tasks?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"
}

Print