CreateHIT

Description

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

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, the CreateHIT operation assumes the syntax with a HIT type ID is what you intended. If you accidentally provide both a HIT type ID and values for the common properties, the common property values will be ignored.

Request Parameters

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

The following tables describe the additonal parameters required to call the CreateHIT operation with an explicit HIT type ID and without a HIT type ID.

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	Required
`Operation`	The name of the operation Type: String Valid Values: CreateHIT Default: None	Yes
`HITTypeId`	The HIT type ID Type: String Default: None	Yes
`Question`	The data the person completing the HIT uses to produce the results. Type: String Default: None Constraints: must be a QuestionForm data structure or an ExternalQuestion data structure. The XML Question data must not be larger than 64 kilobytes (65,535 bytes) in size, including whitespace.	Yes
`LifetimeInSeconds`	The number of seconds after which the HIT is no longer available for users to accept. After the lifetime of the HIT has elapsed, the HIT no longer appears in HIT searches, even if not all of the HIT's assignments have been accepted. Type: positive integer Valid Values: any integer between 30 (30 seconds) and 31536000 (365 days). Default: None	Yes
`MaxAssignments`	The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Type: positive integer Valid Values: any integer between 1 and 1000000000 (1 billion). Default: 1	No
`RequesterAnnotation`	An arbitrary data field. The `RequesterAnnotation` parameter lets your application attach arbitrary data to the HIT for tracking purposes. For example, this parameter could be an identifier internal to the Requester's application that corresponds with the HIT. The `RequesterAnnotation` parameter for a HIT is only visible to the Requester who created the HIT. It is not shown to the Worker, or any other Requester. The `RequesterAnnotation` paramter may be different for each HIT you submit. It does not affect how your HITs are grouped. Type: String Default: None Constraints: must not be longer than 255 characters	No

Calling `CreateHIT` Without a HIT Type ID

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

Name	Description	Required
`Operation`	The name of the operation Type: String Valid Values: CreateHIT Default: None	Yes
`Title`	The title of the HIT. A title should be short and descriptive about the kind of task the HIT contains. On the Amazon Mechanical Turk web site, the HIT title appears in search results, and everywhere the HIT is mentioned. Type: String Default: None Constraints: must not be more than 128 characters	Yes
`Description`	A general description of the HIT. A description includes detailed information about the kind of task the HIT contains. On the Amazon 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. Type: String Default: None Constraints: cannot be more than 2,000 characters in length	Yes
`Question`	The data the person completing the HIT uses to produce the results. Type: String Default: None Constraints: Must be a QuestionForm data structure or an ExternalQuestion data structure. The XML Question data must not be larger than 64 kilobytes (65,535 bytes) in size, including whitespace.	Yes
`Reward`	The amount of money the Requester will pay a Worker for successfully completing the HIT. Type: Price data structure. Default: None	Yes
`AssignmentDurationInSeconds`	The amount of time, in seconds, that a Worker has to complete the HIT after accepting it. If a Worker does not complete the assignment within the specified duration, the assignment is considered abandoned. If the HIT is still active (that is, its lifetime has not elapsed), the assignment becomes available for other users to find and accept. Type: positive integer Valid Values: any integer between 30 (30 seconds) and 31536000 (365 days). Default: None	Yes
`LifetimeInSeconds`	An amount of time, in seconds, after which the HIT is no longer available for users to accept. After the lifetime of the HIT elapses, the HIT no longer appears in HIT searches, even if not all of the assignments for the HIT have been accepted. Type: positive integer Valid Values: any integer between 30 (30 seconds) and 31536000 (365 days). Default: None	Yes
`Keywords`	One or more words or phrases that describe the HIT, separated by commas. These words are used in searches to find HITs. Type: String Default: None Constraints: The complete string of keywords, including commas and spaces, canot be more than 1,000 characters.	No
`MaxAssignments`	The number of times the HIT can be accepted and completed before the HIT becomes unavailable. Type: positive integer Valid Values: any integer between 1 and 1000000000 (1 billion). Default: 1	No
`AutoApprovalDelayInSeconds`	The number of seconds after an assignment for the HIT has been submitted, after which the assignment is considered Approved automatically unless the Requester explicitly rejects it. Type: non-negative integer Valid Values: any integer between 0 (auto-approve results as soon as they are submitted) and 2592000 (30 days). Default: 2592000 (30 days)	No
`QualificationRequirement`	A condition that a Worker's Qualifications must meet before the Worker is allowed to accept and complete the HIT. Type: a QualificationRequirement data structure. Default: None Constraints: there can be no more than 10 `QualificationRequirement` data structures for each HIT.	No
`RequesterAnnotation`	An arbitrary data field. The `RequesterAnnotation` parameter lets your application attach arbitrary data to the HIT for tracking purposes. For example, the `RequesterAnnotation` parameter could be an identifier internal to the Requester's application that corresponds with the HIT. Type: String Default: None Constraints: must not be longer than 255 characters	No

Response Elements

A successful request for the CreateHIT operation includes the elements described in the following table.

Name	Description
`HIT`	Contains the newly created HIT data. For a description of the HIT data structure as it appears in responses, see the HIT Data Structure.

Examples

The following examples show how to use the CreateHIT operation.

Sample Request

The following are examples of REST requests.

Example Request (Query) Using CreateHIT with a HIT Type ID

The following example creates a simple HIT, using an explicit HIT type ID. 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.

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

Example Request (Query) Using CreateHIT Without a HIT Type ID

The following example creates a simple HIT with some properties, letting Amazon Mechanical Turk determine the HIT type ID from the property values. 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.

http://mechanicalturk.amazonaws.com/?Service=AWSMechanicalTurkRequester
&AWSAccessKeyId=[the Requester's Access Key ID]
&Version=2008-08-02
&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

Sample Response

Amazon Mechanical Turk might return the following response for either of the preceeding requests.

<CreateHITResponse>
  <OperationRequest>
    <RequestId>ece2785b-6292-4b12-a60e-4c34847a7916</RequestId>
  </OperationRequest>
  <HIT>
    <Request>
      <IsValid>True</IsValid>
    </Request>
    <HITId>GBHZVQX3EHXZ2AYDY2T0</HITId>
    <HITTypeId>NYVZTQ1QVKJZXCYZCZVZ</HITTypeId>
  </HIT>
</CreateHITResponse>