Amazon Mechanical Turk Legacy API Reference API Version 2014-08-15 Amazon Mechanical Turk Legacy API Reference Amazon Mechanical Turk: Legacy API Reference Copyright © 2022 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. 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 Legacy API Reference Table of Contents ........................................................................................................................................................ x Amazon Mechanical Turk Legacy API Reference ...................................................................................... 1 WSDL and Schema Locations............................................................................................................... 2 API Release Notes...................................................................................................................... 2 The WSDL and Message Schema Locations.................................................................................... 2 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 .............................................................................................. 4 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........................................................................................................... 16 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........................................................................................................... 29 Examples......................................................................................................................... 29 CreateQualificationType............................................................................................................ 32 Description...................................................................................................................... 32 Request Parameters.......................................................................................................... 32 Response Elements........................................................................................................... 34 Examples......................................................................................................................... 34 Related Operations........................................................................................................... 35 DisableHIT............................................................................................................................... 36 API Version 2014-08-15 iii Amazon Mechanical Turk Legacy API Reference Description...................................................................................................................... 36 Request Parameters.......................................................................................................... 36 Response Elements........................................................................................................... 36 Examples......................................................................................................................... 37 DisposeHIT.............................................................................................................................. 38 Description...................................................................................................................... 38 Request Parameters.......................................................................................................... 38 Response Elements........................................................................................................... 38 Examples......................................................................................................................... 39 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......................................................................................................................... 44 ForceExpireHIT......................................................................................................................... 45 Description...................................................................................................................... 45 Request Parameters.......................................................................................................... 45 Response Elements........................................................................................................... 45 Examples......................................................................................................................... 46 GetAccountBalance................................................................................................................... 47 Description...................................................................................................................... 47 Request Parameters.......................................................................................................... 47 Response Elements........................................................................................................... 47 Examples......................................................................................................................... 47 GetAssignment......................................................................................................................... 49 Description...................................................................................................................... 49 Request Parameters.......................................................................................................... 49 Response Elements........................................................................................................... 49 Examples......................................................................................................................... 50 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......................................................................................................................... 61 GetFileUploadURL.................................................................................................................... 62 Description...................................................................................................................... 62 Request Parameters.......................................................................................................... 62 Response Elements........................................................................................................... 62 Examples......................................................................................................................... 63 API Version 2014-08-15 iv Amazon Mechanical Turk Legacy API Reference GetHIT.................................................................................................................................... 64 Description...................................................................................................................... 64 Request Parameters.......................................................................................................... 64 Response Elements........................................................................................................... 64 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........................................................................................................... 70 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......................................................................................................................... 76 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...................................................................................................... 85 Description...................................................................................................................... 85 Request Parameters.......................................................................................................... 86 Response Elements........................................................................................................... 87 Examples......................................................................................................................... 88 GetReviewableHITs................................................................................................................... 89 Description...................................................................................................................... 89 Request Parameters.......................................................................................................... 89 Response Elements........................................................................................................... 90 Examples......................................................................................................................... 91 GetReviewResultsForHIT............................................................................................................ 92 Description...................................................................................................................... 92 Request Parameters.......................................................................................................... 92 Response Elements........................................................................................................... 93 ReviewResult Data Structure .............................................................................................. 94 ReviewAction Data Structure .............................................................................................. 96 Examples......................................................................................................................... 97 GrantBonus............................................................................................................................ 100 Description.................................................................................................................... 100 Request Parameters........................................................................................................ 100 Response Elements......................................................................................................... 101 API Version 2014-08-15 v Amazon Mechanical Turk Legacy API Reference Examples....................................................................................................................... 101 GrantQualification.................................................................................................................. 103 Description.................................................................................................................... 103 Request Parameters........................................................................................................ 103 Response Elements......................................................................................................... 103 Examples....................................................................................................................... 104 NotifyWorkers........................................................................................................................ 105 Description.................................................................................................................... 105 Request Parameters........................................................................................................ 105 Response Elements......................................................................................................... 106 Examples....................................................................................................................... 106 RegisterHITType..................................................................................................................... 107 Description.................................................................................................................... 107 Request Parameters........................................................................................................ 107 Response Elements......................................................................................................... 109 Examples....................................................................................................................... 109 RejectAssignment................................................................................................................... 111 Description.................................................................................................................... 111 Request Parameters........................................................................................................ 111 Response Elements......................................................................................................... 111 Examples....................................................................................................................... 112 RejectQualificationRequest....................................................................................................... 113 Description.................................................................................................................... 113 Request Parameters........................................................................................................ 113 Response Elements......................................................................................................... 113 Examples....................................................................................................................... 113 RevokeQualification................................................................................................................ 115 Description.................................................................................................................... 115 Request Parameters........................................................................................................ 115 Response Elements......................................................................................................... 115 Examples....................................................................................................................... 116 SearchHITs............................................................................................................................. 117 Description.................................................................................................................... 117 Request Parameters........................................................................................................ 117 Response Elements......................................................................................................... 118 Examples....................................................................................................................... 118 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 API Version 2014-08-15 vi Amazon Mechanical Turk Legacy API Reference UnblockWorker....................................................................................................................... 132 Description.................................................................................................................... 132 Request Parameters........................................................................................................ 132 Response Elements......................................................................................................... 132 Examples....................................................................................................................... 133 UpdateQualificationScore........................................................................................................ 134 Description.................................................................................................................... 134 Request Parameters........................................................................................................ 134 Response Elements......................................................................................................... 134 Examples....................................................................................................................... 135 UpdateQualificationType......................................................................................................... 136 Description.................................................................................................................... 136 Request Parameters........................................................................................................ 136 Response Elements......................................................................................................... 138 Examples....................................................................................................................... 139 Related Operations......................................................................................................... 139 Data Structures.............................................................................................................................. 140 Assignment............................................................................................................................ 140 Description.................................................................................................................... 140 Elements....................................................................................................................... 140 Example........................................................................................................................ 143 HIT....................................................................................................................................... 144 Description.................................................................................................................... 144 HITs and Response Groups ............................................................................................... 144 Elements....................................................................................................................... 144 Example........................................................................................................................ 148 HITLayoutParameter............................................................................................................... 150 Description.................................................................................................................... 150 Elements....................................................................................................................... 150 HIT Review Policy ................................................................................................................... 151 Description.................................................................................................................... 151 HIT Review Policy Elements ............................................................................................. 151 Parameter Elements........................................................................................................ 151 MapEntry Elements......................................................................................................... 152 Examples....................................................................................................................... 152 Locale................................................................................................................................... 155 Description.................................................................................................................... 155 Elements....................................................................................................................... 155 Example........................................................................................................................ 155 Example........................................................................................................................ 155 Price..................................................................................................................................... 157 Description.................................................................................................................... 157 Elements....................................................................................................................... 157 Example........................................................................................................................ 157 Qualification.......................................................................................................................... 159 Description.................................................................................................................... 159 Elements....................................................................................................................... 159 Example........................................................................................................................ 160 QualificationRequest............................................................................................................... 161 Description.................................................................................................................... 161 Elements....................................................................................................................... 161 Example........................................................................................................................ 162 QualificationRequirement........................................................................................................ 163 Description.................................................................................................................... 163 Using Custom, System-Assigned, and Master Qualification Types .......................................... 163 Elements....................................................................................................................... 164 Qualification Type IDs ..................................................................................................... 165 API Version 2014-08-15 vii Amazon Mechanical Turk Legacy API Reference Master Qualifications...................................................................................................... 167 Adding Adult Content ..................................................................................................... 167 The Locale Qualification.................................................................................................. 168 Example—Using the QualificationRequirement Data Structure .............................................. 169 Example—Using the QualificationRequirement Data Structure for Comparing Multiple Values ... 170 QualificationType.................................................................................................................... 171 Description.................................................................................................................... 171 Elements....................................................................................................................... 171 Example........................................................................................................................ 173 Notification............................................................................................................................ 175 Description.................................................................................................................... 175 Elements....................................................................................................................... 175 Example........................................................................................................................ 176 WorkerBlock........................................................................................................................... 177 Description.................................................................................................................... 177 Elements....................................................................................................................... 177 Example........................................................................................................................ 177 Review Policies............................................................................................................................... 178 How Review Policies Work ....................................................................................................... 178 Assignment Review Policies ..................................................................................................... 179 ScoreMyKnownAnswers/2011-09-01................................................................................. 179 HIT Review Policies ................................................................................................................. 181 SimplePlurality/2011-09-01............................................................................................. 181 Review Policy Use Cases .......................................................................................................... 185 Photo Moderation Use Case – Single Worker with Known Answers ........................................ 185 Photo Moderation Use Case – Multiple Workers with Agreement ........................................... 186 Categorization and Tagging Use Case – Multiple Workers ..................................................... 188 Question and Answer Data .............................................................................................................. 190 Using XML Parameter Values ................................................................................................... 191 XML Data as a Parameter ................................................................................................ 191 Namespaces for XML Parameter Values ............................................................................. 191 QuestionForm........................................................................................................................ 191 Description.................................................................................................................... 192 QuestionForm Structure.................................................................................................. 192 Content Structure........................................................................................................... 194 Answer Specification....................................................................................................... 199 Example........................................................................................................................ 205 Formatted Content: XHTML ..................................................................................................... 206 Using Formatted Content ................................................................................................ 207 Supported XHTML Tags ................................................................................................... 208 How XHTML Formatted Content Is Validated ...................................................................... 210 QuestionFormAnswers............................................................................................................. 211 Description.................................................................................................................... 211 The Structure of Answers ................................................................................................ 211 Example........................................................................................................................ 212 AnswerKey............................................................................................................................. 212 Description.................................................................................................................... 212 The Structure of an Answer Key ....................................................................................... 213 Example........................................................................................................................ 214 ExternalQuestion.................................................................................................................... 216 Description.................................................................................................................... 216 The ExternalQuestion Data Structure ................................................................................ 216 Example........................................................................................................................ 217 The External Form .......................................................................................................... 217 The Answer Data ............................................................................................................ 219 Guidelines For Using External Questions ............................................................................ 219 HTMLQuestion....................................................................................................................... 221 API Version 2014-08-15 viii Amazon Mechanical Turk Legacy API Reference Description.................................................................................................................... 221 The HTMLQuestion Data Structure .................................................................................... 222 Example........................................................................................................................ 222 Preview Mode................................................................................................................ 223 The Form Action ............................................................................................................ 223 The Answer Data ............................................................................................................ 223 Guidelines For Using HTML Questions ............................................................................... 223 HITLayout.............................................................................................................................. 224 Description.................................................................................................................... 224 Obtaining a Layout ID ..................................................................................................... 224 Using a HITLayout .......................................................................................................... 224 Guidelines for Using HITLayouts ....................................................................................... 225 The Notification API........................................................................................................................ 226 Elements of a Notification Message.......................................................................................... 226 The Notification API Version ............................................................................................ 226 Events........................................................................................................................... 227 Notification Handling Using Amazon SQS .................................................................................. 227 Creating an SQS Queue ................................................................................................... 227 Configuring an SQS Queue .............................................................................................. 227 Amazon SQS Policy Document Example ............................................................................ 228 Configuring Permissions Using the AWS Console ................................................................ 228 Configuring Permissions Using the Amazon SQS API ........................................................... 228 Testing Your Queue ........................................................................................................ 228 Guaranteed Delivery....................................................................................................... 229 SQS Message Ordering .................................................................................................... 229 Multiple SQS Queues ...................................................................................................... 229 SQS Message Payload ..................................................................................................... 229 Double Delivery.............................................................................................................. 230 API Version 2014-08-15 ix Amazon Mechanical Turk Legacy API Reference   API Version 2014-08-15 x