Follow

Jobs Resource Attributes

This document lists and defines the attributes of the Jobs object. Refer to the Appen REST API document for comprehensive information about integrating with the Appen API.

Please visit this link for our new Developer API Documentation.

Read-only Attributes

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

The Job object attributes listed in this section are read-only, but are returned in the JSON of many requests. 

Attribute

Type

Description

Notes

completed

Boolean

Indicates whether the Job has collected all of its ordered judgments Defaults to false until Job reaches finished state

completed_at

String UTC date/timestamp that specifies when the Job was completed, reaching finished state Null until Job is completed

created_at

String UTC date/timestamp that specifies when the Job was created Successful creation of a Job via API is indicated by receipt of the new Job's JSON structure in response to a POST request sent to the /jobs resource

crowd_costs

Number Cost of the Job in USD Returns the cost of the Job at the time of the request

gold

Object Object containing generated Test Question keys
  • Returns CML field input labels for each Row as keys (e.g., "select_one": "select_one_gold")
  • "Gold" refers to Test Questions. The former term is eliminated in the UI and deprecated in future API versions

gold_per_assignment

Integer The number of Test Questions included on each Page "Gold" refers to Test Questions. This term is eliminated in the UI and deprecated in future API versions.  

golds_count

Integer Indicates the number of Rows designated as Test Questions in the Job

"Gold" refers to Test Questions. The former term is eliminated in the UI and deprecated in future API versions.  

id

Integer A unique number assigned by the Appen platform when a Job is created

judgments_count

Integer The number of Judgments the Job has received at the time of the request  

state

String

The lifecycle state of the Job at the time of the request.  There are five Job states, each described at right. Unordered
The Job has been created, but not ordered ("launched," via UI). Ordering/launching a Job occurs at the point of payment.
Running
The Job has been ordered/launched, and is available to workers for the collection of judgments
Paused
The Job has been paused by invoking the Pause operation
Finished
The Job has collected all of the Judgments ordered
Canceled
The Job was canceled by invoking the Cancel operation

units_count

Integer The number of Rows that comprise the Job If Auto Launch is enabled, the value of units_count will increase when new Rows are automatically ordered.

"Unit" refers to Row. The former term is eliminated in the UI.  

updated_at

String The date and time at which changes to Job settings were last made via API (or saved via UI). UTC date/timestamp

 

 

Read-write Attributes

The attributes listed below can be combined in parameterized requests to effect updates and/or other changes to Appen Jobs.

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

 

 

Attribute

Type

Description

Notes

alias String An alternate "title" for your job that can be substituted with and for other Job aliases when performing Jobs in sequence or workflows.
  • May be updated throughout the life of the Job
  • Pro feature
auto_order_threshold Integer The job must have at least this many new rows—or the timeout must have passed—before new rows will be ordered automatically.
  • This setting must be greater than the number of rows per page minus the number of Test Questions shown per page
  • Only applicable when auto_order is enabled
auto_order_timeout Integer The time in seconds before automatic ordering of any new rows will occur Only applicable when auto_order is enabled

"Auto Order" refers to Auto Launch. The former term is eliminated in the UI.  

auto_order Boolean Automatically launch rows as they are added to the Job
  • Defaults false
  • Account must have sufficient funds available to cover automatic ordering of rows
  • "Auto Order" refers to Auto Launch. The former term is eliminated in the UI.  
cml String The Custom Markup Language that comprises the form served to Contributors.  Rendered per Row
css String
  • Custom CSS to be included in form rendering
  • Any CSS added to the Job via the Code Editor interface
CSS evaluated once per Page
expected_judgments_per_unit Integer The average number of judgments you expect the row to collect. 
  • Setting this value allows the platform to to better predict when your job will complete
  • Relevant only when Dynamic Judgments is enabled
  • "Unit" refers to Row. The former term is eliminated in the UI.  
fields Object Object containing generated CML form elements and their attributes  Returns CML form elements as keys that contain the input type and attribute 
include_unfinished Boolean Determines whether unfinished rows will be included in the Full Report.
  • Defaults true
  • Returned in the Options object

UI location:
/settings/reports

included_countries Array Array of countries targeted for participation in Job. UI location:
/settings/geography
instructions String Instructions informing Contributors how to complete the Pages that comprise the Job At minimum, your job must have a valid title, instructions, and one "required" CML form element to be saved successfully. 
js String
  • Custom Javascript to be included in form
  • Any Javascript added to the Job via the UI
Runs once at page load.
judgments_per_unit Integer Specifies the number of Judgments that each Row in the Job will receive. 
  • For survey jobs, enter the number of times you want the survey to be completed
  • For jobs with data, 3 Judgments Per Row is the norm
  • "Unit" refers to Row. The former term is eliminated in the UI.  
max_judgments_per_unit Integer The Job will collect no more judgments than indicated by the value of this attribute.
  • Relevant only when Dynamic Judgments is enabled
  • Note that the Judgments Per Row setting will be the minimum number of judgments that each row collects when Dynamic Judgments is enabled. For Dynamic Judgments, we recommend 2 Judgments per Row, 5 Max Judgments per Row, with a Minimum Confidence Score of 0.7.
  • "Unit" refers to Row. The former term is eliminated in the UI.  
min_unit_confidence Integer Collection of judgments on a row will cease when the rows's confidence score is above the value of this attribute
  • We recommend a min_unit_confidence of 0.7
  • Confidence scores fall between 0 and 1, and are a function of contributor agreement on a row
  • Relevant only when Dynamic Judgments is enabled
  • "Unit" refers to Row. The former term is eliminated in the UI.  
minimum_requirements Object Object containing key-value pairs for any skills required of Contributors

UI location:

/settings/skills

options Object Object containing values for options selected for the Job Keys in Options object include:
payment_cents Number The amount in USD that Contributors are paid for completion of each Page.  
problem String The Custom Markup Language that comprises the form served to Workers.   
support_email String The email address of the account holder UI location:
/settings/general
title String The title given to a specific Job At minimum, your job must have a valid title, instructions, and one required CML form element to be saved successfully. 
units_per_assignment Integer The number of Rows a Contributor must complete, per page, before submitting their Judgments Defaults 5

"Unit" refers to Row. The former term is eliminated in the UI.  

units_remain_finalized Boolean true value prevents collection of more judgments when Contributors become Untrusted and are removed from the Job. By default, when contributors fail too many Test Questions, their judgments are removed from the job and additional, compensatory judgments are collected.

"Unit" refers to Row. The former term is eliminated in the UI.  

uri String When uploading data feed content to a new or existing Job, this attribute's value sets the URL/query string with which to pull data into the Job. 
  • Attribute is not returned in Job object JSON
  • See example request for syntax
variable_judgments_mode String
  • Dynamic Judgments allows the collection of more judgments if contributors disagree on an answer
  • Values:
    none
    auto_confidence
    external
webhook_uri String the URL of a webhook to fire when important events like row or job completion occur See Webhooks

 

 


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


Have more questions? Submit a request
Powered by Zendesk