HIT

Description

The HIT data structure represents a single HIT, including all the information necessary for a Worker to accept and complete the HIT and claim the reward.

The HIT data structure is used as a response element for the following operations:

CreateHIT
DisableHIT
GetHIT
GetReviewableHITs
SearchHITs

HITs and Response Groups

Operations that return a HIT data structure use response groups to determine how much information to return. As described in Common Parameters, the ResponseGroup parameter specifies which sets of elements the service should return, as a set of named groups. For example, the Request response group includes the contents of the operation request in the response.

For the HIT data structure, the Minimal response group returns the HITId. To also return the HIT's Question data, include the HITQuestion response group. To include the other properties of the HIT, specify the HITDetail response group. Finally, specify the HITAssignmentSummary response group to include information on the number of assignments that are available for Workers to accept, accepted and pending submission of results, or completed.

The GetHIT operation returns the HITDetail, HITQuestion and Minimal response groups by default. The HITAssignmentSummary response group is off by default.

The SearchHITs operation includes HITDetail, Minimal, and HITAssignmentSummary as default response groups. You can also specify HITQuestion with SearchHITs.

CreateHIT and DisableHIT can also return additional HIT fields, but their default is Minimal.

Currently, the GetReviewableHITs operation only supports the Minimal response group. To retrieve additional HIT data for HITs returned by this operation, use the HIT IDs in the results with GetHIT.

Sample: CreateHIT

The following example of the HIT data structure could be returned by a call to the CreateHIT operation. CreateHIT returns an element named HIT, that represents the HIT that was created by the call.

<HIT>
  <HITId>123RVWYBAZW00EXAMPLE</HITId>
  <HITTypeId>T100CN9P324W00EXAMPLE</HITTypeId>
  <CreationTime>2005-06-30T23:59:59</CreationTime>
  <HITStatus>Assignable</HITStatus>
  <MaxAssignments>5</MaxAssignments>
  <AutoApprovalDelayInSeconds>86400</AutoApprovalDelayInSeconds>
  <LifetimeInSeconds>86400</LifetimeInSeconds>
  <AssignmentDurationInSeconds>300</AssignmentDurationInSeconds>
  <Reward>
    <Amount>25</Amount>
    <CurrencyCode>USD</CurrencyCode>
    <FormattedPrice>$0.25</FormattedPrice>
  </Reward>
  <Title>Location and Photograph Identification</Title>
  <Description>Select the image that best represents...</Description>
  <Keywords>location, photograph, image, identification, opinion</Keywords>
  <Question>
    &lt;QuestionForm&gt;
      [XML-encoded Question data]
    &lt;/QuestionForm&gt;
  </Question>
  <QualificationRequirement>
    <QualificationTypeId>789RVWYBAZW00EXAMPLE</QualificationTypeId>
    <Comparator>GreaterThan</Comparator>
    <Value>18</Value>
  </QualificationRequirement>
  <HITReviewStatus>NotReviewed</HITReviewStatus>
</HIT>

Elements

The HIT structure may contain the following elements.

