Jobs Resource Attributes – Appen Success Center

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	Primary key This value informs the Jobs resource endpoint for working with existing Jobs
`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: include_unfinished
`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	A 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	Defaults none Dependent fields: max_judgments_per_unit min_unit_confidence confidence_fields expected_judgments_per_unit "Unit" refers to Row. The former term is eliminated in the UI. "Variable Judgments Mode" refers to Dynamic Judgments. The former term is eliminated in the UI.
`webhook_uri`	String	the URL of a webhook to fire when important events like row or job completion occur	See Webhooks