Follow

CrowdFlower API Requests Guide

We've formatted some common CrowdFlower API calls as cURL requests; from these examples, you can extrapolate the request syntax and content suited to your environment and Job(s). The requests below are organized according to the layout of the platform.

Note: In this article, rows are referred to as "units".

Request Conventions


Whatever client you use to reach CrowdFlower via API, observe the request formatting and syntax guidelines below.

  • URL-encoding is necessary when passing unsafe ASCII characters
  • Except where noted in the documentation, object attributes are set within brackets and prepended by the related Object name (e.g., "jobs[title]")
  • Your application must set each request's Accept header field to application/json—​or append .json to the URL in the request
  • When uploading data, the request's Content-Type header field must indicate the format of the data to be uploaded


Design Job - Build Job


Create a Blank Job

Creates a new Job with a Job ID—but without data, title, instructions, or other settings values.
curl -X POST https://api.crowdflower.com/v1/jobs.json?key={api_key}

Response: JSON Representation of new Job

 

​Create a Job with Title and Instructions

Creates a new Job with Job ID, Title, and Instructions.

curl -X POST --data-urlencode "job[title]={some_title}" --data-urlencode "job[instructions]={some_instructions}" https://api.crowdflower.com/v1/jobs.json?key={api_key}

Response: JSON representation of new Job ​

Create a Job with JSON Data

Creates a new Job with Job ID and rows comprised of the JSON data uploaded via the request. Note that this request invokes the ​upload operation.

curl -X POST -T "{sample_data.json}" -H "Content-Type: application/json" https://api.crowdflower.com/v1/jobs/upload.json?key={api_key}

Response: JSON representation of new Job ​

Example JSON file: sample_data.json

 

Create a Job with CSV Data

Note: CSV files must be UTF-8 encoded

Creates a new Job with Job ID and rows comprised of the CSV data uploaded via the request. Note that this request invokes the ​upload operation.

curl -X POST -T "{sample_data.csv}" -H "Content-Type: text/csv" https://api.crowdflower.com/v1/jobs/upload.json?key={api_key}

Response: JSON representation of new Job

 

Copy a Job

Copies the Job identified in the {job_id} parameter of the request to a new job, with a new Job ID.  All Rows and settings are copied.  Uses copy operation.

curl -X GET "https://api.crowdflower.com/v1/jobs/{job_id}/copy.json?key={api_key}&all_units=true"

Response: JSON representation of Job

 

Copy a Job without its Rows

Copies the Job identified in the job_id parameter of the request without its Rows. All settings are copied. Uses copy operation.

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/copy.json?key={api_key}

Response: JSON representation of Job

 

Copy a Job with only its Test Questions

Copies the job identified by the job_id parameter of the request with only its test-question rows. All settings are copied. Uses copy operation.

curl -X GET "https://api.crowdflower.com/v1/jobs/{job_id}/copy.json?key={api_key}&gold=true"

Response: JSON representation of Job

 

Update Job Title

Updates the Title of the Job.  

curl -X PUT --data-urlencode "job[title]={some_new_title}" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job
See Note

 

Update Job Instructions

Updates the instructions of a Job

curl -X PUT --data-urlencode "job[instructions]={updated_instructions}" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job
See Note

 

Update Job CML

Updates the CML of the Job.

curl -X PUT --data-urlencode "job[cml]={some_new_cml}" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job

 

 

Design Job - Data


Add CSV Data to a Job

Uploads the CSV data specified in the request to an existing Job, also specified in the request.  This action corresponds to uploading a CSV using the "Add More Data" button displayed in the screenshot above. Note that this request invokes the upload operation.

curl -X PUT -T cf_sample_data.csv -H "Content-Type: text/csv" "https://api.crowdflower.com/v1/jobs/{job_id}/upload.json?key={api_key}&force=true"

Response: JSON representation of Job
​See Note

 

Add JSON Data to a Job

Uploads the JSON data specified in the request to an existing Job, also specified in the request. This action corresponds to uploading using the "Add More Data" button displayed in the screenshot above however instead of uploading a CSV, this request allows one to upload data in JSON format.  Note that this request invokes the upload operation.

curl -X PUT -T "{sample_data.json}" -H "Content-Type: application/json" https://api.crowdflower.com/v1/jobs/{job_id}/upload.json?key={api_key}

