Shared Workforce API guide

Hello and welcome to the Shared Workforce API documentation. If you have questions or need help you can join us in our public campfire room or send an email to

Shared Workforce Tasks

A "Task" is a single unit of work about a piece of content you specify, for which you can request one or more human sourced responses.

5 types of task are currently supported:

  • Tagging (or categorizing) text or an image
  • Choosing a single option from a list
  • Editing text
  • Rotating images
  • Cropping images

For each task you can provide text content, an image url or both.

We are considering adding new types of content based on feedback and suggestions. Please get in touch if you have a task that isn't covered by these options.

Publishing Tasks

Tasks are published through our REST API which supports JSON and XML. We also provide an official client library for Ruby on Rails (screencast), and various PHP examples.

Multiple responses (answers)

For each task, you can request either a single response (the default) or multiple responses. Multiple responses are useful when you need a higher degree of confidence in the answer. In both cases we send you all the answers and it's up to you to decide what to do with them in your own code.

Getting answers

If you register a web hook when creating your task we will send the answers to your URL when the task is completed. If you are testing on a development server, you can optionally use the REST API to periodically check for answers. (The Ruby client provides a rake task for convenience.)


To get the most out of Shared Workforce, we recommend that you note the following guidelines:

  • Make your directions and options very clear and descriptive. Avoid subjectivity.
  • Use multiple responses for mission critical assessments.
  • Tasks should take on average 10 seconds or less to complete.
  • Split complicated tasks down in to smaller ones.

But most of all don't worry too much — we will monitor your task for quality and accuracy and suggest improvements where necessary.

Getting started

Ruby on Rails users

  1. Read the Shared Workforce Gem documentation.
  2. View the source code on Github.
  3. Report a problem or bug in Github Issues.
  4. Watch our getting started with Ruby on Rails screencast:


PHP users

Other languages and frameworks

If you use another language or framework that you would like to use with Shared Workforce, you should be able to use the standard REST API. If you need help with your integration or would like to help with writing a client or some documentation for your preferred platform, please have a chat to us in our public campfire room or send an email to