Appen API Requests Guide – Appen Success Center

We've formatted some common Appen 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.

Please visit this link for our new Developer API Documentation.

Request Conventions

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

Whatever client you use to reach Appen 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
The API token should be included in every request as part of the header
- headers: {"AUTHORIZATION" => "Token token={token}"}
Passing the API token as a query parameter is currently supported, but is not recommended for security reasons. This support will be deprecated in the future.

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 -H 'Authorization: Token token={api_key}' -X POST https://api.appen.com/v1/jobs.json

Response: JSON Representation of new Job

Create a Job with Title and Instructions

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

curl -H 'Authorization: Token token={api_key}' -X POST --data-urlencode "job[title]={some_title}" --data-urlencode "job[instructions]={some_instructions}" https://api.appen.com/v1/jobs.json

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 -H 'Authorization: Token token={api_key}' "Content-Type: application/json" -X POST -T "{sample_data.json}" https://api.appen.com/v1/jobs/upload.json

Response: JSON representation of new Job

Example JSON file: sample_data.json (please use the JSON Lines format)

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 -H 'Authorization: Token token={api_key}' -X POST -T "{sample_data.csv}" -H "Content-Type: text/csv" https://api.appen.com/v1/jobs/upload.json

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 -H 'Authorization: Token token={api_key}' -X GET "https://api.appen.com/v1/jobs/{job_id}/copy.json?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 -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/copy.json

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 -H 'Authorization: Token token={api_key}' -X GET "https://api.appen.com/v1/jobs/{job_id}/copy.json?gold=true"

Response: JSON representation of Job

Copy a Job to a different team

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 -H 'Authorization: Token token={api_key}' -X GET -d "team_id={team_id} "https://api.appen.com/v1/jobs/{job_id}/copy.json"

Response: JSON representation of Job

Update Job Title

Updates the Title of the Job.

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "job[title]={some_new_title}" https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job
See Note

If your job contains output names that are the same as headers in data you originally uploaded you will need to add "ignore_overlapping_names=true" to this call.

Update Job Instructions

Updates the instructions of a Job

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode 'job[instructions]={updated_instructions}' https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job
See Note

Update Job CML

Updates the CML of the Job.

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode 'job[cml]={some_new_cml}' https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job

Update Job Language

GET /v1/jobs/:id/languages - get available languages in format Array<{ id: number; name: string }> - response is the same for every job.
GET /v1/jobs/:id/language - get current job language setting { id: number; name: string }
PUT /v1/jobs/:id/language with json body { "language_id": number } - set job language setting.

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 -H 'Authorization: Token token={api_key}' -X PUT -T cf_sample_data.csv -H "Content-Type: text/csv" "https://api.appen.com/v1/jobs/{job_id}/upload.json?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 -H 'Authorization: Token token={api_key}' -X PUT -T "{sample_data.json}" -H "Content-Type: application/json" https://api.appen.com/v1/jobs/{job_id}/upload.json

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 -H 'Authorization: Token token={api_key}' -X PUT -T "{sample_data.json}" -H "Content-Type: application/json" "https://api.appen.com/v1/jobs/{job_id}/upload.json?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 -H 'Authorization: Token token={api_key}' -X GET "https://api.appen.com/v1/jobs/{job_id}/units.json?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 -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "unit[state]={new}" https://api.appen.com/v1/jobs/{job_id}/units/{unit_id}.json

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

Get Row Count

Gets count of all Rows in a Job

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/units/ping.json

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 -H 'Authorization: Token token={api_key}' -X POST -d "unit[data][{column1}]={some_data_1}" -d "unit[data][{column2}]={some_data_2}" https://api.appen.com/v1/jobs/{job_id}/units.json

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")

Cancel a Unit

Will cancel a unit in state 'New'. Note that units with collected judgements cannot be cancelled.