The above request fails when the fields in the data uploaded do not match the fields already present in the job. To override this validation and force upload data, use the query parameter "force=true".

curl -X PUT -T "{sample_data.json}" -H "Content-Type: application/json" https://api.crowdflower.com/v1/jobs/{job_id}/upload.json?key={api_key}&force=true"

Response: JSON representation of Job

Example JSON file: sample_data.json

  

Get Rows in a Job

Gets Rows for the Job identified by the job_id parameter of the request.

curl -X GET "https://api.crowdflower.com/v1/jobs/{job_id}/units.json?key={api_key}&page={1}"

Response: JSON object of 1000 rows for the Job indicated in the request. In order to get the next 1000 rows, you must increment the value of page. Keep doing so until an empty hash is returned.

Change the State of a Row

Changes the state (e.g., "new," "golden," "finalized", "canceled") of the Row identified in the request

curl -X PUT --data-urlencode "unit[state]={new}" https://api.crowdflower.com/v1/jobs/{job_id}/units/{unit_id}.json?key={api_key}

Response: JSON object comprising Judgment count, Row state, and timestamp values.

 

Get Row Count

Gets count of all Rows in a Job

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/units/ping.json?key={api_key}

Response: JSON object containing count of Rows in Job

 

Create a New Row

Creates a new Row in an existing Job. This is the request format and endpoint to use for unit-by-unit posting.

curl -X POST -d "unit[data][{column1}]={some_data_1}" -d "unit[data][{column2}]={some_data_2}" https://api.crowdflower.com/v1/jobs/{job_id}/units.json?key={api_key}

Responses: JSON object of the Row created, including its ID, data, and related Job ID. JSON application message indicating status of the operation (e.g., "Unit was successfully created")

 

Copy a Row

Copies a Row 

curl -X POST https://api.crowdflower.com/v1/jobs/{job_id}/units/{unit_id}/copy.json?key={api_key}

Response: JSON object containing count of Rows in Job

 

Cancel a Unit

Will cancel a unit in state 'New'. Units already launched can not be cancelled.

curl -X POST https://api.crowdflower.com/v1/jobs/{job_id}/units/{unit_id}/cancel.json?key={key}

 

Convert Uploaded Test Questions

Corresponds to the "Convert Uploaded Test Questions" button in the screenshot above. All rows where column "_golden" is set to "true" will be converted to test questions.

curl -X PUT https://api.crowdflower.com/v1/jobs/{job_id}/gold.json?key={api_key}

 

Split Column

Corresponds to the "Split Column" button in the screenshot above. This operation will split the contents of a column on a certain character, transforming strings into arrays of strings. For a more detailed explanation, see this article.

curl -X GET 'https://api.crowdflower.com/v1/jobs/{job_id}/units/split?key={api_key}&on={column}&with={character}'

Parameters:

  • on - The name of the column to split
  • with - The character to split on

 


Manage Quality - Job Settings 


Set Job Task Payment

Note: at minimum, your job must have a valid title, instructions, and one "required" CML form element to be saved successfully. 

Determines the amount, in cents, that Contributors will be paid per Task

curl -X PUT --data-urlencode "job[payment_cents]={20}" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job

 

Set Time Per Assignment

Set the amount of time per assignment. Default is set to 30 minutes.

curl -X PUT --data-urlencode "job[options][req_ttl_in_seconds]={n}" "https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}"

 

Set Rows per Page

Sets the number of Rows that will comprise one Page within a Job.

curl -X PUT --data-urlencode "job[units_per_assignment]={n}" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job

 

Set Dynamic Judgments

Sets parameters for collecting dynamic judgments.

curl -X PUT -d "job[variable_judgments_mode]={auto_confidence}" -d "job[confidence_fields]={cml_form_element_name}" -d "job[max_judgments_per_unit]={n}" -d "job[min_unit_confidence]={m}" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Parameters for this command:

  • variable_judgments_mode: "none" - disable dynamic judgments, "auto_confidence" - enable dynamic judgments
  • confidence_fields: CML form element name that determines row finalization for dynamic judgments
  • max_judgments_per_unit: Maximum number of judgments collected per row
  • min_unit_confidence: Minimum confidence needed to finalize a row (a number  from 0 to 1)

Take a look at the Dynamic Judgments article for an in-depth explanation of each parameter: https://success.crowdflower.com/hc/en-us/articles/203219205-Job-Settings-Guide-to-Dynamic-Judgments

 

