REST API

Shared Workforce offers a simple API to access small units of human intelligence as if it was any other online resource.

If you just want to get started with the REST API, you can read on for the quick start guide. If you're ready for a little more detail, you can skip to the full REST API reference guide.

Quick start

Send us your request as json or XML. Here is an example using CURL:

curl -i -H "X-API-Key: acdc30b2-14c5-46ee-ba35-11d50edc65ec" -H "Content-Type: application/vnd.com.sharedworkforce.text+json" -H "Accept: application/json" -X POST -d '{"task": {"title": "Remove offensive language", "instruction": "Edit the text to remove any offensive language.", "text": "My name is Dougie, and I am a massive Crystal Palace Fan.", "answer_type": "edit", "callback_url": "https://your-site.example.com/process_task_response"}}' "https://api.sharedworkforce.com/tasks"

This is a basic example. There are different types of task to choose from. See Creating Tasks for a full list.

Once your task has been completed, we will POST your callback_url with the response:

Content-Type: application/vnd.com.sharedworkforce.text+json
X-API-Key: acdc30b2-14c5-46ee-ba35-11d50edc65ec
Link: <https://sharedworkforce.com/tasks/501234>; rel="response"
{
  "task": {
    "title": "Remove offensive language",
    "id": 501234,
    "responses": [
      "answer": "My name is Dougie.",
      "id": "34562"
    ]
  }
}

API Endpoint

https://api.sharedworkforce.com

Note: All requests must be sent through https not http.

Routes

/tasks
GET, POST
/tasks/available
GET
/tasks/completed
GET
/tasks/{id}
GET, PUT, DELETE
/tasks/{id}/responses
GET

Content Types

The API supports JSON or XML content types. Request content types should be set in the HTTP header, like so:

JSON

Content-Type: application/vnd.com.sharedworkforce.text+json

XML

Content-Type: application/vnd.com.sharedworkforce.text+xml

Authentication

There are 2 ways to authenticate with the application:

  1. The X-API-Key HTTP header (preferred)

    Example Header

    X-API-Key: b94d27b9…
  2. Including your API key in the request params

HTTP Status Codes

202: Accepted
Your request has been accepted and will be processed.
400: Bad Request
Your request syntax is incorrect or you have forgotten a field.
401: Unauthorised
Your API key was not supplied or is incorrect.
402: Payment Required
You do not have enough credits remaining on your subscription to publish any more tasks.
406: Not Acceptable
Your request did not contain the Shared Workforce MIME type in the accept headers.

Creating Tasks

A task represents a single job that is to be completed or processed by a worker on Shared Workforce.

Request Parameters

api_key
Your API key (only required if it's not included in the headers)
<string>
responses_required
The number of human responses you would like for this task
<integer>
title
What you'd like to call the task. e.g. Check gender from photo.
<string>
instruction
The actions a worker should take to complete the task. e.g. Look at this photo. Is the person male or female?
<string>
guidelines
More detailed guidelines about how to correctly answer your task. Accepts Markdown formatted text.
<string>
image_url
The url of an image to include in the task content. sharedworkforce.com must be authorised to see the photo.
<string>
image_crop_ratio
The ratio of width to height for the crop area (e.g. 1 for square)
<float>
image_min_width
The minimum crop width.
<integer>
image_min_height
The minimum crop height.
<integer>
text
The text in question (to be included in the task content).
<string>
answer_type
One of the following: "choice", "tags", "edit", "crop" or "rotate"
<string>
answer_options
The options for the worker to choose from e.g. ["Male", "Female"]. Not required when answer_type is "edit".
<array_of_strings>
callback_url
Where we will POST the response when ready.
<string>
callback_params
Data that will be sent back with the response (JSON or XML).

JSON Example

POST to https://sharedworkforce.com/tasks

Content-Type: application/vnd.com.sharedworkforce.text+json
X-API-Key: acdc30b2-14c5-46ee-ba35-11d50edc65ec

{
  "task": {
    "title": "Remove offensive language",
    "instruction": "Edit the text to remove any offensive language.",
    "text": "My name is Dougie, and I'm a massive Crystal Palace Fan.",
    "answer_type": "edit",
    "callback_url": "http://my-website.example.com/process_task_response",
    "responses_required": 1
  }
}

Web hooks

Web hooks are implemented by defining a callback url when you create a task. We will POST to your callback url when a task is completed.

Callback (POST to https://my-website.example.com/process_task_response):

Content-Type: application/vnd.com.sharedworkforce.text+json
X-API-Key: acdc30b2-14c5-46ee-ba35-11d50edc65ec
Link: <https://api.sharedworkforce.com/tasks/501234>; rel="response"

{ 
  "api_key": "acdc30b2-14c5-46ee-ba35-11d50edc65ec",
  "task": {
    "title": "Remove offensive language",
    "id": 501234,
    "responses": [
      "answer": "My name is Dougie.",
      "id": "34562"
    ]
  }
}

Authorized responses

If you have received a response from Shared Workforce that you are not expecting, the authrized responses API can be used to feed back your expected response.

curl -i -H "X-API-Key: acdc30b2-14c5-46ee-ba35-11d50edc65ec" -H "Content-Type: application/vnd.com.sharedworkforce.text+json" -H "Accept: application/json" -X POST -d '{"authorized_response": {"answer": "Green"}}' "https://api.sharedworkforce.com/tasks/1/authorized_responses"

Request Parameters

api_key
Your API key (only required if it's not included in the headers)
<string>
answer
The response you were expecting
<string> or <object literal>

JSON Example

POST to https://sharedworkforce.com/tasks/:task_id/authorized_responses

Note that the related task id is required in the path.

Content-Type: application/vnd.com.sharedworkforce.text+json
X-API-Key: acdc30b2-14c5-46ee-ba35-11d50edc65ec

{
  "authorized_response": {
    "answer": ['Contains nudity', 'Contains swearing']
  }
}

If you have any further questions about the API or if you need anything clarifying, drop us an email at erica@sharedworkforce.com