curl -H 'Authorization: Token token={api_key}' -X POST https://api.appen.com/v1/jobs/{job_id}/units/{unit_id}/cancel.json

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 -H 'Authorization: Token token={api_key}' -X PUT https://api.appen.com/v1/jobs/{job_id}/gold.json

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 -H 'Authorization: Token token={api_key}' -X GET 'https://api.appen.com/v1/jobs/{job_id}/units/split?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 -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "job[payment_cents]={20}" https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job

Set Judgment Per Row

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

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "job[judgments_per_unit]={3}" https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job

Note: Unit in the API command refers to a row in the job.

Set Time Per Assignment

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

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "job[options][req_ttl_in_seconds]={n}" https://api.appen.com/v1/jobs/{job_id}.json

Set Rows per Page

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

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "job[units_per_assignment]={n}" https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job

Set Dynamic Judgments

Sets parameters for collecting dynamic judgments for exactly one question:

curl -H 'Authorization: Token token={api_key}' -X PUT -d "job[variable_judgments_mode]={auto_confidence}" -d "job[options][confidence_fields][]={cml_question}" -d "job[max_judgments_per_unit]={n}" -d "job[min_unit_confidence]={m}" https://api.appen.com/v1/jobs/{job_id}.json

Sets parameters for collecting dynamic judgments for one or more questions:

curl -H 'Authorization: Token token={api_key}' -X PUT -d "job[variable_judgments_mode]=auto_confidence" -d "job[max_judgments_per_unit]={n}" -d "job[min_unit_confidence]={m}" -d "job[options][confidence_fields][]={cml_question1}" -d "job[options][confidence_fields][]={cml_question2}" https://api.appen.com/v1/jobs/{job_id}.json

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.appent.com/hc/en-us/articles/203219205-Job-Settings-Guide-to-Dynamic-Judgments

Job Tagging

To view all tags in a Job:

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/tags

To add a new tag to a Job:

curl -H 'Authorization: Token token={api_key}' -X POST --data-urlencode "tags={tag}" https://api.appen.com/v1/jobs/{job_id}/tags

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

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "tags={tag1, tag2}" https://api.appen.com/v1/jobs/{job_id}/tags

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 -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/channels

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

curl -H 'Authorization: Token token={api_key}' -X POST --data-urlencode "channels={clixsense}" https://api.appen.com/v1/jobs/{job_id}/channels

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

curl -H 'Authorization: Token token={api_key}' -X POST --data "channel_name={CHANNEL}" 'https://api.appen.com/v1/jobs/{job_id}/disable_channel'

Response: JSON representation of enabled Channels

To target specific countries in the job can be accessed:

curl -H 'Authorization: Token token={api_key}' "Content-Type: application/json" -X PUT --data '{"job": {"included_countries":["US","GB"]}' https://api.appen.com/v1/jobs/{job_id}.json

Turn Auto Launch On or Off

Toggles Auto Launch on or off.

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "job[auto_order]=true" https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job

Get Results - Launch

Launch a Job

Launches ("orders") a Job

To launch to the On Demand Workforce:

curl -H 'Authorization: Token token={api_key}' -X POST -d "channels[0]=on_demand&debit[units_count]={100}" https://api.appen.com/v1/jobs/{job_id}/orders.json

To launch to the Internal Channel:

curl -H 'Authorization: Token token={api_key}' -X POST -d "channels[0]=cf_internal&debit[units_count]={100}" https://api.appen.com/v1/jobs/{job_id}/orders.json

To launch to both:

curl -H 'Authorization: Token token={api_key}' -X POST -d "channels[0]=on_demand&channels[1]=cf_internal&debit[units_count]={100}" https://api.appen.com/v1/jobs/{job_id}/orders.json

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

Pause a Job

Pauses a Job that is currently running.

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id/pause.json

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

Resume a Job

Resumes a Job that had been paused

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/resume.json

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

Cancel a Job

Cancels a Job

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/cancel.json

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

