Amazon Mechanical Turk API Reference API Version 2013-11-15 Amazon Mechanical Turk API Reference Amazon Mechanical Turk: API Reference Copyright © 2014 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront, Cloudfront, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon. Amazon Mechanical Turk API Reference Table of Contents Welcome ..................................................................................................................................... 1 WSDL and Schema Locations......................................................................................................... 2 The WSDL and Message Schema Locations.............................................................................. 3 The Data Structure Schema Locations...................................................................................... 3 The Formatted Content XHTML Subset..................................................................................... 4 The Notification API WSDL Location......................................................................................... 4 Service API Versions.............................................................................................................. 4 Accessing a Specific Service Version........................................................................................ 5 The Default Version ............................................................................................................... 5 Common Parameters ..................................................................................................................... 6 Common Request Parameters................................................................................................. 6 Response Groups ................................................................................................................. 7 Response Groups Content.............................................................................................. 8 Operations ................................................................................................................................. 10 ApproveAssignment ............................................................................................................. 11 Description ................................................................................................................. 11 Request Parameters .................................................................................................... 11 Response Elements ..................................................................................................... 12 Examples ................................................................................................................... 12 ApproveRejectedAssignment ................................................................................................. 13 Description ................................................................................................................. 13 Request Parameters .................................................................................................... 13 Response Elements ..................................................................................................... 14 Examples ................................................................................................................... 14 AssignQualification .............................................................................................................. 14 Description ................................................................................................................. 14 Request Parameters .................................................................................................... 15 Response Elements ..................................................................................................... 15 Examples ................................................................................................................... 16 BlockWorker ....................................................................................................................... 16 Description ................................................................................................................. 16 Request Parameters .................................................................................................... 17 Response Elements ..................................................................................................... 17 Examples ................................................................................................................... 17 Related Operations ..................................................................................................... 18 ChangeHITTypeOfHIT .......................................................................................................... 19 Description ................................................................................................................. 19 Request Parameters .................................................................................................... 19 Response Elements ..................................................................................................... 19 Examples ................................................................................................................... 19 CreateHIT .......................................................................................................................... 21 Description ................................................................................................................. 21 Request Parameters .................................................................................................... 21 Response Elements ..................................................................................................... 28 Examples ................................................................................................................... 28 CreateQualificationType ........................................................................................................ 32 Description ................................................................................................................. 32 Request Parameters .................................................................................................... 32 Response Elements ..................................................................................................... 34 Examples ................................................................................................................... 34 Related Operations ...................................................................................................... 35 DisableHIT ......................................................................................................................... 36 Description ................................................................................................................. 36 Request Parameters .................................................................................................... 36 Response Elements ..................................................................................................... 36 API Version 2013-11-15 iii Amazon Mechanical Turk API Reference Examples ................................................................................................................... 37 DisposeHIT ........................................................................................................................ 38 Description ................................................................................................................. 38 Request Parameters .................................................................................................... 38 Response Elements ..................................................................................................... 38 Examples ................................................................................................................... 38 DisposeQualificationType ...................................................................................................... 40 Description ................................................................................................................. 40 Request Parameters .................................................................................................... 40 Response Elements ..................................................................................................... 40 Examples ................................................................................................................... 41 Related Operations ...................................................................................................... 41 ExtendHIT .......................................................................................................................... 42 Description ................................................................................................................. 42 Request Parameters .................................................................................................... 42 Response Elements ..................................................................................................... 43 Examples ................................................................................................................... 43 ForceExpireHIT ................................................................................................................... 45 Description ................................................................................................................. 45 Request Parameters .................................................................................................... 45 Response Elements ..................................................................................................... 45 Examples ................................................................................................................... 45 GetAccountBalance ............................................................................................................. 47 Description ................................................................................................................. 47 Request Parameters .................................................................................................... 47 Response Elements ..................................................................................................... 47 Examples ................................................................................................................... 47 GetAssignment ................................................................................................................... 49 Description ................................................................................................................. 49 Request Parameters .................................................................................................... 49 Response Elements ..................................................................................................... 49 Examples ................................................................................................................... 49 Related Operations ...................................................................................................... 51 GetAssignmentsForHIT ........................................................................................................ 52 Description ................................................................................................................. 52 Request Parameters .................................................................................................... 52 Response Elements ..................................................................................................... 53 Examples ................................................................................................................... 54 Related Operations ...................................................................................................... 55 GetBlockedWorkers ............................................................................................................. 56 Description ................................................................................................................. 56 Request Parameters .................................................................................................... 56 Response Elements ..................................................................................................... 56 Examples ................................................................................................................... 57 GetBonusPayments ............................................................................................................. 59 Description ................................................................................................................. 59 Request Parameters .................................................................................................... 59 Response Elements ..................................................................................................... 60 Examples ................................................................................................................... 60 GetFileUploadURL............................................................................................................... 62 Description ................................................................................................................. 62 Request Parameters .................................................................................................... 62 Response Elements ..................................................................................................... 62 Examples ................................................................................................................... 63 GetHIT............................................................................................................................... 64 Description ................................................................................................................. 64 Request Parameters .................................................................................................... 64 Response Elements ..................................................................................................... 64 API Version 2013-11-15 iv Amazon Mechanical Turk API Reference Examples ................................................................................................................... 64 Sample Response ....................................................................................................... 65 GetHITsForQualificationType ................................................................................................. 66 Description ................................................................................................................. 66 Request Parameters .................................................................................................... 66 Response Elements ..................................................................................................... 67 Examples ................................................................................................................... 67 GetQualificationsForQualificationType ..................................................................................... 69 Description ................................................................................................................. 69 Request Parameters .................................................................................................... 69 Response Elements ..................................................................................................... 69 Examples ................................................................................................................... 70 GetQualificationRequests...................................................................................................... 72 Description ................................................................................................................. 72 Request Parameters .................................................................................................... 72 Response Elements ..................................................................................................... 73 Examples ................................................................................................................... 73 GetQualificationScore........................................................................................................... 75 Description ................................................................................................................. 75 Request Parameters .................................................................................................... 75 Response Elements ..................................................................................................... 75 Examples ................................................................................................................... 75 GetQualificationType ............................................................................................................ 77 Description ................................................................................................................. 77 Request Parameters .................................................................................................... 77 Response Elements ..................................................................................................... 77 Examples ................................................................................................................... 77 GetRequesterStatistic........................................................................................................... 79 Description ................................................................................................................. 79 Request Parameters .................................................................................................... 81 Response Elements ..................................................................................................... 82 Examples ................................................................................................................... 83 GetRequesterWorkerStatistic................................................................................................. 84 Description ................................................................................................................. 84 Request Parameters .................................................................................................... 85 Response Elements ..................................................................................................... 86 Examples ................................................................................................................... 86 GetReviewableHITs ............................................................................................................. 88 Description ................................................................................................................. 88 Request Parameters .................................................................................................... 88 Response Elements ..................................................................................................... 89 Examples ................................................................................................................... 89 GetReviewResultsForHIT ...................................................................................................... 91 Description ................................................................................................................. 91 Request Parameters .................................................................................................... 91 Response Elements ..................................................................................................... 92 ReviewResult Data Structure ......................................................................................... 92 ReviewAction Data Structure ......................................................................................... 94 Examples ................................................................................................................... 95 GrantBonus ........................................................................................................................ 99 Description ................................................................................................................. 99 Request Parameters .................................................................................................... 99 Response Elements ................................................................................................... 100 Examples ................................................................................................................. 100 GrantQualification .............................................................................................................. 102 Description ............................................................................................................... 102 Request Parameters................................................................................................... 102 Response Elements ................................................................................................... 102 API Version 2013-11-15 v Amazon Mechanical Turk API Reference Examples ................................................................................................................. 102 Help ................................................................................................................................ 104 Description ............................................................................................................... 104 Request Parameters................................................................................................... 104 Response Elements ................................................................................................... 104 Examples ................................................................................................................. 105 NotifyWorkers.................................................................................................................... 107 Description ............................................................................................................... 107 Request Parameters................................................................................................... 107 Response Elements ................................................................................................... 107 Examples ................................................................................................................. 108 RegisterHITType ................................................................................................................ 109 Description ............................................................................................................... 109 Request Parameters................................................................................................... 109 Response Elements ................................................................................................... 110 Examples ................................................................................................................. 111 RejectAssignment .............................................................................................................. 112 Description ............................................................................................................... 112 Request Parameters................................................................................................... 112 Response Elements ................................................................................................... 112 Examples ................................................................................................................. 113 RejectQualificationRequest.................................................................................................. 114 Description ............................................................................................................... 114 Request Parameters................................................................................................... 114 Response Elements ................................................................................................... 114 Examples ................................................................................................................. 114 RevokeQualification............................................................................................................ 116 Description ............................................................................................................... 116 Request Parameters................................................................................................... 116 Response Elements ................................................................................................... 116 Examples ................................................................................................................. 117 SearchHITs ...................................................................................................................... 118 Description ............................................................................................................... 118 Request Parameters................................................................................................... 118 Response Elements ................................................................................................... 119 Examples ................................................................................................................. 119 Related Operations .................................................................................................... 120 SearchQualificationTypes .................................................................................................... 121 Description ............................................................................................................... 121 Request Parameters................................................................................................... 121 Response Elements ................................................................................................... 122 Examples ................................................................................................................. 123 SendTestEventNotification ................................................................................................... 125 Description ............................................................................................................... 125 Request Parameters................................................................................................... 125 Response Elements ................................................................................................... 125 Examples ................................................................................................................. 126 SetHITAsReviewing ............................................................................................................ 127 Description ............................................................................................................... 127 Request Parameters................................................................................................... 127 Response Elements ................................................................................................... 127 Examples ................................................................................................................. 128 SetHITTypeNotification........................................................................................................ 129 Description ............................................................................................................... 129 Request Parameters................................................................................................... 129 Response Elements ................................................................................................... 130 Examples ................................................................................................................. 130 UnblockWorker .................................................................................................................. 132 API Version 2013-11-15 vi Amazon Mechanical Turk API Reference Description ............................................................................................................... 132 Request Parameters................................................................................................... 132 Response Elements ................................................................................................... 132 Examples ................................................................................................................. 132 UpdateQualificationScore .................................................................................................... 134 Description ............................................................................................................... 134 Request Parameters................................................................................................... 134 Response Elements ................................................................................................... 134 Examples ................................................................................................................. 135 UpdateQualificationType ..................................................................................................... 136 Description ............................................................................................................... 136 Request Parameters................................................................................................... 136 Response Elements ................................................................................................... 138 Examples ................................................................................................................. 138 Related Operations .................................................................................................... 139 Data Structures ......................................................................................................................... 140 Assignment....................................................................................................................... 140 Description ............................................................................................................... 140 Elements .................................................................................................................. 141 Example................................................................................................................... 142 HIT.................................................................................................................................. 144 Description ............................................................................................................... 144 HITs and Response Groups......................................................................................... 144 Elements .................................................................................................................. 144 Example................................................................................................................... 147 HITLayoutParameter........................................................................................................... 149 Description ............................................................................................................... 149 Elements .................................................................................................................. 149 HIT Review Policy .............................................................................................................. 150 Description ............................................................................................................... 150 HIT Review Policy Elements ........................................................................................ 150 Parameter Elements................................................................................................... 150 MapEntry Elements.................................................................................................... 151 Examples ................................................................................................................. 151 Locale.............................................................................................................................. 154 Description ............................................................................................................... 154 Elements .................................................................................................................. 154 Example................................................................................................................... 154 Price................................................................................................................................ 155 Description ............................................................................................................... 155 Elements .................................................................................................................. 155 Example................................................................................................................... 155 Qualification ...................................................................................................................... 157 Description ............................................................................................................... 157 Elements .................................................................................................................. 157 Example................................................................................................................... 158 QualificationRequest .......................................................................................................... 159 Description ............................................................................................................... 159 Elements .................................................................................................................. 159 Example................................................................................................................... 160 QualificationRequirement .................................................................................................... 161 Description ............................................................................................................... 161 Using Custom, System-Assigned, and Master Qualification Types ...................................... 161 Elements .................................................................................................................. 162 Qualification Type IDs ................................................................................................. 163 Master Qualifications .................................................................................................. 165 Adding Adult Content.................................................................................................. 166 The Locale Qualification.............................................................................................. 167 API Version 2013-11-15 vii Amazon Mechanical Turk API Reference Example—Using the QualificationRequirement Data Structure........................................... 167 Example—Using the QualificationRequirement Data Structure for Comparing Multiple Values...................................................................................................................... 168 QualificationType ............................................................................................................... 170 Description ............................................................................................................... 170 Elements .................................................................................................................. 170 Example .................................................................................................................. 172 Notification........................................................................................................................ 173 Description ............................................................................................................... 173 Elements .................................................................................................................. 173 Example................................................................................................................... 174 WorkerBlock ..................................................................................................................... 175 Description ............................................................................................................... 175 Elements .................................................................................................................. 175 Example................................................................................................................... 175 Review Policies.......................................................................................................................... 176 How Review Policies Work................................................................................................... 176 Assignment Review Policies................................................................................................. 177 ScoreMyKnownAnswers/2011-09-01 ............................................................................. 177 HIT Review Policies............................................................................................................ 179 SimplePlurality/2011-09-01 .......................................................................................... 179 Review Policy Use Cases.................................................................................................... 182 Photo Moderation Use Case – Single Worker with Known Answers..................................... 183 Photo Moderation Use Case – Multiple Workers with Agreement........................................ 184 Categorization and Tagging Use Case – Multiple Workers................................................. 186 Question and Answer Data.......................................................................................................... 188 Using XML Parameter Values............................................................................................... 189 XML Data as a Parameter........................................................................................... 189 Namespaces for XML Parameter Values ........................................................................ 189 QuestionForm ................................................................................................................... 189 Description ............................................................................................................... 190 QuestionForm Structure.............................................................................................. 190 Content Structure....................................................................................................... 192 Answer Specification .................................................................................................. 197 Example................................................................................................................... 203 Formatted Content: XHTML ................................................................................................. 204 Using Formatted Content ............................................................................................ 205 Supported XHTML Tags.............................................................................................. 206 How XHTML Formatted Content Is Validated.................................................................. 208 QuestionFormAnswers........................................................................................................ 210 Description ............................................................................................................... 210 The Structure of Answers............................................................................................ 210 Example................................................................................................................... 211 AnswerKey ....................................................................................................................... 211 Description ............................................................................................................... 211 The Structure of an Answer Key................................................................................... 212 Example................................................................................................................... 213 ExternalQuestion ............................................................................................................... 215 Description ............................................................................................................... 215 The ExternalQuestion Data Structure ............................................................................ 215 Example................................................................................................................... 216 The External Form ..................................................................................................... 216 The Answer Data ....................................................................................................... 218 Guidelines For Using External Questions....................................................................... 218 HTMLQuestion .................................................................................................................. 220 Description ............................................................................................................... 220 The HTMLQuestion Data Structure ............................................................................... 221 Example................................................................................................................... 221 API Version 2013-11-15 viii Amazon Mechanical Turk API Reference Preview Mode ........................................................................................................... 222 The Form Action........................................................................................................ 222 The Answer Data ....................................................................................................... 222 Guidelines For Using HTML Questions.......................................................................... 222 HITLayout......................................................................................................................... 223 Description ............................................................................................................... 223 Obtaining a Layout ID................................................................................................. 223 Using a HITLayout ..................................................................................................... 223 Guidelines for Using HITLayouts................................................................................... 224 The Notification API.................................................................................................................... 225 Elements of a Notification Message....................................................................................... 225 The Notification API Version......................................................................................... 226 Events ..................................................................................................................... 226 Notification Handling Using Amazon SQS .............................................................................. 226 Creating an SQS Queue ............................................................................................. 226 Configuring an SQS Queue ......................................................................................... 227 Amazon SQS Policy Document Example........................................................................ 227 Configuring Permissions Using the AWS Console............................................................ 228 Configuring Permissions Using the Amazon SQS API...................................................... 228 Testing Your Queue .................................................................................................... 228 Guaranteed Delivery................................................................................................... 228 SQS Message Ordering.............................................................................................. 228 Multiple SQS Queues ................................................................................................. 228 SQS Message Payload ............................................................................................... 229 Double Delivery ......................................................................................................... 229 Document History ...................................................................................................................... 230 API Version 2013-11-15 ix Amazon Mechanical Turk API Reference Welcome This is the Amazon Mechanical Turk API Reference.This guide provides detailed information about Amazon Mechanical Turk operations, data structures, and parameters.The major sections of this guide are described in the following table. Amazon Mechanical Turk is a web service that provides an on-demand, scalable, human workforce to complete jobs that humans can do better than computers, for example, recognizing objects in photos. For more information about this product go to Amazon Mechanical Turk. Operations (p.10) Alphabetical list of all Amazon Mechanical Turk operations. Data Structures (p.140) Alphabetical list of all Amazon Mechanical Turk data structures. Common Parameters (p.6) Descriptions of the parameters common to all operations. WSDL and Schema Locations (p.2) Links to Amazon Mechanical Turk WSDL and schemas. Review Policies (p.176) Description of Amazon Mechanical Turk Review Policies. Question and Answer Data (p.188) Description of question and answer data that Amazon Mechanical Turk passes between Requesters and Workers. The Notification API (p.225) Description of how Amazon Mechanical Turk sends notification messages to your application. API Version 2013-11-15 1