MTurk Requester API Migration Guide

5 min readMar 26, 2019

As announced on March 28, 2019, we will deprecate older versions of the MTurk Requester API and final support will end on June 1, 2019. This post will guide developers currently using a legacy API through the migration to the new API. The guide is split into sections based on functionality, and walks through the updates you need to make to your code to use the new API.

Installation

Please refer to the AWS documentation to install the SDK or Command Line Interface (CLI) you prefer.

You can use MTurk with the following languages and frameworks:

This guide will use Python as an example, showing how to migrate from boto2 to boto3. In addition to the tutorials linked above, we have code samples that use the new API for Java, Ruby, and JavaScript on GitHub.

Client Construction

Old API

import boto
from boto.mturk.connection import MTurkConnection# Create your connection to MTurk
mturk = MTurkConnection(aws_access_key_id='your_access_key_here',
    aws_secret_access_key='your_secret_key_here',
    host='mechanicalturk.sandbox.amazonaws.com')account_balance = mturk.get_account_balance()[0]
print "You have a balance of: {}".format(account_balance)

New API

import boto3

mturk = boto3.client(
    'mturk',
    endpoint_url='https://mturk-requester-sandbox.us-east-1.amazonaws.com',
    region_name='us-east-1',
    aws_access_key_id='your_access_key_here',
    aws_secret_access_key='your_secret_key_here',
)

print(mturk.get_account_balance()['AvailableBalance'])

Creating HITs

Old API

import boto
from boto.mturk.connection import MTurkConnection
from boto.mturk.question import HTMLQuestion# Create your connection to MTurk
mturk = MTurkConnection(aws_access_key_id='your_access_key_here',
    aws_secret_access_key='your_secret_key_here',
    host='mechanicalturk.sandbox.amazonaws.com')question_html_value = """
<html>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
<script src='https://s3.amazonaws.com/mturk-public/externalHIT_v1.js' type='text/javascript'></script>
</head>
<body><!-- HTML to handle creating the HIT form -->
<form name='mturk_form' method='post' id='mturk_form' action='https://workersandbox.mturk.com/mturk/externalSubmit'>
<input type='hidden' value='' name='assignmentId' id='assignmentId'/><!-- This is where you define your question(s) --> 
<h1>Please name the company that created the iPhone</h1>
<p><textarea name='answer' rows=3 cols=80></textarea></p><!-- HTML to handle submitting the HIT -->
<p><input type='submit' id='submitButton' value='Submit' /></p></form>
<script language='Javascript'>turkSetAssignmentID();</script>
</body>
</html>
"""# The first parameter is the HTML content
# The second is the height of the frame it will be shown in
# Check out the documentation on HTMLQuestion for more details
html_question = HTMLQuestion(question_html_value, 500)# These parameters define the HIT that will be created
# question is what we defined above
# max_assignments is the # of unique Workers you're requesting
# title, description, and keywords help Workers find your HIT
# duration is the # of seconds Workers have to complete your HIT
# reward is what Workers will be paid when you approve their work
# Check out the documentation on CreateHIT for more details
response = mturk.create_hit(question=html_question,
                            max_assignments=1,
                            title="Answer a simple question",
                            description="Help research a topic",
                            keywords="question, answer, research",
                            duration=120,
                            reward=0.50)# The response included several fields that will be helpful later
hit_type_id = response[0].HITTypeId
hit_id = response[0].HITIdprint "Your HIT has been created. You can see it at this link:"
print "https://workersandbox.mturk.com/mturk/preview?groupId={}".format(hit_type_id)
print "Your HIT ID is: {}".format(hit_id)

New API

For a step-by-step tutorial, please read our blog post which walks you through the HIT creation process.

import boto3

mturk = boto3.client(
    'mturk',
    endpoint_url='https://mturk-requester-sandbox.us-east-1.amazonaws.com',
    region_name='us-east-1',
    aws_access_key_id='your_access_key_here',
    aws_secret_access_key='your_secret_key_here',
)question = """
<html>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
<script src='https://s3.amazonaws.com/mturk-public/externalHIT_v1.js' type='text/javascript'></script>
</head>
<body><!-- HTML to handle creating the HIT form -->
<form name='mturk_form' method='post' id='mturk_form' action='https://workersandbox.mturk.com/mturk/externalSubmit'>
<input type='hidden' value='' name='assignmentId' id='assignmentId'/><!-- This is where you define your question(s) --> 
<h1>Please name the company that created the iPhone</h1>
<p><textarea name='answer' rows=3 cols=80></textarea></p><!-- HTML to handle submitting the HIT -->
<p><input type='submit' id='submitButton' value='Submit' /></p></form>
<script language='Javascript'>turkSetAssignmentID();</script>
</body>
</html>
"""new_hit = mturk.create_hit(
    Title = 'Answer a simple question',
    Description = 'Help research a topic',
    Keywords = 'question, answer, research',
    Reward = '0.15',
    MaxAssignments = 1,
    LifetimeInSeconds = 172800,
    AssignmentDurationInSeconds = 600,
    AutoApprovalDelayInSeconds = 14400,
    Question = question,
)print "HITID = " + new_hit['HIT']['HITId']

Getting Results

Old API

