Jobs
A Job is the basis for all other resources. It contains all of the information needed to display the task in one of our labor pools and to aggregate the results once they have been collected. With CML it defines output judgement structure as well as the way job input data is represented.
Attributes
Read / Write
- auto_order
- auto_order_threshold
- auto_order_timeout
- cml
- cml_fields
- confidence_fields
- css
- custom_key
- excluded_countries
- gold_per_assignment
- included_countries
- instructions
- js
- judgments_per_unit
- language
- max_judgments_per_unit
- max_judgments_per_worker
- min_unit_confidence
- options
- pages_per_assignment
- problem
- send_judgments_webhook
- state
- title
- units_per_assignment
- webhook_uri
Read-only
- completed
- completed_at
- created_at
- gold
- golds_count
- id
- judgments_count
- units_count
- updated_at
Methods
Common
| Action | URL / Params | Verb |
|---|---|---|
| Create | /jobs | POST |
| Read | /jobs/($JOB_ID) | GET |
| Update | /jobs/$JOB_ID | PUT |
| Delete | /jobs/$JOB_ID | DELETE |
Parameters
Create and Update both accept the Read / Write attributes listed above. Be sure to prepend “job” to each url parameter, e.g.:
job[title]=Some+title&job[instructions]=InstructionsCopy
Copying jobs is great way to group your work into “batches.”
| Action | URL / Params | Verb |
|---|---|---|
| Copy | /jobs/$JOB_ID/copy | POST |
Parameters
- all_units (default: false)
- If set to true, all of this job’s units will be copied to the new job.
- gold (default: false)
- If set to true, only golden units will be copied to the new job.
Response
A successful request will return the job that the data was loaded into.
Pause
You can pause a job at any time if you want to temporarily stop judgments from coming in.
| Action | URL / Params | Verb |
|---|---|---|
| Pause | /jobs/$JOB_ID/pause | GET |
Response
A successful request returns the job that was paused.
Resume
You can resume a paused job at any time.
| Action | URL / Params | Verb |
|---|---|---|
| Resume | /jobs/$JOB_ID/resume | GET |
Response
A successful request returns the job that was resumed.
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.
| Action | URL / Params | Verb |
|---|---|---|
| Cancel | /jobs/$JOB_ID/cancel | GET |
Response
A successful request returns the job that was paused.
Status
You can check the status/progress of your job at any time with this method.
| Action | URL / Params | Verb |
|---|---|---|
| Status | /jobs/$JOB_ID/ping | GET |
Response
{
"all_judgments": 50,
"golden_judgments": 5,
"tainted_judgments": 15,
"needed_judgments": 200,
"all_units": 100,
"golden_units": 10
}Legend
The legend will show you the generated keys that will end up being submitted with your form.
| Action | URL / Params | Verb |
|---|---|---|
| Legend | /jobs/$JOB_ID/legend | GET |
Response
{
"phone_number": "Phone number",
"website_url": "Website URL",
"email_address": "Email address"
}Adding / Removing Gold
You can add or remove gold-quality checking units via this API call.
| Action | URL / Params | Verb |
|---|---|---|
| Add/Remove Gold | /jobs/$JOB_ID/gold | PUT |
Parameters
- reset
- If set, all units currently flagged as gold will be de-flagged, and the job will no longer be configured with gold.
- check
- This field is required if you are adding gold. It must be set to the name of the field being checked against your quality control set. This name is always lower cased and under scored (
like_this_example). You can find the name that was generated for you by using thelegendAPI call on a job. - with
- This field is optional. It should correspond to the column in the spreadsheet you uploaded that contains your quality control data. If it is not specified the value of “_gold” will be appended to the value of
check— e.g. Ifcheckis set to “phone,”withwill default to “phone_gold.”
Response
Upon success you will be informed of the number of units flagged as gold, and the unique set of values in your gold set:
{
"affected": 5,
"populated": ["(123) 456-7890", "(800) 111-1111"]
}Creation of the gold can fail for a few reasons. If a gold set could not be created for the specified column, the response status will be 400, and the body will be one of the following:
{
"error": {
"message": "We couldn't find any prepopulated gold standard in your dataset."
}
}{
"error": {
"message": "We didn't mark any rows as gold because marking 100 rows would have affected over 1/3rd of them."
}
}These errors are related to the number of units with non-empty values in your data set. We generally recommend having approximately 10% of your entire data set flagged as gold. More than 33% is currently not allowed.
Channels
You can view and update the job’s channels via this API call.
| Action | URL / Params | Verb |
|---|---|---|
| View Channels | /jobs/$JOB_ID/channels | GET |
| Set Channels | /jobs/$JOB_ID/channels | PUT |
Parameters
- channels
- An array containing the names of the channels that you would like to enable.
Response
The GET request will return a JSON response that lists the available and enabled channels for this job:
{
"enabled_channels": [
"amt"
]
"available_channels": [
"amt",
"sama",
"gambit",
"mob",
"iphone"]
}A PUT request allows you to set the channels for this job:
curl -d 'channels[]=amt&channels[]=mob' https://api.crowdflower.com/v1/jobs/$JOB_ID/channels?key=$API_KEYThe response will contain a success or error message, the list of available channels, and the list of enabled channels.
{
"success":"The job has been updated."
"enabled_channels":["amt","gambit","mob","sama"],
"available_channels":["amt","gambit","iphone","mob","sama"]
}{
"error":"The channel amtt could not be found."
"enabled_channels":[],
"available_channels":["amt","gambit","iphone","mob","sama"]
}
