Amazon Mechanical Turk
Developer Guide (API Version 2014-08-15)

Making SOAP Requests

This article explains how to make a SOAP request to the Amazon Mechanical Turk web service.

Using SOAP

The Amazon Mechanical Turk web service supports the SOAP message protocol for calling service operations over an HTTP connection. The easiest way to use the SOAP interface with your application is to use a SOAP toolkit appropriate for your platform. SOAP toolkits are available for most popular programming languages and platforms.

The service's Web Services Definition Language (WSDL) file describes the operations and the format and data types of their requests and responses. Your SOAP toolkit interprets the WSDL file to provide your application access to the operations. For most toolkits, your application calls a service operation using routines and classes provided or generated by the toolkit.

The location of the WSDL file is discussed in the section, WSDL Location.


Amazon Mechanical Turk limits the velocity of requests. If you exceed the limit you will receive a 500 or 503 Service Unavailable error. It is highly unlikely that you will reach this limit with normal activity.

Using Operation Parameters With SOAP

The API reference in this guide describes the parameters for each operation and their values. You may find it useful to refer to the WSDL file directly to see how the parameters will appear in the XML of the request generated by your toolkit, and understand how your toolkit will make the operations available to your application code.

The Structure of a Request Message

A SOAP request is an XML data structure generated by your SOAP toolkit and sent to the service. As described by the service WSDL, the root element of this structure is named after the operation, and contains the parameter data for the request.

The root element contains the AWSAccessKeyId, Timestamp, and Signature used to authenticate the request as being sent by you. For more information on these values, see AWS Request Authentication.

In addition to the request authentication parameters, the root element contains a Request element, which contains the parameters of the specific operation being called. For a description of an operation's parameters, see the appropriate page for the operation in the Amazon Mechanical Turk API Reference. The Request element may also contain a ResponseGroup parameter, which controls how much data is returned by the service for an operation.

For more information about these parameters and their values, see Common Parameters.

The XML Message for a GetHIT SOAP Request

The following example is the XML for a SOAP message that calls the GetHIT operation. While you will probably not be building the SOAP message for a service request manually, it is useful to see what your SOAP toolkit will try to produce when provided with the appropriate values. Many SOAP toolkits require that you build a request data structure similar to the XML to make a request.

The GetHIT element contains the parameters common to all requests, and a Request element that contains the operation-specific HITId parameter, along with the ResponseGroup.

The following example calls the GetHIT operation.

<?xml version="1.0" encoding="UTF-8" ?>