# Use the HIT ID previously created
hit_id = 'PASTE_IN_YOUR_HIT_ID'
worker_results = mturk.get_assignments(hit_id)assignment = worker_results[0]
worker_id = assignment.WorkerId
for answer in assignment.answers[0]:
  if answer.qid == 'answer':
    worker_answer = answer.fields[0]print "The Worker with ID {} and gave the answer {}".format(worker_id, worker_answer)

New API

Note: GetAssignmentsForHIT is renamed to ListAssignmentsForHIT on the new API. See below for other renamed operations.

# You will want to use the following library
# to help parse the XML answers supplied from MTurk
# Install it in your local environment with
# pip install xmltodict
import xmltodict# Use the HIT ID previously created
hit_id = 'PASTE_IN_YOUR_HIT_ID'worker_results = mturk.list_assignments_for_hit(HITId=hit_id, AssignmentStatuses=['Submitted'])if worker_results['NumResults'] > 0:
   for assignment in worker_results['Assignments']:
      xml_doc = xmltodict.parse(assignment['Answer'])
      
      print "Worker's answer was:"
      if type(xml_doc['QuestionFormAnswers']['Answer']) is list:
         # Multiple fields in HIT layout
         for answer_field in xml_doc['QuestionFormAnswers']['Answer']:
            print "For input field: " + answer_field['QuestionIdentifier']
            print "Submitted answer: " + answer_field['FreeText']
      else:
         # One field found in HIT layout
         print "For input field: " + xml_doc['QuestionFormAnswers']['Answer']['QuestionIdentifier']
         print "Submitted answer: " + xml_doc['QuestionFormAnswers']['Answer']['FreeText']
else:
   print "No results ready yet"

Other Operations

Migrating your other operations should be just as easy. Please refer to the API documentation for detailed input/output formats.

Renamed Operations

Some operation were renamed on the new API for consistency with other AWS services.

ApproveRejectedAssignment → ApproveAssignment (with an OverrideRejection parameter set to true)

AssignQualification → AssociateQualificationWithWorker

BlockWorker → CreateWorkerBlock

ChangeHITTypeOfHIT → UpdateHITTypeOfHIT

DisposeHIT → DeleteHIT

GrantQualification → AssociateQualificationWithWorker

DisposeQualificationType → DeleteQualificationType

ExtendHIT (adding time) → UpdateExpirationForHIT

ExtendHIT (adding assignments) → CreateAdditionalAssignmentsForHIT

ForceExpireHIT → UpdateExpirationForHIT (with the ExpireAt parameter set to now())

GetAssignmentsForHIT → ListAssignmentsForHIT

GetBlockedWorkers → ListWorkerBlocks

GetBonusPayments → ListBonusPayments

GetHITsForQualificationType → ListHITsForQualificationType

GetQualificationsForQualificationType → ListWorkersWithQualificationType

GetQualificationRequests → ListQualificationRequests

GetReviewableHITs → ListReviewableHITs

GetReviewResultsForHIT → ListReviewPolicyResultsForHIT

GrantBonus → SendBonus

GrantQualification → AssociateQualificationWithWorker

RegisterHITType → CreateHITType

RevokeQualification → DisassociateQualificationWithWorker

SearchHITs → ListHITs (note that the SortProperty and SortDirection parameters are no longer supported)

SearchQualificationTypes → ListQualificationTypes (note that the SortProperty and SortDirection parameters are no longer supported)

SetHITAsReviewing → UpdateHITReviewStatus

SetHITTypeNotification → UpdateNotificationSettings

UnblockWorker → DeleteWorkerBlock

UpdateQualificationScore → AssociateQualificationWithWorker

New Operations

Some functionality was moved to its own operation.

CreateHIT (passing in a HITTypeID): This is now a separate operation, CreateHITWithHITType. You can still pass all the HITType-related parameters directly into CreateHIT as well.

ExtendHIT (adding assignments): This is now a separate operation, CreateAdditionalAssignmentsForHIT.

Deprecated Operations

The following operations are no longer supported:

DisableHIT: The DisableHIT operation removes a HIT from the Amazon Mechanical Turk marketplace, approves any submitted assignments pending approval or rejection, and disposes of the HIT and all assignment data. To achieve the same outcome on the new API, you call UpdateExpirationForHIT and DeleteHIT. You can also retrieve all the un-reviewed assignments and approve them using ListAssignmentsForHIT and ApproveAssignment if you wish to manually approve them prior to the auto-approval time.

GetRequesterStatistic and GetRequesterWorkerStatistic: These operations are not supported on the new API. Please contact us at requester-legacyapideprecation-support@amazon.com if you depend on these operations.

Additional Help

Step by step Getting Started Guide

Code samples on GitHub

Latest SDK API Reference

This guide is intended to make transitioning from the legacy MTurk Requester API to the new MTurk Requester API as easy and quick as possible. If you have any additional questions or feedback, please do not hesitate to contact us at requester-legacyapideprecation-support@amazon.com or post on our forum.

MTurk Requester API Migration Guide

Installation

Client Construction

Old API

New API

Creating HITs

Old API

New API

Getting Results

Old API

New API

Other Operations

Renamed Operations

New Operations

Deprecated Operations

Additional Help

Written by Amazon Mechanical Turk