# Data Structures **Topics** + [Assignment](ApiReference_AssignmentDataStructureArticle.md) + [HIT](ApiReference_HITDataStructureArticle.md) + [HITLayoutParameter](ApiReference_HITLayoutParameterArticle.md) + [Qualification](ApiReference_QualificationDataStructureArticle.md) + [QualificationRequest](ApiReference_QualificationRequestDataStructureArticle.md) + [QualificationRequirement](ApiReference_QualificationRequirementDataStructureArticle.md) + [QualificationType](ApiReference_QualificationTypeDataStructureArticle.md) + [HIT Review Policy](ApiReference_HITReviewPolicyDataStructureArticle.md) + [Locale](ApiReference_LocaleDataStructureArticle.md) The Amazon Mechanical Turk API uses several common data structures in its operation request and response structures. For easy reference, these structures are documented in separate articles. For more information, refer to their corresponding operations. # Assignment ## Description The Assignment data structure represents a single assignment of a HIT to a Worker. The assignment tracks the Worker's efforts to complete the HIT, and contains the results for later retrieval. The Assignment data structure is used as a response element for the following operations: + `GetAssignment` + `ListAssignmentsForHIT` ## Elements The Assignment structure can contain the following elements. | Name | Description | Required | | --- | --- | --- | | `AssignmentId` | A unique identifier for the assignment. Can be up to 255 bytes in length. Type: String Default: None | No | | `WorkerId` | The ID of the Worker who accepted the HIT. Can be up to 255 bytes in length. Type: String Default: None | No | | `HITId` | The ID of the HIT. Can be up to 255 bytes in length. Type: String Default: None | No | | `AssignmentStatus` | The status of the assignment Type: String Valid Values: Submitted \$1 Approved \$1 Rejected Default: None | No | | `AutoApprovalTime` | If results have been submitted, `AutoApprovalTime` is the date and time the results of the assignment results are considered **Approved** automatically if they have not already been explicitly approved or rejected by the Requester. This value is derived from the auto-approval delay specified by the Requester in the HIT. This value is omitted from the assignment if the Worker has not yet submitted results. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None | No | | `AcceptTime` | The date and time the Worker accepted the assignment. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None | No | | `SubmitTime` | If the Worker has submitted results, `SubmitTime` is the date and time the assignment was submitted. This value is omitted from the assignment if the Worker has not yet submitted results. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None | No | | `ApprovalTime` | If the Worker has submitted results and the Requester has approved the results, `ApprovalTime` is the date and time the Requester approved the results. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None. **Note**: This value is omitted from the assignment if the Requester has not yet approved the results. | No | | `RejectionTime` | If the Worker has submitted results and the Requester has rejected the results, `RejectionTime` is the date and time the Requester rejected the results. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None. **Note**: This value is omitted from the assignment if the Requester has not yet rejected the results. | No | | `Deadline` | The date and time of the deadline for the assignment. This value is derived from the deadline specification for the HIT and the date and time the Worker accepted the HIT. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None | No | | `Answer` | The Worker's answers submitted for the HIT contained in a `QuestionFormAnswers` document, if the Worker provides an answer. If the Worker does not provide any answers, `Answer` may contain a `QuestionFormAnswers` document, or `Answer` may be empty. Type: a [QuestionFormAnswers](ApiReference_QuestionFormAnswersDataStructureArticle.md) data structure Default: None | No | | `RequesterFeedback` | The feedback string included with the call to the ` ApproveAssignment` operation or the` RejectAssignment` operation, if the Requester approved or rejected the assignment and specified feedback. Type: String Default: None | No | ## Example The following example shows an Assignment data structure returned by the `ListAssignmentsForHIT` operation. The `ListAssignmentsForHIT` operation returns zero or more `Assignment` elements for a **Reviewable** HIT. ``` Assignment:{ AssignmentId: "123RVWYBAZW00EXAMPLE456RVWYBAZW00EXAMPLE", WorkerId:"AZ3456EXAMPLE", HITId:"123RVWYBAZW00EXAMPLE", AssignmentStatus:"Submitted", Deadline: "2005-12-01T23:59:59Z", AcceptTime: "2005-12-01T12:00:00Z", SubmitTime: "2005-12-07T23:59:59Z", Answer:{ QuestionFormAnswers:[XML-encoded Answer data] } } ``` # HIT ## Description The HIT data structure represents a single HIT, including all the information necessary for a Worker to accept and complete the HIT. The HIT data structure is used as a response element for the following operations: + `CreateHIT` + `GetHIT` + `ListReviewableHITs` + `ListHITs` ## Elements The HIT structure can contain the elements described in the following table. | Name | Description | Required | | --- | --- | --- | | `HITId` | A unique identifier for the HIT. The `CreateHIT` operation gives a HIT the HIT ID and the HIT retains that ID forever. Type: String Default: None | No | | `HITTypeId` | The ID of the HIT type of this HIT Type: String Default: None | No | | `HITGroupId` | The ID of the HIT Group of this HIT Type: String Default: None | No | | `HITLayoutId` | The ID of the HIT Layout of this HIT Type: String Default: None | No | | `CreationTime` | The date and time the HIT was created Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as `2012-01-31T23:59:59Z`. Default: None | No | | `Title` | The title of the HIT Type: String Default: None | No | | `Description` | A general description of the HIT Type: String Default: None | No | | `Keywords` | One or more words or phrases that describe the HIT, separated by commas. Search terms similar to the keywords of a HIT are more likely to have the HIT in the search results. Type: String Default: None | No | | `HITStatus` | The status of the HIT and its assignments Type: String Valid Values: Assignable \$1 Unassignable \$1 Reviewable \$1 Reviewing \$1 Disposed Default: None | No | | `Reward` | The amount of money the Requester will pay a Worker for successfully completing the HIT. Type: a `Price` data structure Default: None | No | | `LifetimeInSeconds` | The amount of time, in seconds, after which the HIT is no longer available for users to accept. The HIT becomes unavailable even if the requested number of assignments, specified by `MaxAssignments`, has not been completed. Type: positive integer Default: None | No | | `AssignmentDurationInSeconds` | The length of time, in seconds, that a Worker has to complete the HIT after accepting it. Type: positive integer Default: None | No | | `MaxAssignments` | The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Type: positive integer Default: 1 | No | | `AutoApprovalDelayInSeconds` | The amount of time, in seconds, after the Worker submits an assignment for the HIT that the results are automatically approved by Amazon Mechanical Turk. This is the amount of time the Requester has to reject an assignment submitted by a Worker before the assignment is auto-approved and the Worker is paid. Type: positive integer Default: None | No | | `Expiration` | The date and time the HIT expires Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as `2012-01-31T23:59:59Z`. Default: None | No | | `QualificationRequirement` | The QualificationRequirement data structure describes a Qualification that a Worker must have before the Worker is allowed to accept a HIT. A requirement may optionally state that a Worker must have the Qualification in order to preview the HIT, or see the HIT in search results. A HIT can have between zero and ten Qualification requirements. Type: a `QualificationRequirement` data structure. Default: None | No | | `Question` | The data the Worker completing the HIT uses produce the results. Type: either a [QuestionForm](ApiReference_QuestionFormDataStructureArticle.md) or an [ExternalQuestion ](ApiReference_ExternalQuestionArticle.md) data structure. Default: None | No | | `RequesterAnnotation` | An arbitrary data field the Requester who created the HIT can use. This field is visible only to the creator of the HIT. Type: String Default: None | No | | `HITReviewStatus` | Indicates the review status of the HIT. Type: String Valid Values: NotReviewed \$1 MarkedForReview \$1 ReviewedAppropriate \$1 ReviewedInappropriate Default: None | No | | `NumberofAssignmentsPending` | The number of assignments for this HIT that are being previewed or have been accepted by Workers, but have not yet been submitted, returned, or abandoned. Type: non-negative integer Default: None Conditions: This element is returned only if the `HITAssignmentSummary` response group is specified. | Conditional | | `NumberofAssignmentsAvailable` | The number of assignments for this HIT that are available for Workers to accept Type: non-negative integer Default: None Conditions: This element is returned only if the `HITAssignmentSummary` response group is specified. | Conditional | | `NumberofAssignmentsCompleted` | The number of assignments for this HIT that have been approved or rejected. Type: non-negative integer Default: None Conditions: This element is returned only if the `HITAssignmentSummary` response group is specified. | Conditional | ## Example The following example shows a HIT data structure returned by the `CreateHIT` operation. The `CreateHIT` operation returns an element named `HIT` that represents the HIT that was created by the call. ``` HIT:{ HITId:"123RVWYBAZW00EXAMPLE", HITTypeId:"T100CN9P324W00EXAMPLE", HITTypeId:"2005-06-30T23:59:59", HITStatus:"Assignable", MaxAssignments:"5", AutoApprovalDelayInSeconds:"86400", LifetimeInSeconds:"86400", AssignmentDurationInSeconds:"300", Reward:{ Amount:"25" CurrencyCode:"USD" FormattedPrice:"$0.25" }, Title:"Location and Photograph Identification", Description:"Select the image that best represents...", Keywords:"location, photograph, image, identification, opinion", Question:{ QuestionForm:[XML-encoded Question data] }, QualificationRequirement:{ QualificationTypeId:"789RVWYBAZW00EXAMPLE", Comparator:"GreaterThan", Value:"18" }, HITReviewStatus:"NotReviewed" } ``` # HITLayoutParameter ## Description The `HITLayoutParameter` data structure defines parameter values used with a HITLayout. A HITLayout is a reusable Amazon Mechanical Turk project template used to provide Human Intelligence Task (HIT) question data for `CreateHIT`. For more information, see [HITLayout](ApiReference_HITLayoutArticle.md). The `HITLayoutParameter` data structure is used in the results of the following operation: + [CreateHIT](ApiReference_CreateHITOperation.md) **Tip** The [HITLayout](ApiReference_HITLayoutArticle.md) is used to create an HTMLQuestion document. HITLayoutParameter values with reserved characters or invalid HTML markup may result in an invalid HTMLQuestion document. ## Elements The `HITLayout` data structure has a root element of `HITLayoutParameter`. The `HITLayoutParameter` element contains the following elements: | Name | Description | Required | | --- | --- | --- | | `Name` | The name of the parameter in the HITLayout. Type: String Default: None Constraints: Parameter names supplied in a HITLayoutParameter structure must be used in the referenced HITLayout. | Yes | | `Value` | The value substituted for the parameter referenced in the HITLayout. Type: String Default: None | Yes | # Qualification ## Description The Qualification data structure represents a Qualification assigned to a user, including the Qualification type and the value (score). The Qualification data structure is used as a response element for the following operations: + `GetQualificationScore` + `ListQualificationRequests` ## Elements The Qualification structure can contain the elements described in the following table. When the structure is used in a request, elements described as **Required** must be included for the request to succeed. | Name | Description | Required | | --- | --- | --- | | `QualificationTypeId` | The ID of the Qualification type for the Qualification. Can be up to 255 bytes in length. Type: String Default: None | Yes | | `WorkerId` | The ID of the Worker who possesses the Qualification. Can be up to 255 bytes in length. Type: String Default: None | Yes | | `GrantTime` | The date and time the Qualification was associated with the Worker. If the Worker's Qualification was revoked, and then re-associated based on a new Qualification request, `GrantTime` is the date and time of the last call to the AssociateQualificationWithWorker operation. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z** Default: None | Yes | | `IntegerValue` | The value (score) of the Qualification, if the Qualification has an integer value. Type: Integer Default: None | No | | `LocaleValue` | The value of the Qualification if the Qualification describes a geographical region or location. Type: a [Locale](ApiReference_LocaleDataStructureArticle.md) data structure. Default: None | No | | `Status` | The status of the Qualification Type: String Valid Values: Granted \$1 Revoked Default: None | Yes | ## Example The following example illustrates a Qualification with an integer value. ``` Qualification:{ QualificationTypeId:"789RVWYBAZW00EXAMPLE", WorkerId:"AZ3456EXAMPLE", GrantTime:"2005-01-31T23:59:59Z", IntegerValue:95 } ``` # QualificationRequest ## Description The QualificationRequest data structure represents a request a Worker has made for a Qualification. The QualificationRequest data structure is used as a response element for the following operations: + `ListQualificationRequests` ## Elements The QualificationRequest structure can contain the elements described in the following table: | Name | Description | Required | | --- | --- | --- | | `QualificationRequestId` | The ID of the Qualification request, a unique identifier generated when the request was submitted. Can be up to 255 bytes in length. Type: String Default: None | No | | `QualificationTypeId` | The ID of the Qualification type the Worker is requesting, as returned by the `CreateQualificationType` operation. Can be up to 255 bytes in length. Type: String Default: None | No | | `SubjectId` | The ID of the Worker requesting the Qualification. This ID corresponds to the `WorkerId` returned with assignment results when the Worker performs a HIT. Can be up to 255 bytes in length. Type: String Default: None | No | | `Test` | The contents of the Qualification test that was presented to the Worker, if the type has a test and the Worker has submitted answers. This value is identical to the QuestionForm associated with the Qualification type at the time the Worker requests the Qualification. Type: a [QuestionForm](ApiReference_QuestionFormDataStructureArticle.md) data structure Default: None | No | | `Answer` | The Worker's answers for the Qualification type's test contained in a `QuestionFormAnswers` document, if the type has a test and the Worker has submitted answers. If the Worker does not provide any answers, `Answer` may be empty. Type: a [QuestionFormAnswers](ApiReference_QuestionFormAnswersDataStructureArticle.md) data structure Default: None | No | | `SubmitTime` | The date and time the Qualification request had a status of **Submitted**. This is either the time the Worker submitted answers for a Qualification test, or the time the Worker requested the Qualification if the Qualification type does not have a test. Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z** Default: None | No | ## Example The following example shows a QualificationRequest data structure returned by the `ListQualificationRequests` operation. This operation returns the requests for Qualifications of a Qualification type to the owner of the type. ``` QualificationRequest:{ QualificationRequestId:"789RVWYBAZW00EXAMPLE951RVWYBAZW00EXAMPLE", QualificationTypeId:"789RVWYBAZW00EXAMPLE", SubjectId:"AZ3456EXAMPLE", Test:{ QuestionForm:[XML-encoded Question data] }, Answer:{ QuestionFormAnswers:[XML-encoded Answer data] }, SubmitTime:"2005-12-01T23:59:59Z" } ``` # QualificationRequirement **Topics** + [Description](#ApiReference_QualificationRequirementDataStructureArticle-description) + [Using Custom, System-Assigned, and Master Qualification Types](#CustomQualificationsandSystemQualifications) + [Elements](#ApiReference_QualificationRequirementDataStructureArticle-elements) + [Qualification Type IDs](#ApiReference_QualificationType-IDs) + [Master Qualification](#MasterQualifications) + [Adding Adult Content](#AdultContent) + [The Locale Qualification](#ApiReference_QualificationRequirementDataStructureArticle-the-locale-qualification) + [Example—Using the QualificationRequirement Data Structure](#ApiReference_QualificationRequirementDataStructureArticle-sample1-createhit) + [Example—Using the QualificationRequirement Data Structure for Comparing Multiple Values](#ApiReference_QualificationRequirementDataStructureArticle-sample-createhit) + [Example—Using the QualificationRequirement Data Structure to Hide HIT from Unqualified Workers](#ApiReference_QualificationRequirementDataStructureArticle-samplehidden-createhit) ## Description The QualificationRequirement data structure describes a Qualification that a Worker must have before the Worker is allowed to accept a HIT. A requirement may optionally state that a Worker must have the Qualification in order to preview the HIT, or see the HIT in search results. The QualificationRequirement data structure is used as a parameter for the following operations: + `CreateHIT` + `CreateHITType` The QualificationRequirement data structure is used in the [HIT data structure](ApiReference_HITDataStructureArticle.md). ## Using Custom, System-Assigned, and Master Qualification Types A Qualification requirement can be based on a Qualification you assign to Workers. You can create a custom Qualification type using the `CreateQualificationType` operation. Then you can grant requests for the Qualification automatically using a Qualification test and answer key submitted with the Qualification type, or you can grant the request manually with the `AcceptQualificationRequest` operation. The `CreateQualificationType` returns a `QualificationTypeId`, which you can use with the `QualificationRequirement` data structure to identify the type of Qualification the Worker is required to have to accept a HIT. Either the Qualification test or your call to `AcceptQualificationRequest` determines a Qualification value, which is compared to the requirement in the HIT to determine the Worker's eligibility. Amazon Mechanical Turk supplies several Qualification types for use by all Requesters. Mechanical Turk system-assigned Qualification types work the same way as Qualifications that you create, except that data from the Mechanical Turk marketplace determines the Worker’s values. Every Worker has a value for each system Qualification, and these values are updated as the Worker uses the system. Additionally, Amazon Mechanical Turk also provides Master Qualification types that give you access to an elite group of Workers who have demonstrated superior performance while completing thousands of HITs across the Mechanical Turk marketplace. You can use the Master and system-assigned Qualification types by using the corresponding Qualification type ID in the `QualificationTypeId` element of the `QualificationRequirement` data structure. For a list of the Master and system-assigned IDs, see [Qualification Type IDs](#ApiReference_QualificationType-IDs). For more information about using a Master Qualification type, see [Master Qualification](#MasterQualifications). ## Elements The QualificationRequirement data structure can contain the following elements. | Name | Description | Value | | --- | --- | --- | | QualificationTypeId | The ID of the Qualification type for the requirement. Can be up to 255 bytes in length. | A valid QualificationType ID from a custom Qualification type you created or an ID from the list of Master and system-assigned [Qualification Type IDs](#ApiReference_QualificationType-IDs). | | Comparator | The kind of comparison to make against a Qualification's value. You can compare a Qualification's value: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QualificationRequirementDataStructureArticle.html) A Qualification requirement can also test if a Qualification `Exists` or `DoesNotExist` in the user's profile, regardless of its value. | `LessThan` \$1 `LessThanOrEqualTo` \$1 `GreaterThan` \$1 `GreaterThanOrEqualTo` \$1 `EqualTo` \$1 `NotEqualTo` \$1 `Exists` \$1 `DoesNotExist` \$1 `In` \$1 `NotIn` | | IntegerValues | Array of integer values to compare against the Qualification's value. `IntegerValue` must not be present if `Comparator` is `Exists` or `DoesNotExist`. `IntegerValue` can only be used if the Qualification type has an integer value; it cannot be used with the `Worker_Locale` QualificationType ID, see [Qualification Type IDs](#ApiReference_QualificationType-IDs). When performing a set comparison by using the `In` or the `NotIn` comparator, you can use up to 15 elements in this list. For an example of a set comparison, see [Example—Using the QualificationRequirement Data Structure for Comparing Multiple Values](#ApiReference_QualificationRequirementDataStructureArticle-sample-createhit). | An integer. | | LocaleValue | The locale value to compare against the Qualification's value. The local value must be a valid [ ISO 3166 country code](http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm) or supports [ISO 3166-2 subdivisions](http://en.wikipedia.org/wiki/ISO_3166-2:US). `LocaleValue` can only be used with a `Worker_Locale` QualificationType ID, see [Qualification Type IDs](#ApiReference_QualificationType-IDs). `LocaleValue` can only be used with the `EqualTo`, `NotEqualTo`, `In`, and `NotIn` comparators. You must only use a single `LocaleValue` element when using the `EqualTo` or `NotEqualTo` comparators. When performing a set comparison by using the `In` or the `NotIn` comparator, you can use up to 30 `LocaleValue` elements in a QualificationRequirement data structure. For an example of a set comparison, see [Example—Using the QualificationRequirement Data Structure for Comparing Multiple Values](#ApiReference_QualificationRequirementDataStructureArticle-sample-createhit). | A [Locale](ApiReference_LocaleDataStructureArticle.md) data structure. | | ActionsGuarded | Setting this attribute prevents Workers whose Qualifications do not meet this requirement from taking the specified action. Valid arguments are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QualificationRequirementDataStructureArticle.html) It's possible for you to create a HIT with multiple QualificationRequirements (which can have different values for the ActionGuarded attribute). In this case, the Worker is only permitted to perform an action when they have met all QualificationRequirements guarding the action. The actions in the order of least restrictive to most restrictive is Discover, Preview and Accept. For example, if a Worker meets all QualificationRequirements that are set to DiscoverPreviewAndAccept, but do not meet all requirements that are set with PreviewAndAccept, then the Worker will be able to Discover, i.e. see the HIT in their search result, but will not be able to Preview or Accept the HIT. The default is `Accept`. | Accept \$1 PreviewAndAccept \$1 DiscoverPreviewAndAccept | | RequiredToPreview | DEPRECATED as of 03/29/2018 - Use the `ActionsGuarded` field instead. If **true**, the question data for the HIT will not be shown when a Worker whose Qualifications do not meet this requirement tries to preview the HIT. That is, a Worker's Qualifications must meet all of the requirements for which `RequiredToPreview` is **true** in order to preview the HIT. If a Worker meets all of the requirements where `RequiredToPreview` is **true** (or if there are no such requirements), but does not meet all of the requirements for the HIT, the Worker will be allowed to preview the HIT's question data, but will not be allowed to accept and complete the HIT. The default is **false**. | A Boolean value, **true** or **false** | ## Qualification Type IDs The following table lists the Master and system-assigned Qualification Type IDs that can be used in the `QualificationTypeId` element. | Name | QualificationTypeId | Description | | --- | --- | --- | | Masters | Sandbox: 2ARFPLSP75KLA8M8DH1HTEQVJT3SY6 Production: 2F1QJWKUDD8XADTFD2Q0G6UTO95ALH | Masters are Workers who have demonstrated superior performance while completing thousands of HITs across the Mechanical Turk marketplace. Masters maintain this high level of performance to keep this distinction. Set the `comparator` parameter to "Exists" to require that Workers have this Qualification. Note that for this Qualification type ID, the `QualificationTypeId` value for the Mechanical Turk Sandbox environment is different than the value for the production environment. | | Worker\$1​NumberHITsApproved | 00000000000000000040 | Specifies the total number of HITs submitted by a Worker that have been approved. The value is an integer greater than or equal to 0. | | Worker\$1Locale | 00000000000000000071 | The location of the Worker, as specified in the Worker's mailing address. For more information about the locale Qualification, see the [The Locale Qualification](#ApiReference_QualificationRequirementDataStructureArticle-the-locale-qualification) section. | | Worker\$1Adult | 00000000000000000060 | Requires workers to acknowledge that they are over 18 and that they agree to work on potentially offensive content. The value type is boolean, 1 (required), 0 (not required, the default). | | Worker\$1​PercentAssignmentsApproved | 000000000000000000L0 | The percentage of assignments the Worker has submitted that were subsequently approved by the Requester, over all assignments the Worker has submitted. The value is an integer between 0 and 100. Note that a Worker's approval rate is statistically meaningless for small numbers of assignments, since a single rejection can reduce the approval rate by many percentage points. So to ensure that a new Worker's approval rate is unaffected by these statistically meaningless changes, if a Worker has submitted less than 100 assignments, the Worker's approval rate in the system is 100%. To prevent Workers who have less than 100 approved assignments from working on your HIT, set the Worker\$1​NumberHITsApproved qualification type ID to a value greater than 100. | ## Master Qualification You can require that Workers must have a Master Qualification to complete your HITs. To create a Qualification requirement for Masters, specify: + A `QualificationTypeId` of 2F1QJWKUDD8XADTFD2Q0G6UTO95ALH + A `Comparator` of `Exists` **Note** The Master Qualification Type ID values used for the `QualificationTypeId` parameter in the preceding procedures are for the production environment. The ID values to use in the Mechanical Turk Sandbox environment are listed in the [Qualification Type IDs](#ApiReference_QualificationType-IDs) table. ## Adding Adult Content Adult content can be offensive to some people. For that reason, if your HIT is adult-oriented, we ask you to use the following procedure. **Adding Adult HITs** 1. In the HIT title, include the words "adult content." 1. Specify the worker's qualifications in one of the following ways: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QualificationRequirementDataStructureArticle.html) 1. Define the HIT to be private or previewed. This setting prevents anyone who does not qualify from seeing the HIT. To make the HIT private, use one of the following methods: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_QualificationRequirementDataStructureArticle.html) ## The Locale Qualification You can create a Qualification requirement based on the Worker's location. The Worker's location is specified by the Worker to Amazon Mechanical Turk when the Worker creates his account. To create a Qualification requirement based on the Worker's location, specify: + A `QualificationTypeId` of 00000000000000000071 + A `Comparator` of `EqualTo` or `NotEqualTo` + A `LocaleValue` that corresponds to the desired locale To create a Qualification requirement based on the Worker being in or not in one of several locations, specify: + A `QualificationTypeId` of 00000000000000000071 + A `Comparator` of `In` or `NotIn` + Multiple `LocaleValue` values that correspond to the desired locales. For more information on the format of a `LocaleValue` element, see [Locale data structure](ApiReference_LocaleDataStructureArticle.md). ### Example The following example shows a QualificationRequirement specifying Workers located in the state of Pennsylvania. Workers located in the state of New York (US-NY) or in the country of India (IN) do not qualify for the HITs with this QualificationRequirement. ``` QualificationRequirement:{ QualificationTypeId:"00000000000000000071", Comparator:"EqualTo", LocaleValues:[{ Country:"US", Subdivision:"PA" }] } ``` The following example shows a QualificationRequirement specifying Workers not located in the state of California. Workers located in the state of New York or in the country of India (IN) will be qualified to do HITs with this QualificationRequirement. ``` QualificationRequirement:{ QualificationTypeId:"00000000000000000071", Comparator:"NotEqualTo", LocaleValues:[{ Country:"US", Subdivision:"CA" }] } ``` ## Example—Using the QualificationRequirement Data Structure The following example of a QualificationRequirement data structure could be passed in to a call to `CreateHIT`. `CreateHIT` accepts parameters that describe the HIT being created, including one or more Qualification requirements: ``` QualificationRequirement:{ QualificationTypeId:"789RVWYBAZW00EXAMPLE", Comparator:"GreaterThan", IntegerValues:[18] } ``` ## Example—Using the QualificationRequirement Data Structure for Comparing Multiple Values The following example of a QualificationRequirement data structure could be passed in to a call to `CreateHIT`. `CreateHIT` accepts parameters that describe the HIT being created, including one or more Qualification requirements. ### Example Request The following example shows a QualificationRequirement data structure used in a SOAP request that uses multiple `IntegerValue` values when performing a set comparison by using the `In` comparator. ``` QualificationRequirement:{ QualificationTypeId:"789RVWYBAZW00EXAMPLE", Comparator:"In", IntegerValues:[10, 20, 30] } ``` ## Example—Using the QualificationRequirement Data Structure to Hide HIT from Unqualified Workers The following example of a QualificationRequirement data structure could be passed in to a call to `CreateHIT`. This will hide the HIT from unqualified Workers (these Workers will not be able to accept, preview, or see the HIT in search results). `CreateHIT` accepts parameters that describe the HIT being created, including one or more Qualification requirements: ``` QualificationRequirement:{ QualificationTypeId:"789RVWYBAZW00EXAMPLE", Comparator:"Exists", ActionsGuarded:"DiscoverPreviewAndAccept" } ``` # QualificationType ## Description The QualificationType data structure represents a Qualification type, a description of a property of a Worker that must match the requirements of a HIT for the Worker to be able to accept the HIT. The type also describes how a Worker can obtain a Qualification of that type, such as through a Qualification test. The QualificationType data structure is used as a response element for the following operations: + `CreateQualificationType` + `GetQualificationType` + `ListQualificationTypes` + `UpdateQualificationType` ## Elements The QualificationType structure can contain the elements described in the following table: | Name | Description | Required | | --- | --- | --- | | `QualificationTypeId` | A unique identifier for the Qualification type. A Qualification type is given a Qualification type ID when you call the `CreateQualificationType` operation operation, and it retains that ID forever. Can be up to 255 bytes in length. Type: String Default: None | No | | `CreationTime` | The date and time the Qualification type was created Type: a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) structure in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as **2005-01-31T23:59:59Z**. Default: None | No | | `Name` | The name of the Qualification type. The type name is used to identify the type, and to find the type using a Qualification type search. Type: String Default: None | No | | `Description` | A long description for the Qualification type. Type: String Default: None | No | | `Keywords` | One or more words or phrases that describe theQualification type, separated by commas. The Keywords make the type easier to find using a search. Type: String Default: None | No | | `QualificationTypeStatus` | The status of the Qualification type. A Qualification type's status determines if users can apply to receive a Qualification of this type, and if HITs can be created with requirements based on this type. Type: String Valid Values: Active \$1 Inactive Default: None | No | | `RetryDelayInSeconds` | The amount of time, in seconds, Workers must wait after taking the Qualification test before they can take it again. Workers can take a Qualification test multiple times if they were not granted the Qualification from a previous attempt, or if the test offers a gradient score and they want a better score. Type: positive integer Default: None. If not specified, retries are disabled and Workers can request a Qualification only once. | No | | `Test` | The questions for a Qualification test associated with this Qualification type that a user can take to obtain a Qualification of this type. Type: a [QuestionForm](ApiReference_QuestionFormDataStructureArticle.md) data structure. A Qualification test cannot use an [ExternalQuestionQuestionForm](ApiReference_ExternalQuestionArticle.md) like a HIT can. Default: None Constraints: must be specified if `AnswerKey` is present. A Qualification type cannot have both a specified `Test` parameter and an `AutoGranted` value of **true**. | No | | `TestDurationInSeconds` | The amount of time, in seconds, given to a Worker to complete the Qualification test, beginning from the time the Worker requests the Qualification. Type: positive integer Default: None | No | | `AnswerKey` | The answers to the Qualification test specified in the `Test` parameter. Type: an [AnswerKey](ApiReference_AnswerKeyDataStructureArticle.md) data structure. Default: None. If not provided with a test, the Qualification author must process the Qualification request manually. | No | | `AutoGranted` | Specifies that requests for the Qualification type are granted immediately, without prompting the Worker with a Qualification test. Type: Boolean Valid Values: true \$1 false Default: None Constraints: A Qualification type cannot have both a specified `Test` parameter and an `AutoGranted` value of **true**. | No | | `AutoGrantedValue` | The Qualification value to use for automatically granted Qualifications, if `AutoGranted` is `true`. Type: Integer Default: 1 | No | | `IsRequestable` | Specifies whether the Qualification type is one that a user can request through the Amazon Mechanical Turk web site, such as by taking a Qualification test. This value is **false** for Qualifications assigned automatically by the system. Type: Boolean Valid Values: true \$1 false Default: None | No | ## Example The following example shows a QualificationType data structure returned by a call to the `ListQualificationTypes` operation. The `GetQualificationType` operation returns a `QualificationType` element. ``` QualificationType:{ QualificationTypeId:"789RVWYBAZW00EXAMPLE", CreationTime:"2005-01-31T23:59:59Z", Name:"EnglishWritingAbility", Description:"The ability to write and edit text...", Keywords:"English, text, write, edit, language", QualificationTypeStatus:"Active", RetryDelayInSeconds:86400, IsRequestable:true } ``` # HIT Review Policy **Topics** + [Description](#ApiReference_HITReviewPolicyDataStructureArticle-description) + [HIT Review Policy Elements](#ApiReference_HITReviewPolicyDataStructureArticle-hit-review-policy-elements) + [Parameter Elements](#ApiReference_HITReviewPolicyDataStructureArticle-parameter-elements) + [MapEntry Elements](#ApiReference_HITReviewPolicyDataStructureArticle-mapentry-elements) + [Examples](#ApiReference_HITReviewPolicyDataStructureArticle-examples) ## Description HIT Review Policy data structures represent HIT review policies, which you specify when you create a Human Intelligence Task (HIT). For more information about Review Policies, see [Review Policies](ApiReference_ReviewPoliciesArticle.md). The following two types of HIT Review Policy data structures are used when calling the [CreateHIT](ApiReference_CreateHITOperation.md) operation. + `AssignmentReviewPolicy` data structures set the review results and actions at the Assignment level. For more information, see [Assignment Review Policies](ApiReference_AssignmentReviewPolicies.md). + `HITReviewPolicy` data structures set the review results and actions at the HIT-level. For more information, see [HIT Review Policies](ApiReference_HITReviewPolicies.md). The HIT Review Policy data structure is used in the following operation: + `CreateHIT` ## HIT Review Policy Elements The HIT Review Policy data structures can contain the following elements. | Name | Description | Required | | --- | --- | --- | | `PolicyName` | Name of a Review Policy. For policy names and descriptions, see [Assignment Review Policies](ApiReference_AssignmentReviewPolicies.md) and [HIT Review Policies](ApiReference_HITReviewPolicies.md). Type: String Constraints: SimplePlurality/2011-09-01 or ScoreMyKnownAnswers/2011-09-01 | Yes | | `Parameter` | Name of the parameter from the Review policy. Type: Parameter data structure, for a description see the next section Parameter Elements. | | ## Parameter Elements The Parameter data structure contains the elements described in the following table. | Name | Description | Required | | --- | --- | --- | | `Key ` | Name of the parameter from the list of Review Polices. For a list of valid parameter names, see [Assignment Review Policies](ApiReference_AssignmentReviewPolicies.md) and [HIT Review Policies](ApiReference_HITReviewPolicies.md). Type: String Constraints: none Default: none | | | `Value` | Value of the parameter. Type: Varies. | | | `MapEntry ` | This data structure is the data type for the `AnswerKey` parameter of the ScoreMyKnownAnswers/2011-09-01 Review Policy, see [Assignment Review Policies](ApiReference_AssignmentReviewPolicies.md). Type: MapEntry data structure, for a description, see the next section MapEntry Elements. | | ## MapEntry Elements The MapEntry element contains the elements described in the following table. | Name | Description | Required | | --- | --- | --- | | `Key` | The QuestionID from the HIT that is used to identify which question requires Mechanical Turk to score as part of the ScoreMyKnownAnswers/2011-09-01 Review Policy. Can be up to 255 bytes in length. Type: String none | | | `Value` | The answer to the question specified in the MapEntry `Key` element. Note: You can provide multiple `Value` elements, but the Worker must match all values in order for the answer to be scored correctly. Type: String | | ## Examples The following example request shows the structure of a `CreateHIT` request using HIT Review Policy data structures. The example request is followed by an example response. ### Sample Request The following is an example `CreateHIT` request. ``` { HITTypeId:"T100CN9P324W00EXAMPLE", Question:URL-encoded question data, LifetimeInSeconds:604800, AssignmentReviewPolicy:{ PolicyName:"ScoreMyKnownAnswers/2011-09-01", Parameters:[ { Key:"AnswerKey", MapEntries:[ {Key: "QuestionId1", Values:["B"]}, {Key: "QuestionId2", Value:["A"]}, {Key: "QuestionId3", Value:["C"]}, {Key: "QuestionId4", Value:["A"]} ] }, { Key: "ApproveIfKnownAnswerScoreIsAtLeast", Values:["79"] } { Key: "ExtendIfKnownAnswerScoreIsLessThan", Values:["79"] } { Key: "ExtendMaximumAssignments", Values:["3"] } ] }, HITReviewPolicy:{ PolicyName:"SimplePlurality/2011-09-01", Parameters:[ { Key:"QuestionIDs", // Add upto 15 questions Values:["questionid1", "questionid2", "questionid3", "questionid4", "questionid5"] }, { Key:"QuestionAgreementThreshold", Values:["100"] } ] } } ``` # Locale ## Description The Locale data structure represents a geographical region or location. The Locale data structure is used as part of the [ QualificationRequirement](ApiReference_QualificationRequirementDataStructureArticle.md) data structure when you specify a requirement based on the locale Qualification, and as part of the [Qualification](ApiReference_QualificationDataStructureArticle.md) data structure that describes the value of a locale Qualification. When used in a QualificationRequirement, the Locale data structure only needs to contain as much of the locale as the Worker needs to match to meet the requirement. For example, a requirement that the Worker be living anywhere in the United States would have only the `Country` field. **Note** Currently, a Locale data structure only supports the `Country` field and `Subdivision` field. Please note that subdivisions or states are only available for the United States of America. ## Elements The Locale structure can contain the elements described in the following table. When the structure is used in a request, elements described as **Required** must be included for the request to succeed. | Name | Description | Required | | --- | --- | --- | | `Country` | The country of the locale. Type: A valid [ ISO 3166 country code](https://www.iso.org/iso-3166-country-codes.html). For example, the code **US** refers to the United States of America. Default: none | Yes | | `Subdivision` | The state or subdivision of the locale. Type: Type: A valid ISO 3166-2 subdivision code. For example, the code CA refers to the state of California Default: none | No | ## Example The following code sample indicates a locale in the United States. ``` LocaleValue:{ Country:"US" } ``` ## Example The following code sample indicates a locale in the state of California in the United States of America. ``` LocaleValue:{ Country:"US", Subdivision:"CA" } ```