Disable a Test Question

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "unit[state]=hidden_gold" https://api.appen.com/v1/jobs/{job_id}/units/{unit_id}.json

Response: JSON application response

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 -H 'Authorization: Token token={api_key}' -X POST --data-urlencode "amount={amount_in_cents}" https://api.appen.com/v1/jobs/{job_id}/workers/{worker_id}/bonus.json

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 -H 'Authorization: Token token={api_key}' -X POST --data-urlencode "message={message_to_worker}" https://api.appen.com/v1/jobs/{job_id}/workers/{worker_id}/notify.json

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" button on the Contributors page.

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "flag={reason_for_flagging_contributor}" https://api.appen.com/v1/jobs/{job_id}/workers/{worker_id}.json

Response: JSON application message indicating status of operation

Flag a Contributor Across All Jobs

Flags a contributor with the reason indicated in the request across all jobs for a user. Corresponds to the "Flag" button on the Contributors page.

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "flag={reason}" https://api.appen.com/v1/jobs/{job_id}/workers/{contributor_id}.json?persist=true

Response: JSON application message indicating status of operation

Unflag a Contributor

Unflags a contributor with the reason indicated in the request.

curl -H 'Authorization: Token token={api_key}' -X PUT --data-urlencode "unflag={reason_for_unflagging_contributor}" https://api.appen.com/v1/jobs/{job_id}/workers/{worker_id}.json

Response: JSON application message indicating status of operation

Reject a Contributor

Rejects a contributor with the reason indicated in the request.

curl -H 'Authorization: Token token={api_key}' -X PUT -d 'reason={input_reason}' -d 'manual=true' https://api.appen.com/v1/jobs/{job_id}/workers/{worker_id}/reject.json

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 -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/ping.json

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 includes the total cost and job state.

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}.json

Response: JSON representation of Job

Get Results - Results

Job Reports

To regenerate a report in a job:

curl -H 'Authorization: Token token={api_key}' -X POST "https://api.appen.com/v1/jobs/{job_id}/regenerate?type={report_type}"

To download a report from a job, first run the following command:

curl -H 'Authorization: Token token={api_key}' -s -o /dev/null -w "%{http_code}" "https://api.appen.com/v1/jobs/{job_id}.csv?type={report_type}"

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

curl -H 'Authorization: Token token={api_key}' -o "{filename}.zip" -L "https://api.appen.com/v1/jobs/{job_id}.csv?type={report_type}"

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
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 -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/units/{unit_id}/judgments.json

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 -H 'Authorization: Token token={api_key}' -X GET "https://api.appen.com/v1/jobs/{job_id}/judgments.json?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.

Fetching aggregated result in JSON for a single row
Get source data, all judgements and aggregate result for a specified row.

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs/{job_id}/units/{unit_id}.json

Response: JSON array of aggregated result received for the Row indicated in the request.

Account Information

Get all Jobs for User

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

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/jobs.json

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

Get all Jobs for Team

Queries for all Jobs under the team specified as a parameter. The API key used to make the call should belong to a user on the team.

curl -H 'Authorization: Token token={api_key}' -X GET "https://api.appen.com/v1/jobs.json?team_id={team_id}"

Additionally, if teams have been grouped into an organization, the organization admin can retrieve jobs for different teams in the organization by providing the appropriate team_id parameter.

If you do not know your team ID, please get in touch with help@appen.com.

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

Get Account Information

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

curl -H 'Authorization: Token token={api_key}' -X GET https://api.appen.com/v1/account.json

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`	Upload rows to a job using this endpoint The API currently only supports JSON If uploading multiple rows, use Newline Delimited JSON (ndJSON) See Uploading and Posting Data

Copy

Method	Endpoint	Parameters
GET	`/jobs/{job_id}/copy`	`all_units` copies all units to new Job `gold` copies only Test Questions to new Job See example requests for request syntax and parameter use

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`	You can resume a paused job at any time See example request

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