Job Tagging

To view all tags in a Job:

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/tags?key={api_key}

To add a new tag to a Job:

curl -X POST --data-urlencode "tags={tag}" https://api.crowdflower.com/v1/jobs/{job_id}/tags?key={api_key}

To replace the tags in a Job - separate tags with commas:

curl -X PUT --data-urlencode "tags={tag1, tag2}" https://api.crowdflower.com/v1/jobs/{job_id}/tags?key={api_key}

Response: JSON application message indicating status of the operation (e.g., "Unit was successfully created")

  

Channels

To get all labor Channels via which the Job can be accessed:

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/channels?key={api_key} 

To add a Channel via which the Job can be accessed:

curl -X POST --data-urlencode "channels={clixsense}" https://api.crowdflower.com/v1/jobs/{job_id}/channels?key={api_key} 

To remove a Channels via which the Job can be accessed:

curl -X POST --data "channel_name={CHANNEL}" 'https://api.crowdflower.com/v1/jobs/{job_id}/disable_channel?key={CF_KEY}'

Response: JSON representation of enabled Channels

 

Turn Auto Launch On or Off

Toggles Auto Launch on or off.

curl -X PUT --data-urlencode "job[auto_order]=true" https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job

 

Get the Legend of a Job

Gets the legend of the Job identified by the job_id parameter of the request.

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/legend.json?key={api_key}

Response: a JSON hash of the fields (keys) that your job's CML will generate as the results/output of your job.  If a CML field in your job features a fixed set of responses (e.g., a cml:radio object), then the set of possible responses will also be returned.​

 

 

Get Results - Launch


 Launch a Job

Launches ("orders") a Job  

To launch to the On Demand Workforce:

curl -X POST -d "channels[0]=on_demand&debit[units_count]={100}" https://api.crowdflower.com/v1/jobs/{job_id}/orders.json?key={api_key}

To launch to the Internal Channel:

curl -X POST -d "channels[0]=cf_internal&debit[units_count]={100}" https://api.crowdflower.com/v1/jobs/{job_id}/orders.json?key={api_key}

To launch to both:

curl -X POST -d "channels[0]=on_demand&channels[1]=cf_internal&debit[units_count]={100}" https://api.crowdflower.com/v1/jobs/{job_id}/orders.json?key={api_key}

Response: JSON object, including credit balance, starting and ending Unit IDs, etc.

 

Pause a Job

Pauses a Job that is currently running.

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id/pause.json?key={api_key}

Response: JSON application response (e.g., "Success! Your job is being paused").

 

Resume a Job

Resumes a Job that had been paused

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/resume.json?key={api_key}

Response: JSON application response (e.g., "Success! Your job is being resumed").

 

Cancel a Job

Cancels a Job

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/cancel.json?key={api_key}

Response: JSON application response (e.g., "Success! Your job is being canceled").

 

 

Get Results - Monitor


Contributors tab in Get Results - Monitor section  

Pay a Contributor Bonus

Deposits the amount indicated in the request into the indicated Contributor's account, as a bonus. Corresponds to the "Award Bonus" buttons shown in the screenshot above.

curl -X POST --data-urlencode "amount={amount_in_cents}" https://api.crowdflower.com/v1/jobs/{job_id}/workers/{worker_id}/bonus.json?key={api_key}

Response: JSON application message indicating status of operation

 

Notify a Contributor

Notifies a Contributor with the message provided in the request.  The notification appears in the Contributor's dashboard. Corresponds to the "Notify Contributor" button showns in the screenshot above.

curl -X POST --data-urlencode "message={message_to_worker}" https://api.crowdflower.com/v1/jobs/{job_id}/workers/{worker_id}/notify.json?key={api_key}

Response: JSON application message indicating status of operation

 

Flag a Contributor

Flags a contributor with the reason indicated in the request. Corresponds to the "Flag" buttons shown in the screenshot above.

curl -X PUT --data-urlencode "flag={reason_for_flagging_contributor}" https://api.crowdflower.com/v1/jobs/{job_id}/workers/{worker_id}.json?key={api_key}

Response: JSON application message indicating status of operation

 

Unflag a Contributor

Unflags a contributor with the reason indicated in the request. 

curl -X PUT --data-urlencode "unflag={reason_for_unflagging_contributor}" https://api.crowdflower.com/v1/jobs/{job_id}/workers/{worker_id}.json?key={api_key}

