CreateHIT

Prev		Next

Description

The CreateHIT operation creates a new HIT. The new HIT is made available for Workers to find and accept on the Mechanical Turk web site.

Once a HIT has been created, it cannot be deleted. A HIT may be removed from the web site using the DisableHIT operation, but Workers that have already accepted the HIT will still be allowed to submit results to claim rewards. See DisableHIT for more information.

Most fields of a HIT cannot be changed after the HIT has been created. The ExtendHIT operation can increase the maximum number of assignments (MaxAssignments) and the expiration date (LifetimeInSeconds).

HIT Types

Most uses of Mechanical Turk involve submitting many HITs that are similar, differing only in the details of the questions they are asking. To present these HITs in a convenient way, Mechanical Turk groups together HITs that have identical values for a set of common properties. These properties define a HIT type.

The HIT properties that define a HIT type are the following:

Title
Description
Keywords
Reward
AssignmentDurationInSeconds
AutoApprovalDelayInSeconds
a set of zero or more QualificationRequirements

You can register a new HIT type by calling the RegisterHITType operation with values for the HIT type properties. RegisterHITType returns a HIT type ID that refers to the properties, and corresponds with every HIT of that type.

You can use the HIT type ID to create a HIT of that type by calling the CreateHIT operation with the ID, along with values for the properties that are not part of the HIT type (such as the HIT's Question data).

To create a HIT without a HIT type ID, you can call the CreateHIT operation with the values of the HIT type properties themselves. If a HIT type already exists with the given values, the new HIT is assigned the existing HIT type ID. If a HIT type does not exist for those values, a new HIT type is created. In either case, the HIT type ID is returned with the HIT data in the response from the CreateHIT operation.

Note:

There are two ways to call the CreateHIT operation: with the HIT type ID, or with the common property values. If the HITTypeId parameter is specified, CreateHIT assumes the syntax with a HIT type ID is what is intended. If you accidentally provide both a HIT type ID and values for the common properties, the common property values will be ignored.

For more information about HIT types, see HIT Types.

Sample Request: Using CreateHIT With a HIT Type ID (REST)

The following example of a call to the CreateHIT operation creates a simple HIT, using an explicit HIT type ID.

http://mechanicalturk.amazonaws.com/onca/xml?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2006-08-23
&Operation=CreateHIT
&Signature=[signature for this request]
&Timestamp=[your system's local time]
&HITTypeId=T100CN9P324W00EXAMPLE
&Question=[URL-encoded question data]
&LifetimeInSeconds=604800

The Question parameter takes a block of XML data as its value. See the QuestionForm data structure and the ExternalQuestion data structure for more information.

Sample Request: Using CreateHIT Without a HIT Type ID (REST)

The following example of a call to the CreateHIT operation creates a simple HIT with some properties, letting Mechanical Turk determine the HIT type ID from the property values.

http://mechanicalturk.amazonaws.com/onca/xml?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2006-08-23
&Operation=CreateHIT
&Signature=[signature for this request]
&Timestamp=[your system's local time]
&Title=Location%20and%20Photograph%20Identification
&Description=Select%20the%20image%20that%20best%20represents...
&Reward.1.Amount=5
&Reward.1.CurrencyCode=USD
&Question=[URL-encoded question data]
&AssignmentDurationInSeconds=30
&LifetimeInSeconds=604800
&Keywords=location,%20photograph,%20image,%20identification,%20opinion

The Question parameter takes a block of XML data as its value. See the QuestionForm data structure and the ExternalQuestion data structure for more information.

Request Parameters

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.

CreateHIT accepts parameters common to all operations. Some common parameters are required. See Common Parameters for more information.

Calling CreateHIT With a HIT Type ID

The following parameters are specific to calling the CreateHIT operation with an explicit HIT type ID:

Name	Description	Type	Value
`Operation`	The operation to call. To access the `CreateHIT` operation, set the `Operation` parameter to `CreateHIT`.	Required	`CreateHIT`
`HITTypeId`	The HIT type ID.	Required	A valid HIT type ID
`Question`	The data the person completing the HIT will use to produce the results. The value of this parameter is an XML data structure. See the QuestionForm data structure and the ExternalQuestion data structure for more information. The XML Question data must not be larger than 64 kilobytes (65,536 bytes) in size, including whitespace.	Required	XML data for the question, a QuestionForm data structure or an ExternalQuestion data structure
`LifetimeInSeconds`	An amount of time after which the HIT will no longer be available for users to accept. After the HIT's lifetime has elapsed, the HIT will no longer appear in HIT searches, even if not all of the HIT's assignments have been accepted. `LifetimeInSeconds` must be an integer between `30` (30 seconds) and `31536000` (365 days).	Required	A number of seconds, as a positive integer
`MaxAssignments`	The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Each Worker can complete a HIT only once, so multiple assignments are guaranteed to be completed by multiple Workers. If not specified, the HIT will have a `MaxAssignments` of 1. Only one user can accept the HIT at a time. Once the HIT is complete, it is no longer available for other users to accept. `MaxAssignments` must be between `1` and `1000000000` (1 billion).	Optional	A positive integer
`RequesterAnnotation`	An arbitrary data field. The `RequesterAnnotation` parameter lets your application attach arbitrary data to the HIT for tracking purposes. For example, the `RequesterAnnotation` could be an identifier internal to the Requester's application that corresponds with the HIT. A HIT's `RequesterAnnotation` is only visible to the Requester that created the HIT. It is not shown to the Worker, or any other Requester. The `RequesterAnnotation` may be different for each HIT you submit. It will not affect how your HITs are grouped. The `RequesterAnnotation` must not be longer than 255 characters.	Optional	A string

Calling CreateHIT Without a HIT Type ID

The following parameters are specific to calling the CreateHIT operation without a HIT type ID, letting Mechanical Turk determine the HIT type from the property values:

Name	Description	Type	Value
`Operation`	The operation to call. To access the `CreateHIT` operation, set the `Operation` parameter to `CreateHIT`.	Required	`CreateHIT`
`Title`	The title of the HIT. A title should be short and descriptive about the kind of task the HIT contains. On the Mechanical Turk web site, the HIT title appears in search results, and everywhere the HIT is mentioned.	Required	A string, up to 128 characters in length
`Description`	A general description of the HIT. A description includes detailed information about the kind of task the HIT contains. On the Mechanical Turk web site, the HIT description appears in the expanded view of search results, and in the HIT and assignment screens. A good description gives the user enough information to evaluate the HIT before accepting it. Though the description is displayed while a Worker completes the HIT, the `Question` data should include the complete instructions for completing the HIT. The Worker may not know to look for instructions in the HIT's description. The description must be less than 2,000 characters in length.	Required	A string
`Question`	The data the person completing the HIT will use to produce the results. The value of this parameter is an XML data structure. See the QuestionForm data structure and the ExternalQuestion data structure for more information.	Required	XML data for the question, a QuestionForm data structure or an ExternalQuestion data structure
`Reward`	The amount of money the Requester will pay a user for successfully completing the HIT. The value is a Price data structure. For more information, see the Price Data Structure.	Required	A Price data structure
`AssignmentDurationInSeconds`	The amount of time a user has to complete the HIT after accepting it. If a user does not complete their assignment in the specified duration, the assignment is considered abandoned. If the HIT is still active (its lifetime has not elapsed), the assignment becomes available for other users to find and accept. `AssignmentDurationInSeconds` must be between `30` (30 seconds) and `31536000` (365 days).	Required	A number of seconds, as a positive integer
`LifetimeInSeconds`	An amount of time after which the HIT will no longer be available for users to accept. After the HIT's lifetime has elapsed, the HIT will no longer appear in HIT searches, even if not all of the HIT's assignments have been accepted. `LifetimeInSeconds` must be an integer between `30` (30 seconds) and `31536000` (365 days).	Required	A number of seconds, as a positive integer
`Keywords`	One or more words or phrases that describe the HIT, separated by commas. Searches for words similar to a HIT's keywords are more likely to return the HIT in the search results. The complete string of keywords, including commas and spaces, must be fewer than 1,000 characters.	Optional	A string
`MaxAssignments`	The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Each Worker can complete a HIT only once, so multiple assignments are guaranteed to be completed by multiple Workers. If not specified, the HIT will have a `MaxAssignments` of 1. Only one user can accept the HIT at a time. Once the HIT is complete, it is no longer available for other users to accept. `MaxAssignments` must be between `1` and `1000000000` (1 billion).	Optional	A positive integer
`AutoApprovalDelayInSeconds`	An amount of time after an assignment for the HIT has been submitted, after which the assignment will be considered "approved" automatically unless the Requester explicitly rejects it. If not specified, the auto-approval delay is set to the maximum value of 30 days (`2592000` seconds). In most cases, the Requester will be able to retrieve and approve answers directly before the auto-approval delay elapses. The maximum value assures that the Worker will get paid even if the Requester is unavailable. A Requester may wish to specify a shorter auto-approval delay if the Workers are trusted (such as by having been vetted with high Qualification requirements) and to assure Workers that they will be paid in a timely manner. There is no way to automatically reject results. To reject results, the Requester must explicitly call the `RejectAssignment` method. Once an assignment has been approved, it cannot be rejected, and payment cannot be reversed. `AutoApprovalDelayInSeconds` must be between `3600` (1 hour) and `2592000` (30 days).	Optional	A number of seconds, as a positive integer
`QualificationRequirement`	A condition that a Worker's Qualifications must meet before the Worker is allowed to accept and complete the HIT. The condition specifies that the Worker must have a Qualification of a particular Qualification type, and that its value must compare to the requirement's value in the specified way: equal to, not equal to, less than, less than or equal to, greater than or equal to, or greater than. A HIT may have between zero and ten (10) Qualification requirements. All requirements must be met by a Worker's Qualifications for the Worker to accept the HIT. All of a HIT's Qualification requirements must be based on Qualification types with an "active" status. If any requirement is based on a Qualification type with an "inactive" status, the call to `CreateHIT` will fail. The value of this element is a Qualification requirement data structure. For more information, see the QualificationRequirement Data Structure.	Optional	A Qualification requirement data structure
`RequesterAnnotation`	An arbitrary data field. The `RequesterAnnotation` parameter lets your application attach arbitrary data to the HIT for tracking purposes. For example, the `RequesterAnnotation` could be an identifier internal to the Requester's application that corresponds with the HIT. A HIT's `RequesterAnnotation` is only visible to the Requester that created the HIT. It is not shown to the Worker, or any other Requester. The `RequesterAnnotation` may be different for each HIT you submit. It will not affect how your HITs are grouped. The `RequesterAnnotation` must not be longer than 255 characters.	Optional	A string

Responses

A successful request for the CreateHIT operation will have a HIT element in the response.

The HIT element contains the newly created HIT data. For a description of the HIT data structure as it appears in responses, see the HIT Data Structure.