The CreateQualificationType operation creates a new Qualification type.
The user who creates a Qualification type is the "author" for the type. Qualifications of the type are statements by the author about the recipient of the Qualification.
A Qualification type may include a Qualification test, a set of questions a Worker must answer to request the Qualification. The type may also include an answer key for the test. Qualification requests for types with answer keys are granted automatically by Mechanical Turk, using a value calculated from the answer key and the Worker's test answers. If the Qualification type does not have a test, or does not have an answer key, the author is responsible for polling for and granting Qualification requests. (See GetQualificationRequests.)
Once a Qualification type has been created, it cannot be deleted. The author can disable the Qualification type by calling the UpdateQualificationType operation, to prevent Workers from taking the Qualification test, and to prevent Requesters from creating HITs that use the type in a requirement.
An author may create an unlimited number of Qualification types.
Using CreateQualificationType (REST)
The following example of a call to the CreateQualificationType operation creates a Qualification type.
http://mechanicalturk.amazonaws.com/onca/xml?Service=AWSMechanicalTurkRequester &AWSAccessKeyId=[the Requester's Access Key ID] &Operation=CreateQualificationType &Signature=[signature for this request] &Timestamp=[your system's local time] &Name=EnglishWritingAbility &Description=The%20ability%20to%20write%20and%20edit%20text... &QualificationTypeStatus=Active
A request to the Mechanical Turk Service includes parameters that control its behavior and the data it returns. Required parameters must be included for the request to succeed.
CreateQualificationType accepts parameters common to all operations. Some common parameters are required. See Common Parameters for more information.
The following parameters are specific to the CreateQualificationType operation:
| Name | Description | Type | Value |
|---|---|---|---|
| Operation |
The operation to call. To access the CreateQualificationType operation, set the Operation parameter to CreateQualificationType. |
Required |
CreateQualificationType |
| Name |
The name of the Qualification type. The type name is used to represent the Qualification to Workers, and to find the type using a Qualification type search. The name of a Qualification type must be unique across all of the Qualification types created by this author. To other users, a Qualification type is known by its author and its name. |
Required |
A string |
| Description |
A long description for the Qualification type. On the Mechanical Turk web site, the long description is displayed when a user examines a Qualification type. The description must be less than or equal to 2,000 characters in length. |
Required |
A string |
| Keywords |
One or more words or phrases that describe the Qualification type, separated by commas. A type's Keywords make the type easier to find using a search. The complete string of keywords, including commas and spaces, must be less than or equal to 1,000 characters in length. |
Optional |
A string |
| RetryDelayInSeconds |
An amount of time after taking the Qualification test a user must wait before the user can take it again. A user may wish to 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 the user would like a better score. If RetryDelayInSeconds is not specified, then retries are disabled. A user can request a Qualification of this type only once, even if the user has not been granted the Qualification. |
Optional |
A number of seconds, as a non-negative integer |
| QualificationTypeStatus |
The initial 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. If a Qualification type is Active, a user can take a Qualification test to receive the Qualification, and HITs can include requirements based on the type. If the QualificationTypeStatus is Inactive, users may not apply for the Qualification, and newly created HITs may not use the type for their requirements. If a type becomes Inactive, HITs created while the type was Active that have not yet expired may continue to be accepted by Workers whose Qualifications meet the requirements. Qualification requests that were submitted while the type was Active may be completed and the Qualification granted by the author. However, the author may have no need to grant such requests if the type is being disabled. |
Required |
Active | Inactive |
| Test |
The questions for a Qualification test a user must answer correctly to obtain a Qualification of this type. The value of this parameter is an XML data structure. See the QuestionForm data structure for more information. A Qualification test is optional. If omitted, a user may request the Qualification without answering any questions. The Qualification author specifies the value of the Qualification in the call to GrantQualification. Test must be specified if AnswerKey is present. |
Optional |
XML data for the Qualification test, a QuestionForm data structure |
| AnswerKey |
The answers to the Qualification test specified in the Test parameter. If an answer key is provided for a test, Mechanical Turk will process requests for the Qualification automatically, assigning the user a Qualification with a value calculated from the answer key and the answers submitted by the user. The value of this parameter is an XML data structure. See the AnswerKey data structure for more information. The answer key is optional. If an answer key is not provided with a test, Qualification requests must be processed manually by the Qualification author. The user's test answers will be included in the response from the GetQualificationRequests operation. |
Optional |
XML data for the answer key, an AnswerKey data structure |
| TestDurationInSeconds |
An amount of time a user has from requesting the Qualification to complete the Qualification test. If the user does not submit test answers before this duration has elapsed after requesting the Qualification, the request is voided. The user must then wait for the RetryDelayInSeconds to elapse before requesting the Qualification again. If test retries are disabled (if RetryDelayInSeconds is not specified) and the TestDurationInSeconds elapses before the user submits test answers, the user will not be able to request the Qualification again, nor will the user be able to submit test answers. You may wish to allow retries, or not specify a test duration, to ensure users are not prevented from receiving the Qualification unnecessarily. |
Optional |
A number of seconds, as a positive integer |
A successful request for the CreateQualificationType operation will have a QualificationType element in the response.
The QualificationType element contains a Qualification type data structure. For a description of this data structure, see the Qualification Type Data Structure.