Login

Login

Channel API

The CrowdFlower Channel API allows anyone to become a provider for the tasks that are posted on the CrowdFlower platform. Partners can specify conversion rates and present a list of tasks for their users to complete.

Channel Setup

The first step in becoming a channel provider to the CrowdFlower platform is contacting a CrowdFlower account manager to setup your integration. Send an email to solutions@crowdflower.com to get the process started. Once you have been approved, we will assign you a channel name and secret key. You will also provide us with two URLs that respond as defined below.

Workflow definition

There are three steps in the workflow between CrowdFlower and a channel provider. Each are described in detail below:

Integration Step 1

Users from the provider’s site are sent to a list of available tasks hosted by CrowdFlower. This list of tasks can be displayed within an iFrame or a separate page all together. Providers must specify a unique identifier for each user who accesses this page. The URL is formed as follows:

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

The channel name is defined in the setup phase. The uid can be any string of up to 50 UTF8 characters in length or less. You can also specify the conversion_rate and conversion_name parameters. conversion_rate is a floating point number that is multiplied by the actual dollar amount to display the correct numbers of credits a user will receive. conversion_name is used to display the type of currency the user will receive. If these parameters are not specified, the user will be displayed the reward in USD.

Any query parameters specified outside of those defined will be passed back to the channel provider in Step 2.

Integration Step 2

When a user chooses a task from the available list, CrowdFlower issues a POST request to a predefined location on the channel provider’s servers. The post request contains at minimum the uid and amount parameters. uid is the unique identifier for the user (specified in Step 1) and amount is a floating point number corresponding to the reward in USD for completing the task. Any extra parameters specified in step 1 will also be sent to the provider in JSON format. Below is an example initiation request:

POST http://providers_url.com/conversion_initiation_endpoint

Request body (payload not URL-encoded for readability)

  payload={
    "uid": "123ABC",
    "amount": 0.50,
    "extra_param": "foo"
  }
  &signature=ac23e64b2ff8aa0c1b1cd366754c5093b55265d2
}

The response from this request is required to return an HTTP status of 200 and provide a conversion_id identifier in the response body. conversion_id must be a string of UTF8 characters 50 characters in length or less. This value will later be sent back to the providers servers if the user completes a given task. The request body should be verified by creating a SHA1 hash of the JSON data within the payload of the POST body concatenated with the secret_key received from the setup phase. An example implementation in Ruby is shown below:

Ruby example

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

secret_key = "secret_key_defined_in_setup_phase"
params = CGI::parse(post_body)
if(Digest::SHA1.hexdigest(params["payload"]+secret_key) == params["signature"])
  #valid signature
  payload = JSON.parse(params["payload"])
else
  #invalid signature, should response with a non 200 response code
end

Response body

ABCD1234

If an HTTP response status code other than 200 is received or the request does not respond within five seconds, an error message is displayed to the user, and they cannot accept the task.

Integration Step 3

If the user is able to complete the task they accepted, another request is issued to the channel provider’s servers. This request informs the provider that the user should be paid for their work and CrowdFlower should be billed for the completion. For the completion to be acknowledged by CrowdFlower, the provider must respond with an HTTP status of 200. The request appears as follows:

POST http://providers_url.com/conversion_completion_endpoint

Request body (payload not URL encoded for readability)

payload={
  "conversion_id": "ABCD1234"
}
&signature=ac23e64b2ff8aa0c1b1cd366754c5093b55265d2

Response body

OK

Again the POST body should be validated against the signature with the secret_key and payload content as described in Step 2. To prevent confusion, please be sure to assert that each conversion id is recorded only once. CrowdFlower will retry this post several times if your server is unavailable or responds with a non-200 code. Asserting the uniqueness of conversion ids will prevent accounting errors due to network or configuration failure. In case of problems, you can easily download conversion histories from the CrowdFlower.com web site for reconciliation.

CHANNEL Docs