Name	Description	Value
`HITId`	A unique identifier for the HIT. A HIT is given a HIT ID when `CreateHIT` is called, and it retains that ID forever.	A valid HIT ID
`HITTypeId`	The ID of the HIT type of this HIT.	A valid HIT type ID
`CreationTime`	The date and time the HIT was created.	A dateTime in the Coordinated Universal Time (Greenwich Mean Time) time zone, such as `2005-01-31T23:59:59Z`
`Title`	The title of the HIT.	A string
`Description`	A general description of the HIT.	A string
`Keywords`	One or more words or phrases that describe the HIT, separated by commas. Search terms similar to a HIT's keywords are more likely to have the HIT in the search results.	A string
`HITStatus`	The status of the HIT and its assignments. A HIT with a status of `Assignable` is ready to be found and accepted by Workers. A HIT begins in the `Assignable` status, and remains `Assignable` until `MaxAssignments` assignments are in progress, or until the HIT's `LifetimeInSeconds` has elapsed. A HIT with a status of `Unassignable` is no longer available to be accepted by Workers, and has one or more assignments in progress. A HIT remains `Unassignable` until all assignments have been submitted, returned or abandoned. A HIT with a status of `Reviewable` has submitted results for `MaxAssignments` assignments, or the HIT's `LifetimeInSeconds` has elapsed and all assignments that were in progress have been submitted, returned or abandoned. A Requester can retrieve all HITs with this status using the `GetReviewableHITs` operation. When a HIT is `Reviewable`, the Requester can retrieve the results, and approve or reject the assignments. A HIT has a status of `Reviewing` after the Requester calls the `SetHITAsReviewing` operation. Only `Reviewable` HITs can be moved to this status. The same operation can move the HIT back to the `Reviewing` status. A HIT has a status of `Disposed` after `DisposeHIT` has been called for the HIT. Because a HIT may be removed from the system at any time after being disposed, calling `GetHIT` for a disposed HIT may return the HIT with this status, or it may return nothing.	`Assignable` \| `Unassignable` \| `Reviewable` \| `Reviewing` \| `Disposed`
`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.	A Price data structure
`LifetimeInSeconds`	An amount of time after which the HIT will no longer be available for users to accept. The HIT becomes unavailable even if the requested number of assignments, specified by `MaxAssignments`, has not yet been fulfilled. The initial `LifetimeInSeconds` value is specified as a parameter to `CreateHIT`. When the HIT is created, the HIT's life begins, and this value begins counting down. When the HIT data is returned by the service, such as from a call to `GetHIT`, the `LifetimeInSeconds` value represents how much time remains until the HIT expires from the time the operation call is complete.	A number of seconds, as a positive integer
`AssignmentDurationInSeconds`	The length of time a user has to complete the HIT after accepting it. If a user does not complete the assignment in the specified duration, the assignment is considered abandoned. If the HIT is still active (it has not expired), the assignment becomes available for other users to find and accept.	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 value is 1.	A positive integer
`AutoApprovalDelayInSeconds`	An amount of time after an assignment for the HIT has been submitted by the Worker after which the results ought to automatically be considered "approved" by the Requester.	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 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 Qualification requirements. All requirements must be met by a Worker's Qualifications for the Worker to accept the HIT. The value of this element is a Qualification requirement data structure. For more information, see the QualificationRequirement Data Structure.	A Qualification requirement data structure
`Question`	The data the Worker completing the HIT will use to produce the results. This value is an XML data structure. See the QuestionForm data structure and the ExternalQuestion data structure for more information.	XML data for the question, a QuestionForm data structure or an ExternalQuestion data structure
`RequesterAnnotation`	An arbitrary data field for use by the Requester that created the HIT. This field is only visible to the creator of the HIT.	A string
`NumberOfSimilarHITs`	The number of HITs whose fields are identical to this HIT, other than the `Question` field. See the documentation for the `CreateHIT` operation for a description of HIT similarity.	A non-negative integer
`HITReviewStatus`	If a HIT is submitted that violates Mechanical Turk's policies for appropriate content, a Mechanical Turk user can request that a HIT be reviewed by an administrator. `HITReviewStatus` indicates whether the HIT has not been reviewed, has been marked for review by a user, or has been reviewed by an administrator and deemed appropriate or inappropriate.	`NotReviewed` \| `MarkedForReview` \| `ReviewedAppropriate` \| `ReviewedInappropriate`
`NumberOfAssignmentsPending`	The number of assignments for this HIT that are currently in progress by Workers. These assignments have been accepted by Workers, but have not yet been submitted or returned or abandoned. This element is returned only if the `HITAssignmentSummary` response group is specified.	A non-negative integer
`NumberOfAssignmentsAvailable`	The number of assignments for this HIT that are available for Workers to accept. Up to this many Workers can accept the HIT before the HIT expires. This element is returned only if the `HITAssignmentSummary` response group is specified.	A non-negative integer
`NumberOfAssignmentsCompleted`	The number of assignments for this HIT that have been approved or rejected. This is the number of Workers that have submitted results for this HIT, which is also the number of result sets that can be retrieved by calling the `GetAssignmentsForHIT` operation. This element is returned only if the `HITAssignmentSummary` response group is specified.	A non-negative integer