Task delivery schema

Whether you get your delivered tasks by polling or via callback, you can get a description of the format of the answers you should expect through the delivery schema endpoint.

Polling

You can use the polling delivery API to get tasks delivered since a given date or get tasks delivered since the last time you called. For the second endpoint, you can provide a token to identify a particular API user, so multiple people in your organization can poll for delivered tasks at their own pace.

Task delivery callback

If you provide a delivery callback, we will call that callback for every task that is delivered. The advantage of this method is that you get notified of new deliveries right away, and can even reject a task by returning a rejection response from the callback.

Sama Platform HTTP request

Sama Platform will send an API request when a task has been completed, reviewed, and accepted by the workers in our delivery centers.

Method:POST

Header: Content-Type: application/json

URL: delivery callback url defined during project set up

Authentication: Callbacks can be authenticated in one of the following ways:

basic http auth (specify a username/password)
access_key (specify an access_key in the callback URL)
token based (specify a token in an X-Auth-Token header)
HMAC-SHA-256 (specify the X-wsm-date and signed Authorization header)

Body: Example callback for Image with a Caption task.

{
  "task": {
    "id": "51e77305ff1d8131a4000011",
    "project_id": 117,
    "created_at": "20130715T04:45:57",
    "state": "completed",
    "batch_id": 1,
    "client_batch_id": "abc",
    "data": {
      "img": "http: //static.samasource.org/samasource/images/logo.png",
      "caption": "SamaLogo"
    },
    "answers": {
      "in_color": "true",
      "jpeg": "false"
    }
  }
}

User HTTP response

The response that your callback sends back to Sama Platform will determine what happens to the task.

Success

Sama Platform consider that the task has been successfully delivered.

Code: 200

Body: Not required

Failure

Any response code other than 200 or 409 will be treated as a failed delivery. The system will attempt to re-deliver the task after 10 minutes. Continued attempts to deliver the task will be made with the wait time doubling between attempts until the wait time reaches 24 hours. Daily delivery attempts will continue for two weeks. A notification will be generated to our delivery team with a daily summary of failed attempts.

Advanced task delivery

Rejection

If you are receiving delivered tasks via callback, you can reject tasks at the moment of delivery by returning a rejection response, and Sama Platform will set a task to the rejected state with this response. Rejected tasks are sent to the top of the queue to be reworked as soon as possible. To help our Delivery Centers make appropriate corrections, rejection responses must also include rejection reason(s) in the body in JSON format. If a rejection reason is not included, the task will not be set to a rejected or delivered state, and continued delivery attempts will be made. You may choose to provide either a single reason or an array of reasons as shown below.

Code: 409

Header: Content-Type: application/json

Body (with reason key): Example when providing a single reason

{
  "reason": "This image is not in color"
}

Body (with reasons key): Example when providing one or more reasons

{
  "reasons": ["This image is not in color", "This image is a JPEG file"]
}

With polling delivery you can still reject tasks, but you need to use the rejection endpoint after you have got them. That endpoint uses the same rejection reason format as the rejection response to the callback.

Submit a task

For some workflows, agents will not be working in Sama Platform, but for QA and tracking purposes you still might need to submit task answers as if an agent had worked on them in Sama Platform. Please see the documentation of the submit task endpoint for further instructions.

Task Acknowledgement

After receiving a task through any of the options for task delivery, you can mark tasks as acknowledged using the acknowledge endpoint. This marks that the tasks have passed any internal quality review process and have been accepted by the client.