Response: JSON application message indicating status of operation

 

Reject a Contributor

Rejects a contributor with the reason indicated in the request. 

curl -X PUT --data-urlencode "reject={reason_for_rejecting_contributor}" https://api.crowdflower.com/v1/jobs/{job_id}/workers/{worker_id}/reject.json?key={api_key}

Response: JSON application message indicating status of operation

 

Get the Status of a Job

Gets the status of the Job identified by the job_id parameter of the request.

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/ping.json?key={api_key}

Response: JSON payload comprising Judgment and Row counts.

 

Get the .json of a Job

Gets the .json of the Job identified by the job_id parameter of the request. This includs the total cost and job state.

https://api.crowdflower.com/v1/jobs/{job_id}.json?key={api_key}

Response: JSON representation of Job

 

Get Results - Results


 

Job Reports

To regenerate a report within a job:

curl -X POST "https://api.crowdflower.com/v1/jobs/{job_id}/regenerate?type={report_type}&key={api_key}"

To download a report from a job first run:

curl -s -o /dev/null -w "%{http_code}" "https://api.crowdflower.com/v1/jobs/{job_id}.csv?type=json&key={api_key}"

After you receive a 302 from the above command, run the following:

curl -o "{filename}.zip" -L "https://api.crowdflower.com/v1/jobs/{job_id}.csv?type={report_type}&key={api_key}"

Options for report_type:

  • full - Returns the Full report containing every judgment
  • aggregated - Returns the Aggregated report containing the aggregated response for each row
  • json - Returns the JSON report containing the aggregated response, as well as the individual judgments, for the first 50 rows
  • gold_report - Returns the Test Question report
  • workset - Returns the Contributor report
  • source - Returns a CSV of the source data uploaded to the job

 

Get all Judgments per Row

Gets all Judgments received for the Row indicated in the request.

curl -X GET https://api.crowdflower.com/v1/jobs/{job_id}/units/{unit_id}/judgments.json?key={api_key}

Response: JSON array of all Judgments received for the Row indicated in the request.

 

Get Rows and their Judgments

Gets Rows with Judgment information for the job_id indicated in the request.

curl -X GET "https://api.crowdflower.com/v1/jobs/{job_id}/judgments.json?key={api_key}&page={1}"

Response: JSON array of 100 rows with received judgments for the Job indicated in the request. In order to get the next 100 rows, you must increment the value of page. Keep doing so until an empty hash is returned.

 

 

Account Information


 

Get all Jobs

Queries for all Jobs under the Account related to the API key in the request

curl -X GET https://api.crowdflower.com/v1/jobs.json?key={api_key}

Response: JSON representation of the latest 10 Jobs.  Use page={n} query to get additional Jobs.

 

​Get Account Information

Retrieves the CrowdFlower account information related to the key value in the request

curl -X GET https://api.crowdflower.com/v1/account.json?key={api_key}

Response: JSON account object, including company name, account balance, and plan type

 

 

List of Operations


An operation is a request that invokes a server-side procedure.  All Jobs-resource operations are are invoked at the /jobs or /jobs/{job_id} endpoint.
 

Upload

Method

Endpoint

Parameters


POST

/jobs/upload 
or
​/jobs/{job_id}/upload


See Uploading and Posting Data

 

Copy

Method

Endpoint

Parameters




GET




​/jobs/{job_id}/copy

 

Pause

Method

Endpoint

Notes




GET




/jobs/{job_id}/pause

  • You can pause a job at any time if you want to temporarily stop judgments from coming
  • ​Paused jobs may be resumed
  • See example request

 

Resume

Method

Endpoint

Notes



GET



/jobs/{job_id}/resume

 

Cancel

Method

Endpoint

Notes





GET





/jobs/{job_id}/cancel

  • You can cancel a job at any time if you want to permanently stop judgments from coming in and refund your account for any judgments not yet received
  • ​Canceled Jobs may not be resumed or ordered
  • See example request

 

Status

Method

Endpoint

Notes



GET 



/jobs/{job_id}/ping

  • You can check the status/progress of your job at any time with this operation
  • See example request

 

Legend

Method

Endpoint

Notes



GET



/jobs/{job_id}/legend

  • The legend displays the generated keys that will be submitted with your form
  • See example request

Was this article helpful?
0 out of 0 found this helpful


Have more questions? Submit a request
Powered by Zendesk